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
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 bytoFullResolution(long, int)
.
Tile coordinate matrix
In eachTiledGridCoverage
, 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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected final class
The Area Of Interest specified by user in a call torender(GridExtent)
.protected static class
Snapshot of aTiledGridCoverage.AOI
iterator position.Nested classes/interfaces inherited from class org.apache.sis.coverage.grid.GridCoverage
GridCoverage.Evaluator
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected static final int
Number of dimensions in a rendered image.protected final ColorModel
The Java2D color model for images rendered from this coverage.private final boolean
Whether the reading of tiles is deferred toRenderedImage.getTile(int, int)
time.protected final Number
The value to use for filling empty spaces in rasters, ornull
if zero.private final boolean
Whether to force thereadExtent
tile intersection to thetileSize
.protected final int[]
Indices ofTiledGridResource
bands which have been retained for inclusion in thisTiledGridCoverage
, in strictly increasing order.private final int
Index of the firstTiledGridCoverage
tile in a row-major array of tiles.protected final SampleModel
The sample model for all rasters.private final WeakValueHashMap
<TiledGridResource.CacheKey, Raster> Cache of rasters read by thisTiledGridCoverage
.private final GridExtent
The area to read in unit of the full coverage (without subsampling).private final int[]
Conversion from pixel coordinates in this (potentially subsampled) coverage to pixel coordinates in the resource coverage at full resolution.private final int[]
Conversion from pixel coordinates in this (potentially subsampled) coverage to pixel coordinates in the resource coverage at full resolution.private final int[]
Size of all tiles in the domain of thisTiledGridCoverage
, without clipping and subsampling.private final int[]
Values by which to multiply each tile coordinates for obtaining the index in the tile vector.private final long[]
The Tile Matrix Coordinates (TMC) of the first tile.protected static final int
The dimensions of x and y axes.protected static final int
The dimensions of x and y axes.Fields inherited from class org.apache.sis.coverage.grid.GridCoverage
gridGeometry
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
Creates a new tiled grid coverage. -
Method Summary
Modifier and TypeMethodDescriptionprivate TiledGridResource.CacheKey
createCacheKey
(int indexInTileVector) Creates the key to use for caching the tile at given index.protected abstract org.opengis.util.GenericName
Returns a unique name that identifies this coverage.protected Locale
Returns the locale for error messages, ornull
for the default.protected final int
Returns the number of pixels in a single bank element.(package private) static int
getPixelsPerElement
(SampleModel model) Implementation ofgetPixelsPerElement()
.protected final int
getSubsampling
(int dimension) Returns the subsampling in the given dimension.protected final int
getTileSize
(int dimension) Returns the size of all tiles in the domain of thisTiledGridCoverage
, without clipping and subsampling.protected abstract Raster[]
readTiles
(TiledGridCoverage.AOI iterator) Returns all tiles in the given area of interest.render
(GridExtent sliceExtent) Returns a two-dimensional slice of grid data as a rendered image.private long
toFullResolution
(long coordinate, int dimension) Converts a cell coordinate from thisTiledGridCoverage
coordinate space to full resolution.private long
toSubsampledPixel
(long coordinate, int dimension) Converts a cell coordinate fromTiledGridResource
space toTiledGridCoverage
coordinate.private long
toTileMatrixCoordinate
(long coordinate, int dimension) Converts a cell coordinate from thisTiledGridCoverage
coordinate space to the Tile Matrix Coordinate (TMC) of the tile which contains that cell.Methods inherited from class org.apache.sis.coverage.grid.GridCoverage
createConvertedValues, evaluator, forConvertedValues, getCoordinateReferenceSystem, getEnvelope, getGridGeometry, getSampleDimensions, toString, toTree
-
Field Details
-
BIDIMENSIONAL
protected static final int BIDIMENSIONALNumber 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_DIMENSIONThe 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_DIMENSIONThe dimensions of x and y axes. Static constants for now, may become configurable fields in the future.- See Also:
-
readExtent
The area to read in unit of the full coverage (without subsampling). This is the intersection between user-specified domain and the sourceTiledGridResource
domain, expanded to an integer number of tiles. -
forceTileSize
private final boolean forceTileSizeWhether to force thereadExtent
tile intersection to thetileSize
. 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 theRaster
. 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.
- If the image is untiled, then the
-
tileSize
private final int[] tileSizeSize of all tiles in the domain of thisTiledGridCoverage
, without clipping and subsampling. All coverages created from the sameTiledGridResource
have the same tile size values. The length of this array is the number of dimensions in the sourceGridExtent
. This is often 2 but can also be more. -
tileStrides
private final int[] tileStridesValues by which to multiply each tile coordinates for obtaining the index in the tile vector. The length of this array is the same astileSize
. All coverages created from the sameTiledGridResource
have the same stride values. -
indexOfFirstTile
private final int indexOfFirstTileIndex of the firstTiledGridCoverage
tile in a row-major array of tiles. This is the value to add to the index computed withtileStrides
before to access vector elements. -
tmcOfFirstTile
private final long[] tmcOfFirstTileThe 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[] subsamplingConversion 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₁
- See Also:
-
subsamplingOffsets
private final int[] subsamplingOffsetsConversion 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₁
- See Also:
-
includedBands
protected final int[] includedBandsIndices ofTiledGridResource
bands which have been retained for inclusion in thisTiledGridCoverage
, in strictly increasing order. An "included" band is stored in memory but not necessarily visible to the user, because theSampleModel
can be configured for ignoring some bands. This array isnull
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
. ThisincludedBands
array does not apply any change of order for making sequential readings easier. -
rasters
Cache of rasters read by thisTiledGridCoverage
. This cache may be shared with other coverages created for the sameTiledGridResource
resource. For each value, the rasterminX
andminY
values can be anything, depending whichTiledGridCoverage
was first to load the tile.- See Also:
-
model
The sample model for all rasters. The width and height of this sample model are the two first elements oftileSize
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
The Java2D color model for images rendered from this coverage. -
fillValue
The value to use for filling empty spaces in rasters, ornull
if zero. -
deferredTileReading
private final boolean deferredTileReadingWhether the reading of tiles is deferred toRenderedImage.getTile(int, int)
time.
-
-
Constructor Details
-
TiledGridCoverage
Creates a new tiled grid coverage. All parameters should have been validated before this call.- Parameters:
subset
- description of theTiledGridResource
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 theTileMatrixSet
.- Returns:
- an human-readable identification of this coverage.
-
getLocale
Returns the locale for error messages, ornull
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 thisTiledGridCoverage
, 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 thisTiledGridCoverage
coordinate space to full resolution. This method removes the subsampling effect. Note that since thisTiledGridCoverage
uses the same coordinate space thanTiledGridResource
, the converted coordinates should be valid in the full resource as well.- Parameters:
coordinate
- coordinate in thisTiledGridCoverage
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 fromTiledGridResource
space toTiledGridCoverage
coordinate. This is the converse oftoFullResolution(long, int)
. Note that there is a possible accuracy lost.- Parameters:
coordinate
- coordinate in theTiledGridResource
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 thisTiledGridCoverage
coordinate space to the Tile Matrix Coordinate (TMC) of the tile which contains that cell. The TMC is relative to the fullTiledGridResource
, i.e. without subtraction oftmcOfFirstTile
.- Parameters:
coordinate
- coordinates in thisTiledGridCoverage
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 forMultiPixelPackedSampleModel
which packs many pixels in a single bank element. This value is a power of 2 accordingMultiPixelPackedSampleModel
specification.Note: this is "pixels per element", not "samples per element". It makes a difference in theSinglePixelPackedSampleModel
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
Implementation ofgetPixelsPerElement()
.- 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
Returns a two-dimensional slice of grid data as a rendered image.- Specified by:
render
in classGridCoverage
- Parameters:
sliceExtent
- a subspace of this grid coverage extent, ornull
for the whole image.- Returns:
- the grid slice as a rendered image. Image location is relative to
sliceExtent
.
-
createCacheKey
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 thisTiledGridCoverage
: (0,0) is the tile in the upper-left corner of thisTiledGridCoverage
(not necessarily the upper-left corner of the image in theTiledGridResource
). TheRaster.getMinX()
andgetMinY()
coordinates of returned rasters shall start at the giveniterator.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).
-