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
public abstract class TiledGridResource extends AbstractGridCoverageResource
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

  • Field Details

  • Constructor Details

    • TiledGridResource

      protected TiledGridResource(StoreListeners parent)
      Creates a new resource.
      Parameters:
      parent - listeners of the parent resource, or null if none. This is usually the listeners of the DataStore 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

      protected int getAtomSize(boolean xdim) throws DataStoreException
      Returns the number of sample values in an indivisible element of a tile. An element is a primitive type such as byte, int or float. 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, the TiledGridResource.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

      protected boolean getDissociableBands() throws DataStoreException
      Returns true if the reader can load only the requested bands and skip the other bands, or false if the reader must load all bands. This value controls the amount of data to be loaded by GridCoverageResource.read(GridGeometry, int...):
      • If false, then TiledGridCoverage.model will expect the same DataBuffer 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 the range argument. This strategy is convenient when skipping bands at reading time is hard.
      • If true, then TiledGridCoverage.model will have its band indices and bit masks "compressed" for making them consecutive. For example if the range 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 a ComponentSampleModel and false 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, or false if the reader needs to load all bands regardless the range subset.
      Throws:
      DataStoreException - if an error occurred while fetching the sample model.
      See Also:

    • getSampleModel

      protected abstract SampleModel getSampleModel() throws DataStoreException
      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

      protected abstract ColorModel getColorModel() throws DataStoreException
      Returns the Java2D color model for rendering images, or null if none. The color model shall be compatible with the sample model returned by getSampleModel().
      Returns:
      a color model compatible with getSampleModel(), or null if none.
      Throws:
      DataStoreException - if an error occurred during color model construction.

    • getFillValue

      protected abstract Number getFillValue() throws DataStoreException
      Returns the value to use for filling empty spaces in rasters, or null 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

      protected final GridCoverage preload(GridCoverage coverage) throws DataStoreException
      If the loading strategy is to load all tiles at read(…) time, replaces the given coverage by a coverage will all data in memory. This method should be invoked by subclasses at the end of their GridCoverageResource.read(GridGeometry, int...) method implementation.
      Parameters:
      coverage - the TiledGridCoverage 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

      public final RasterLoadingStrategy getLoadingStrategy() throws DataStoreException
      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

      public final boolean setLoadingStrategy(RasterLoadingStrategy strategy) throws DataStoreException
      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, or false 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 at read(…) method call or deferred at a later time.