Class ImageLayout

Object
ImageLayout
public class ImageLayout extends Object
Preferences about the tiling of an image in relationship with a given image size. Image­Layout contains a preferred tile size, together with methods for deriving an actual tile size for a given image size. The rules for deriving a tile size are configurable by flags.

An image layout can be specified in more details with a Sample­Model. The size of a sample model usually determines the size of tiles, but the former may be replaced by the tile size computed by this Image­Layout class.

This class contains no information about colors. The Color­Model to associate with a Sample­Model is controlled by a separated interface: Colorizer.

Instances of this class are immutable and thread-safe.

Since:
1.5

  • Field Details

    • DEFAULT_TILE_SIZE

      public static final int DEFAULT_TILE_SIZE
      Default width and height of tiles, in pixels. This is currently set to 256 pixels, but may change in any future Apache SIS version.
      See Also:

    • DEFAULT

      public static final ImageLayout DEFAULT
      The default instance with a preferred tile width and height of 256 pixels. Image sizes are preserved but the tile sizes are flexible. The last row and last column of tiles in an image are allowed to be only partially filled.

    • sampleModel

      protected final SampleModel sampleModel
      Preferred sample model, or null if none. The sample model width and height may be replaced by the tile size computed by this Image­Layout class.
      See Also:

    • preferredTileWidth

      protected final int preferredTileWidth
      Preferred size (in pixels) for tiles. The actual tile size will also depend on the size of the image to tile. The default value is 256.
      See Also:

    • preferredTileHeight

      protected final int preferredTileHeight
      Preferred size (in pixels) for tiles. The actual tile size will also depend on the size of the image to tile. The default value is 256.
      See Also:

    • isTileSizeAdjustmentAllowed

      public final boolean isTileSizeAdjustmentAllowed
      Whether to allow changes of tile size when needed. If this flag is false, then suggest­Tile­Size(int, int) unconditionally returns the preferred tile size.

      The default value is true.

      See Also:

    • isImageBoundsAdjustmentAllowed

      public final boolean isImageBoundsAdjustmentAllowed
      Whether to allow changes of image size when needed. An image may be resized when the suggest­Tile­Size(int, int) method cannot find a size close enough to the preferred tile size. For example, if the image width is a prime number, there is no way to divide the image horizontally with an integer number of tiles. The only way to get an integer number of tiles is to change the image size. This is done by changing the fields of the bounds argument given to the suggest­Tile­Size(Rendered­Image, Rectangle) method.

      The default value is false.

      See Also:

    • isPartialTilesAllowed

      public final boolean isPartialTilesAllowed
      Whether to allow tiles that are only partially filled in the last row and last column of the tile matrix. This flag may be ignored (handled as false) when the image for which to compute a tile size is opaque.

      The default value is true.

      See Also:

    • preferredMinTileX

      protected final int preferredMinTileX
      Preferred tile index where images start their tile matrix. This property usually has no incidence on the appearance or performance of an image and may be ignored by image operations. The default value is 0.
      See Also:

    • preferredMinTileY

      protected final int preferredMinTileY
      Preferred tile index where images start their tile matrix. This property usually has no incidence on the appearance or performance of an image and may be ignored by image operations. The default value is 0.
      See Also:

  • Constructor Details

    • ImageLayout

      protected ImageLayout(SampleModel sampleModel, Dimension preferredTileSize, boolean isTileSizeAdjustmentAllowed, boolean isImageBoundsAdjustmentAllowed, boolean isPartialTilesAllowed, Point preferredMinTile)
      Creates a new image layout with the given properties.
      Parameters:
      sample­Model - preferred sample model, or null if none.
      preferred­Tile­Size - preferred tile size, or null for the default size.
      is­Tile­Size­Adjustment­Allowed - whether tile size can be modified if needed.
      is­Image­Bounds­Adjustment­Allowed - whether image size can be modified if needed.
      is­Partial­Tiles­Allowed - whether to allow tiles that are only partially filled.
      preferred­Min­Tile - preferred tile index where image start their tile matrix, or null for (0,0).

  • Method Details

    • withSampleModel

      public ImageLayout withSampleModel(SampleModel model, boolean cascade)
      Returns a new layout with the same properties than this layout except for the sample model. If the given argument value results in no change, returns this.
      Parameters:
      model - the new sample model, or null if none.
      cascade - whether to set the preferred tile size to the size of the given sample model.
      Returns:
      the layout for the given sample model.

    • allowTileSizeAdjustments

      public ImageLayout allowTileSizeAdjustments(boolean allowed)
      Returns a new layout with the same properties than this layout except whether it allows changes of tile size. If the given argument value results in no change, returns this.
      Parameters:
      allowed - whether to allow changes of tile size when needed.
      Returns:
      the layout for the given flag.
      See Also:

    • allowImageBoundsAdjustments

      public ImageLayout allowImageBoundsAdjustments(boolean allowed)
      Returns a new layout with the same properties than this layout except whether it allows changes of image size. If the given argument value results in no change, returns this.
      Parameters:
      allowed - whether to allow changes of image size when needed.
      Returns:
      the layout for the given flag.
      See Also:

    • allowPartialTiles

      public ImageLayout allowPartialTiles(boolean allowed)
      Returns a new layout with the same properties than this layout except whether it allows partially filled tiles. If the given argument value results in no change, returns this.
      Parameters:
      allowed - whether to allow tiles that are only partially filled in the last row and last column of the tile matrix.
      Returns:
      the layout for the given flag.
      See Also:

    • withTileMatrix

      public ImageLayout withTileMatrix(RenderedImage source)
      Creates a new layout with the tile size and tile indices of the given image. Other properties of this Image­Layout (sample model and all Boolean flags) are inherited unchanged. If the given argument value results in no change, returns this.
      Parameters:
      source - image from which to take tile size and tile indices.
      Returns:
      layout giving exactly the tile size and indices of given image.
      See Also:

    • withPreferredTileSize

      public ImageLayout withPreferredTileSize(Dimension size)
      Returns a new layout with the same flags but a different preferred tile size. If the given argument values result in no change, returns this.
      Parameters:
      size - the new tile size.
      Returns:
      the layout for the given size.
      See Also:

    • getPreferredTileSize

      public final Dimension getPreferredTileSize()
      Returns the preferred tile size. This is the dimension values specified at construction time.
      Returns:
      the preferred tile size.

    • suggestTileSize

      public Dimension suggestTileSize(int imageWidth, int imageHeight)
      Suggests a tile size for the specified image size. This method suggests a tile size which is a divisor of the given image size if possible, or a size that left as few empty pixels as possible otherwise. The is­Partial­Tiles­Allowed flag specifies whether to allow tiles that are only partially filled. A value of true implies that tiles in the last row or in the last column may contain empty pixels. A value of false implies that this class will be unable to subdivide large images in smaller tiles if the image size is a prime number.

      The is­Partial­Tiles­Allowed flag should be false when the tiled image is opaque, or if the sample value for transparent pixels is different than zero. This restriction is for avoiding black or colored borders on the image left size and bottom size.

      Parameters:
      image­Width - the image width in pixels.
      image­Height - the image height in pixels.
      Returns:
      suggested tile size for the given image size.

    • suggestTileSize

      public Dimension suggestTileSize(RenderedImage image, Rectangle bounds)
      Suggests a tile size for operations derived from the given image. If the given image is null, then this method returns the preferred tile size. Otherwise, if the given image is already tiled, then this method preserves the current tile size unless the tiles are too large, in which case they may be subdivided. Otherwise (untiled image), this method proposes a tile size.

      This method checks whether the image color model supports transparency. If not, then this method will not return a size that may result in the creation of partially empty tiles. In other words, the is­Partial­Tiles­Allowed flag is ignored (handled as false) for opaque images.

      Parameters:
      image - the image for which to derive a tile size, or null.
      bounds - the bounds of the image to create, or null if same as image.
      Returns:
      suggested tile size for the given image.

    • createCompatibleSampleModel

      public SampleModel createCompatibleSampleModel(RenderedImage image, Rectangle bounds)
      Returns a sample model with a size computed from the given image size. If this Image­Layout contains a sample­Model, then the latter is used as a template. Otherwise, the new sample model is derived from the image.
      Parameters:
      image - the image from which to derive a sample model.
      bounds - the bounds of the image to create, or null if same as image.
      Returns:
      image sample model with a tile size derived from the given image size.
      Throws:
      Illegal­State­Exception - if sample­Model is non-null and the given image does not have the same number of bands.
      See Also:

    • createSampleModel

      public SampleModel createSampleModel(DataType dataType, Rectangle bounds, int numBands)
      Returns a sample model for the given data type with a size computed from the given image bounds. If this Image­Layout contains a sample­Model, then the latter is used as a template.
      Parameters:
      data­Type - the default data type for the sample model to create.
      bounds - the bounds of the image to create.
      num­Bands - the number of bands in the sample model to create.
      Returns:
      image sample model with a tile size derived from the given image bounds.
      Throws:
      Illegal­State­Exception - if sample­Model is non-null but does not have the same number of bands as the given num­Bands argument.

    • getPreferredMinTile

      public final Point getPreferredMinTile()
      Returns the preferred indices of the upper-left tile in an image tile matrix. This property usually has no incidence on the appearance or performance of an image. It usually doesn't change neither the calculations that depend on georeferencing, because these calculations depend on pixel coordinates rather than tile coordinates. Therefore, this property is only a hint and may be ignored by image operations.
      Returns:
      preferred tile indices of the upper-left tile.
      See Also:

    • toString

      public String toString()
      Returns a string representation for debugging purpose.
      Overrides:
      to­String in class Object
      Returns:
      a string representation for debugging purpose.