# Class ImageLayout

Object
ImageLayout

public class ImageLayout extends Object
Preferences about the tiling of an image in relationship with a given image size. `ImageLayout` 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 `SampleModel`. 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 `ImageLayout` class.

This class contains no information about colors. The `ColorModel` to associate with a `SampleModel` is controlled by a separated interface: `Colorizer`.

Instances of this class are immutable and thread-safe.

Since:
  1.5

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ImageLayout`
  `DEFAULT`
  The default instance with a preferred tile width and height of 256 pixels.
  `static final int`
  `DEFAULT_TILE_SIZE`
  Default width and height of tiles, in pixels.
  `final boolean`
  `isImageBoundsAdjustmentAllowed`
  Whether to allow changes of image size when needed.
  `final boolean`
  `isPartialTilesAllowed`
  Whether to allow tiles that are only partially filled in the last row and last column of the tile matrix.
  `final boolean`
  `isTileSizeAdjustmentAllowed`
  Whether to allow changes of tile size when needed.
  `protected final int`
  `preferredMinTileX`
  Preferred tile index where images start their tile matrix.
  `protected final int`
  `preferredMinTileY`
  Preferred tile index where images start their tile matrix.
  `protected final int`
  `preferredTileHeight`
  Preferred size (in pixels) for tiles.
  `protected final int`
  `preferredTileWidth`
  Preferred size (in pixels) for tiles.
  `protected final SampleModel`
  `sampleModel`
  Preferred sample model, or `null` if none.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ImageLayout(SampleModel sampleModel, Dimension preferredTileSize, boolean isTileSizeAdjustmentAllowed, boolean isImageBoundsAdjustmentAllowed, boolean isPartialTilesAllowed, Point preferredMinTile)`
  Creates a new image layout with the given properties.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ImageLayout`
  `allowImageBoundsAdjustments(boolean allowed)`
  Returns a new layout with the same properties than this layout except whether it allows changes of image size.
  `ImageLayout`
  `allowPartialTiles(boolean allowed)`
  Returns a new layout with the same properties than this layout except whether it allows partially filled tiles.
  `ImageLayout`
  `allowTileSizeAdjustments(boolean allowed)`
  Returns a new layout with the same properties than this layout except whether it allows changes of tile size.
  `SampleModel`
  `createCompatibleSampleModel(RenderedImage image, Rectangle bounds)`
  Returns a sample model with a size computed from the given image size.
  `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.
  `final Point`
  `getPreferredMinTile()`
  Returns the preferred indices of the upper-left tile in an image tile matrix.
  `final Dimension`
  `getPreferredTileSize()`
  Returns the preferred tile size.
  `Dimension`
  `suggestTileSize(int imageWidth, int imageHeight)`
  Suggests a tile size for the specified image size.
  `Dimension`
  `suggestTileSize(RenderedImage image, Rectangle bounds)`
  Suggests a tile size for operations derived from the given image.
  `String`
  `toString()`
  Returns a string representation for debugging purpose.
  `ImageLayout`
  `withPreferredTileSize(Dimension size)`
  Returns a new layout with the same flags but a different preferred tile size.
  `ImageLayout`
  `withSampleModel(SampleModel model, boolean cascade)`
  Returns a new layout with the same properties than this layout except for the sample model.
  `ImageLayout`
  `withTileMatrix(RenderedImage source)`
  Creates a new layout with the tile size and tile indices of the given image.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## 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:
      - Constant Field Values

  - ### 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 `ImageLayout` class.
    See Also:
      - `createCompatibleSampleModel(RenderedImage, Rectangle)`

  - ### 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:
      - `DEFAULT_TILE_SIZE`
      - `getPreferredTileSize()`
      - `suggestTileSize(int, int)`

  - ### 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:
      - `DEFAULT_TILE_SIZE`
      - `getPreferredTileSize()`
      - `suggestTileSize(int, int)`

  - ### isTileSizeAdjustmentAllowed

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

    The default value is `true`.

    See Also:
      - `allowTileSizeAdjustments(boolean)`
      - `suggestTileSize(int, int)`

  - ### isImageBoundsAdjustmentAllowed

    public final boolean isImageBoundsAdjustmentAllowed
    Whether to allow changes of image size when needed. An image may be resized when the `suggestTileSize(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 `suggestTileSize(RenderedImage, Rectangle)` method.

    The default value is `false`.

    See Also:
      - `allowImageBoundsAdjustments(boolean)`
      - `suggestTileSize(RenderedImage, Rectangle)`

  - ### 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:
      - `allowPartialTiles(boolean)`

  - ### 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:
      - `getPreferredMinTile()`

  - ### 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:
      - `getPreferredMinTile()`

- ## 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:
      `sampleModel` - preferred sample model, or `null` if none.
      `preferredTileSize` - preferred tile size, or `null` for the default size.
      `isTileSizeAdjustmentAllowed` - whether tile size can be modified if needed.
      `isImageBoundsAdjustmentAllowed` - whether image size can be modified if needed.
      `isPartialTilesAllowed` - whether to allow tiles that are only partially filled.
      `preferredMinTile` - 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:
      - `isTileSizeAdjustmentAllowed`

  - ### 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:
      - `isImageBoundsAdjustmentAllowed`

  - ### 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:
      - `isPartialTilesAllowed`

  - ### 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 `ImageLayout` (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:
      - `getPreferredTileSize()`
      - `getPreferredMinTile()`

  - ### 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()`

  - ### 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 `isPartialTilesAllowed` 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 `isPartialTilesAllowed` 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:
      `imageWidth` - the image width in pixels.
      `imageHeight` - 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 `isPartialTilesAllowed` 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 `ImageLayout` contains a `sampleModel`, 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:
      `IllegalStateException` - if `sampleModel` is non-null and the given image does not have the same number of bands.
    See Also:
      - `ComputedImage(SampleModel, RenderedImage...)`

  - ### 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 `ImageLayout` contains a `sampleModel`, then the latter is used as a template.
    Parameters:
      `dataType` - the default data type for the sample model to create.
      `bounds` - the bounds of the image to create.
      `numBands` - 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:
      `IllegalStateException` - if `sampleModel` is non-null but does not have the same number of bands as the given `numBands` 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:
      - `RenderedImage​.getMinTileX()`
      - `RenderedImage​.getMinTileY()`

  - ### toString

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