Package org.apache.sis.internal.storage

Class TiledGridCoverage

java.lang.Object
org.apache.sis.coverage.BandedCoverage
org.apache.sis.coverage.grid.GridCoverage
org.apache.sis.internal.storage.TiledGridCoverage
Direct Known Subclasses:
DataSubset
public abstract class TiledGridCoverage extends GridCoverage
Base class of grid coverage read from a resource where data are stored in tiles. This grid coverage may represent only a subset of the coverage resource. Tiles are read from the storage only when first needed.

Cell Coordinates

When there is no subsampling, this coverage uses the same cell coordinates than the originating resource. When there is a subsampling, cell coordinates in this coverage are divided by the subsampling factors. Conversions are done by toFullResolution(long, int).

Tile coordinate matrix

In each TiledGridCoverage, indices of tiles starts at (0, 0, …). This class does not use the same tile indices than the coverage resource in order to avoid integer overflow.
Since:
1.1
Version:
1.2

  • Field Details

    • BIDIMENSIONAL

      protected static final int BIDIMENSIONAL
      Number of dimensions in a rendered image. Used for identifying codes where a two-dimensional slice is assumed.
      See Also:

    • X_DIMENSION

      protected static final int X_DIMENSION
      The dimensions of x and y axes. Static constants for now, may become configurable fields in the future.
      See Also:

    • Y_DIMENSION

      protected static final int Y_DIMENSION
      The dimensions of x and y axes. Static constants for now, may become configurable fields in the future.
      See Also:

    • readExtent

      private final GridExtent readExtent
      The area to read in unit of the full coverage (without subsampling). This is the intersection between user-specified domain and the source TiledGridResource domain, expanded to an integer number of tiles.

    • forceTileSize

      private final boolean forceTileSize
      Whether to force the readExtent tile intersection to the tileSize. This is relevant only for the last column of tile matrix, because those tiles may be truncated if the image size is not a multiple of tile size. It is usually necessary to read those tiles fully anyway because otherwise, the pixels read from the storage would not be aligned with the pixels stored in the Raster. However, there is a few exceptions where the read extent should not be forced to the tile size:
      • If the image is untiled, then the TiledGridResource.Subset constructor assumes that only the requested region of the tile will be read.
      • If the tile is truncated on the storage as well (note: this is rare. GeoTIFF for example always stores whole tiles).

      In current version this is a flag for the x dimension only. In a future version it could be flags for other dimensions as well (using bitmask) if it appears to be useful.

    • tileSize

      private final int[] tileSize
      Size of all tiles in the domain of this TiledGridCoverage, without clipping and subsampling. All coverages created from the same TiledGridResource have the same tile size values. The length of this array is the number of dimensions in the source GridExtent. This is often 2 but can also be more.

    • tileStrides

      private final int[] tileStrides
      Values by which to multiply each tile coordinates for obtaining the index in the tile vector. The length of this array is the same as tileSize. All coverages created from the same TiledGridResource have the same stride values.

    • indexOfFirstTile

      private final int indexOfFirstTile
      Index of the first TiledGridCoverage tile in a row-major array of tiles. This is the value to add to the index computed with tileStrides before to access vector elements.

    • tmcOfFirstTile

      private final long[] tmcOfFirstTile
      The Tile Matrix Coordinates (TMC) of the first tile. This is the value to subtract from tile indices computed from pixel coordinates.
      See Also:

    • subsampling

      private final int[] subsampling
      Conversion from pixel coordinates in this (potentially subsampled) coverage to pixel coordinates in the resource coverage at full resolution. The conversion from (x, y) to (x′, y′) is as below, where s are subsampling factors and t are subsampling offsets:
      • x′ = s₀⋅x + t₀
      • y′ = s₁⋅y + t₁
      This transform maps pixel corners.
      See Also:

    • subsamplingOffsets

      private final int[] subsamplingOffsets
      Conversion from pixel coordinates in this (potentially subsampled) coverage to pixel coordinates in the resource coverage at full resolution. The conversion from (x, y) to (x′, y′) is as below, where s are subsampling factors and t are subsampling offsets:
      • x′ = s₀⋅x + t₀
      • y′ = s₁⋅y + t₁
      This transform maps pixel corners.
      See Also:

    • includedBands

      protected final int[] includedBands
      Indices of TiledGridResource bands which have been retained for inclusion in this TiledGridCoverage, in strictly increasing order. An "included" band is stored in memory but not necessarily visible to the user, because the SampleModel can be configured for ignoring some bands. This array is null if all bands shall be included.

      If the user specified bands out of order, the change of band order is taken in account by the sample model. This includedBands array does not apply any change of order for making sequential readings easier.

    • rasters

      private final WeakValueHashMap<TiledGridResource.CacheKey,Raster> rasters
      Cache of rasters read by this TiledGridCoverage. This cache may be shared with other coverages created for the same TiledGridResource resource. For each value, the raster minX and minY values can be anything, depending which TiledGridCoverage was first to load the tile.
      See Also:

    • model

      protected final SampleModel model
      The sample model for all rasters. The width and height of this sample model are the two first elements of tileSize divided by subsampling and clipped to the domain. If user requested to read only a subset of the bands, then this sample model is already the subset.

    • colors

      protected final ColorModel colors
      The Java2D color model for images rendered from this coverage.

    • fillValue

      protected final Number fillValue
      The value to use for filling empty spaces in rasters, or null if zero.

    • deferredTileReading

      private final boolean deferredTileReading
      Whether the reading of tiles is deferred to RenderedImage.getTile(int, int) time.

  • Constructor Details

    • TiledGridCoverage

      protected TiledGridCoverage(TiledGridResource.Subset subset)
      Creates a new tiled grid coverage. All parameters should have been validated before this call.
      Parameters:
      subset - description of the TiledGridResource subset to cover.
      Throws:
      ArithmeticException - if the number of tiles overflows 32 bits integer arithmetic.

  • Method Details

    • getIdentifier

      protected abstract org.opengis.util.GenericName getIdentifier()
      Returns a unique name that identifies this coverage. The name shall be unique in the TileMatrixSet.
      Returns:
      an human-readable identification of this coverage.

    • getLocale

      protected Locale getLocale()
      Returns the locale for error messages, or null for the default.
      Returns:
      the locale for warning or error messages, or null if unspecified.

    • getTileSize

      protected final int getTileSize(int dimension)
      Returns the size of all tiles in the domain of this TiledGridCoverage, without clipping and subsampling.
      Parameters:
      dimension - dimension for which to get tile size.
      Returns:
      tile size in the given dimension, without clipping and subsampling.

    • getSubsampling

      protected final int getSubsampling(int dimension)
      Returns the subsampling in the given dimension.
      Parameters:
      dimension - dimension for which to get subsampling.
      Returns:
      subsampling as a value ≥ 1.

    • toFullResolution

      private long toFullResolution(long coordinate, int dimension)
      Converts a cell coordinate from this TiledGridCoverage coordinate space to full resolution. This method removes the subsampling effect. Note that since this TiledGridCoverage uses the same coordinate space than TiledGridResource, the converted coordinates should be valid in the full resource as well.
      Parameters:
      coordinate - coordinate in this TiledGridCoverage domain.
      dimension - dimension of the coordinate.
      Returns:
      coordinate in this TiledGridCoverage as if no subsampling was applied.
      Throws:
      ArithmeticException - if the coordinate cannot be represented as a long integer.

    • toSubsampledPixel

      private long toSubsampledPixel(long coordinate, int dimension)
      Converts a cell coordinate from TiledGridResource space to TiledGridCoverage coordinate. This is the converse of toFullResolution(long, int). Note that there is a possible accuracy lost.
      Parameters:
      coordinate - coordinate in the TiledGridResource domain.
      dimension - dimension of the coordinate.
      Returns:
      coordinates in this subsampled TiledGridCoverage domain.
      Throws:
      ArithmeticException - if the coordinate cannot be represented as a long integer.

    • toTileMatrixCoordinate

      private long toTileMatrixCoordinate(long coordinate, int dimension)
      Converts a cell coordinate from this TiledGridCoverage coordinate space to the Tile Matrix Coordinate (TMC) of the tile which contains that cell. The TMC is relative to the full TiledGridResource, i.e. without subtraction of tmcOfFirstTile.
      Parameters:
      coordinate - coordinates in this TiledGridCoverage domain.
      dimension - dimension of the coordinate.
      Returns:
      Tile Matrix Coordinate (TMC) of the tile which contains the specified cell.
      Throws:
      ArithmeticException - if the coordinate cannot be represented as an integer.

    • getPixelsPerElement

      protected final int getPixelsPerElement()
      Returns the number of pixels in a single bank element. This is usually 1, except for MultiPixelPackedSampleModel which packs many pixels in a single bank element. This value is a power of 2 according MultiPixelPackedSampleModel specification.
      Note: this is "pixels per element", not "samples per element". It makes a difference in the SinglePixelPackedSampleModel case, for which this method returns 1 (by contrast a "samples per element" would give a value greater than 1). But this value can nevertheless be understood as a "samples per element" value where only one band is considered at a time.
      Returns:
      number of pixels in a single bank element. Usually 1.
      See Also:

    • getPixelsPerElement

      static int getPixelsPerElement(SampleModel model)
      Implementation of getPixelsPerElement().
      Parameters:
      model - the sample model from which to infer the number of pixels per bank element.
      Returns:
      number of pixels in a single bank element. Usually 1.

    • render

      public RenderedImage render(GridExtent sliceExtent)
      Returns a two-dimensional slice of grid data as a rendered image.
      Specified by:
      render in class GridCoverage
      Parameters:
      sliceExtent - a subspace of this grid coverage extent, or null for the whole image.
      Returns:
      the grid slice as a rendered image. Image location is relative to sliceExtent.

    • createCacheKey

      private TiledGridResource.CacheKey createCacheKey(int indexInTileVector)
      Creates the key to use for caching the tile at given index.

    • readTiles

      protected abstract Raster[] readTiles(TiledGridCoverage.AOI iterator) throws IOException, DataStoreException
      Returns all tiles in the given area of interest. Tile indices are relative to this TiledGridCoverage: (0,0) is the tile in the upper-left corner of this TiledGridCoverage (not necessarily the upper-left corner of the image in the TiledGridResource). The Raster.getMinX() and getMinY() coordinates of returned rasters shall start at the given iterator.offsetAOI values.

      This method must be thread-safe. It is implementer responsibility to ensure synchronization, for example using AbstractResource.getSynchronizationLock().

      Parameters:
      iterator - an iterator over the tiles that intersect the Area Of Interest specified by user.
      Returns:
      tiles decoded from the TiledGridResource.
      Throws:
      IOException - if an I/O error occurred.
      DataStoreException - if a logical error occurred.
      RuntimeException - if the Java2D image cannot be created for another reason (too many exception types to list them all).