Package org.apache.sis.internal.storage
Class TiledGridResource
java.lang.Object
org.apache.sis.storage.AbstractResource
org.apache.sis.storage.AbstractGridCoverageResource
org.apache.sis.internal.storage.TiledGridResource
- All Implemented Interfaces:
DataSet
,GridCoverageResource
,Resource
- Direct Known Subclasses:
DataCube
Base class of grid coverage resource storing data in tiles.
The word "tile" is used for simplicity but can be understood
as "chunk" in a n-dimensional generalization.
- Since:
- 1.1
- Version:
- 1.2
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static final class
A key in therasters
cache of tiles.final class
Parameters that describe the resource subset to be accepted by theTiledGridCoverage
constructor. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate RasterLoadingStrategy
Whether all tiles should be loaded atread(…)
method call or deferred to a later time.private final WeakValueHashMap
<TiledGridResource.CacheKey, Raster> All tiles loaded by anyTiledGridCoverage
created from this resource.Fields inherited from class org.apache.sis.storage.AbstractResource
listeners
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
TiledGridResource
(StoreListeners parent) Creates a new resource. -
Method Summary
Modifier and TypeMethodDescriptionprotected int
getAtomSize
(boolean xdim) Returns the number of sample values in an indivisible element of a tile.protected abstract ColorModel
Returns the Java2D color model for rendering images, ornull
if none.protected boolean
Returnstrue
if the reader can load only the requested bands and skip the other bands, orfalse
if the reader must load all bands.protected abstract Number
Returns the value to use for filling empty spaces in rasters, ornull
if none, not different than zero or not valid for the target data type.final RasterLoadingStrategy
Returns an indication about when the "physical" loading of raster data will happen.protected abstract SampleModel
Returns the Java2D sample model describing pixel type and layout for all bands.protected abstract int[]
Returns the size of tiles in this resource.protected final GridCoverage
preload
(GridCoverage coverage) If the loading strategy is to load all tiles atread(…)
time, replaces the given coverage by a coverage will all data in memory.private void
setLoadingStrategy
(boolean loadAtReadTime) Sets the strategy for the given flag.final boolean
setLoadingStrategy
(RasterLoadingStrategy strategy) Sets the preferred strategy about when to do the "physical" loading of raster data.private boolean
Whether this resource supports immediate loading of raster data.Methods inherited from class org.apache.sis.storage.AbstractGridCoverageResource
canNotRead, createMetadata, getEnvelope, logReadOperation
Methods inherited from class org.apache.sis.storage.AbstractResource
addListener, clearCache, getIdentifier, getMetadata, getSynchronizationLock, removeListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.apache.sis.storage.GridCoverageResource
getGridGeometry, getResolutions, getSampleDimensions, read, subset
Methods inherited from interface org.apache.sis.storage.Resource
addListener, getIdentifier, getMetadata, removeListener
-
Field Details
-
rasters
All tiles loaded by anyTiledGridCoverage
created from this resource. Keys contains tile indices in a row-major array of tiles. For each value, theRaster.getMinX()
andminY
values can be anything, depending whichTiledGridResource
was first to load the tile.- See Also:
-
loadingStrategy
Whether all tiles should be loaded atread(…)
method call or deferred to a later time. This field is initiallynull
and is initialized to its default value only when needed.- See Also:
-
-
Constructor Details
-
TiledGridResource
Creates a new resource.- Parameters:
parent
- listeners of the parent resource, ornull
if none. This is usually the listeners of theDataStore
that created this resource.
-
-
Method Details
-
getTileSize
protected abstract int[] getTileSize()Returns the size of tiles in this resource. The length of the returned array is the number of dimensions.- Returns:
- the size of tiles (in pixels) in this resource.
-
getAtomSize
Returns the number of sample values in an indivisible element of a tile. An element is a primitive type such asbyte
,int
orfloat
. This value is usually 1 because each sample value is usually stored in a separated element. However, in multi-pixels packed sample model (e.g. bilevel image with 8 pixels per byte), it is difficult to start reading an image at x location other than a byte boundary. By declaring an "atom" size of 8 sample values in dimension X, theTiledGridResource.Subset
constructor will ensure than the sub-region to read starts at a byte boundary when reading a bilevel image.The default implementation returns the number of pixels per data element for dimension X and returns 1 for all other dimensions.
- Parameters:
xdim
-true
for the size on x dimension,false
for any other dimension.- Returns:
- indivisible amount of sample values to read in the specified dimension. Must be ≥ 1. This is in units of sample values (may be bits, bytes, floats, etc).
- Throws:
DataStoreException
- if an error occurred while fetching the sample model.
-
getDissociableBands
Returnstrue
if the reader can load only the requested bands and skip the other bands, orfalse
if the reader must load all bands. This value controls the amount of data to be loaded byGridCoverageResource.read(GridGeometry, int...)
:- If
false
, thenTiledGridCoverage.model
will expect the sameDataBuffer
than the one expected by the sample model of this resource. All bands will be loaded but the coverage sample model will ignore the bands that were not enumerated in therange
argument. This strategy is convenient when skipping bands at reading time is hard. - If
true
, thenTiledGridCoverage.model
will have its band indices and bit masks "compressed" for making them consecutive. For example if therange
argument specifies that the bands to read are {1, 3, 4, 6}, then after "compression" band indices become {0, 1, 2, 3}. This strategy is efficient when the reader is capable to skip bands at reading time.
The default implementation returns
true
if the sample model is aComponentSampleModel
andfalse
if all other cases, because skipping bands in a packed sample model is more difficult to implement.- Returns:
true
if the reader can load only the requested bands and skip other bands, orfalse
if the reader needs to load all bands regardless therange
subset.- Throws:
DataStoreException
- if an error occurred while fetching the sample model.- See Also:
- If
-
getSampleModel
Returns the Java2D sample model describing pixel type and layout for all bands. The raster size is the tile size as stored in the resource.Multi-dimensional data cube
If this resource has more than 2 dimensions, then this model is for the two first ones (usually horizontal). The images for all levels in additional dimensions shall use the same sample model.Performance note
Implementation should return a cached value, because this method may be invoked many times.- Returns:
- the sample model for tiles at full resolution with all their bands.
- Throws:
DataStoreException
- if an error occurred during sample model construction.
-
getColorModel
Returns the Java2D color model for rendering images, ornull
if none. The color model shall be compatible with the sample model returned bygetSampleModel()
.- Returns:
- a color model compatible with
getSampleModel()
, ornull
if none. - Throws:
DataStoreException
- if an error occurred during color model construction.
-
getFillValue
Returns the value to use for filling empty spaces in rasters, ornull
if none, not different than zero or not valid for the target data type. This value is used if a tile contains less pixels than expected. The zero value is excluded because tiles are already initialized to zero by default.- Returns:
- the value to use for filling empty spaces in rasters.
- Throws:
DataStoreException
- if an error occurred while fetching filling information.
-
preload
If the loading strategy is to load all tiles atread(…)
time, replaces the given coverage by a coverage will all data in memory. This method should be invoked by subclasses at the end of theirGridCoverageResource.read(GridGeometry, int...)
method implementation.- Parameters:
coverage
- theTiledGridCoverage
to potentially replace by a coverage with preloaded data.- Returns:
- a coverage with preloaded data, or the given coverage if preloading is not enabled.
- Throws:
DataStoreException
- if an error occurred while preloading data.
-
supportImmediateLoading
private boolean supportImmediateLoading()Whether this resource supports immediate loading of raster data. Current implementation does not support immediate loading if the data cube has more than 2 dimensions. Non-immediate loading allows users to specify two-dimensional slices. -
getLoadingStrategy
Returns an indication about when the "physical" loading of raster data will happen.- Returns:
- current raster data loading strategy for this resource.
- Throws:
DataStoreException
- if an error occurred while fetching data store configuration.
-
setLoadingStrategy
Sets the preferred strategy about when to do the "physical" loading of raster data.- Parameters:
strategy
- the desired strategy for loading raster data.- Returns:
true
if the given strategy has been accepted, orfalse
if this implementation replaced the given strategy by an alternative.- Throws:
DataStoreException
- if an error occurred while setting data store configuration.
-
setLoadingStrategy
private void setLoadingStrategy(boolean loadAtReadTime) Sets the strategy for the given flag.- Parameters:
loadAtReadTime
- whether all tiles should be read immediately atread(…)
method call or deferred at a later time.
-