Class ImageLayout

java.lang.Object
org.apache.sis.internal.coverage.j2d.ImageLayout
Direct Known Subclasses:
ImageCombiner.Layout, ImageLayout.FixedSize

public class ImageLayout extends Object
Derives information about image location, size and tile grid. ImageLayout does not store those information directly, but provides method for deriving those properties from a given image.
Since:
1.1
Version:
1.2
  • Field Details

    • MIN_TILE_SIZE

      private static final int MIN_TILE_SIZE
      The minimum tile size. The toTileSize(int, int, boolean) method will not suggest tiles smaller than this size. This size must be smaller than ImageUtilities.DEFAULT_TILE_SIZE.

      Tiles of 180×180 pixels consume about 127 kB, assuming 4 bytes per pixel. This is about half the consumption of tiles of 256×256 pixels. We select a size which is a multiple of 90 because images are often used with a resolution of e.g. ½° per pixel.

      See Also:
    • DEFAULT

      public static final ImageLayout DEFAULT
      The default instance which will target 256 pixels as tile width and height.
    • SIZE_ADJUST

      public static final ImageLayout SIZE_ADJUST
      Same as DEFAULT, but makes image size an integer amount of tiles.
    • preferredTileWidth

      private final int preferredTileWidth
      Preferred size for tiles.
      See Also:
    • preferredTileHeight

      private final int preferredTileHeight
      Preferred size for tiles.
      See Also:
    • isBoundsAdjustmentAllowed

      public final boolean isBoundsAdjustmentAllowed
      Whether image size can be modified if needed. Changes are applied only if an image cannot be tiled because suggestTileSize(int, int, boolean) cannot find a tile size close to the desired 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.

      If this flag is true, then the bounds argument given to the suggestTileSize(RenderedImage, Rectangle, boolean) will be modified in-place.

  • Constructor Details

    • ImageLayout

      public ImageLayout(Dimension preferredTileSize, boolean isBoundsAdjustmentAllowed)
      Creates a new image layout.
      Parameters:
      preferredTileSize - the preferred tile size, or null for the default size.
      isBoundsAdjustmentAllowed - whether image size can be modified if needed.
  • Method Details

    • fixedSize

      public static ImageLayout fixedSize(RenderedImage source)
      Creates a new layout with exactly the tile size of given image.
      Parameters:
      source - image from which to take tile size and indices.
      Returns:
      layout giving exactly the tile size and indices of given image.
    • getPreferredTileSize

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

      private static int toTileSize(int imageSize, int preferredTileSize, boolean allowPartialTiles)
      Suggests a tile size close to tileSize for the specified imageSize. First, this method tries to return a tile size which is a divisor of the image size. If no such divisor is found and allowPartialTiles is true, then this method returns a size that minimize the amount of empty pixels in the last tile.
      Parameters:
      imageSize - the image size (width or height).
      preferredTileSize - the preferred tile size, which is often 256.
      allowPartialTiles - whether to allow tiles that are only partially filled.
      Returns:
      the suggested tile size, or imageSize if none.
    • suggestTileSize

      public Dimension suggestTileSize(int imageWidth, int imageHeight, boolean allowPartialTiles)
      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 allowPartialTile argument 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 allowPartialTile argument should be false if 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.
      allowPartialTiles - whether to allow tiles that are only partially filled.
      Returns:
      suggested tile size for the given image size.
    • suggestTileSize

      public Dimension suggestTileSize(RenderedImage image, Rectangle bounds, boolean allowPartialTiles)
      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 also checks whether the color model supports transparency. If not, then this method will not return a size that may result in the creation of partially empty tiles.

      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.
      allowPartialTiles - whether to allow tiles that are only partially filled. This argument is ignored (reset to false) if the given image is opaque.
      Returns:
      suggested tile size for the given image.
    • sizeToAdd

      private static int sizeToAdd(int size, int tileSize)
      Computes the size to add to the width or height for making it divisible by the given tile size.
    • createBandedSampleModel

      public BandedSampleModel createBandedSampleModel(int type, int numBands, RenderedImage image, Rectangle bounds)
      Creates a banded sample model of the given type with the suggested tile size for the given image.
      Parameters:
      type - desired data type as a DataBuffer constant.
      numBands - desired number of bands.
      image - the image which will be the source of the image for which a sample model is created.
      bounds - the bounds of the image to create, or null if same as image.
      Returns:
      a banded sample model of the given type with the given number of bands.
    • createCompatibleSampleModel

      public SampleModel createCompatibleSampleModel(RenderedImage image, Rectangle bounds)
      Creates a sample model compatible with the sample model of the given image but with a size matching the preferred tile size. This method can be used for determining the sampleModel argument of ComputedImage constructor.
      Parameters:
      image - the image form which to get a sample model.
      bounds - the bounds of the image to create, or null if same as image.
      Returns:
      image sample model with preferred tile size.
      See Also:
    • getMinTile

      public Point getMinTile()
      Returns indices of the first tile (minTileX, minTileY), or null for (0,0). The default implementation returns null.
      Returns:
      indices of the first tile (minTileX, minTileY), or null for (0,0).
    • toString

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