Package org.apache.sis.storage.geotiff

Class DataSubset

java.lang.Object
org.apache.sis.coverage.BandedCoverage
org.apache.sis.coverage.grid.GridCoverage
org.apache.sis.internal.storage.TiledGridCoverage
org.apache.sis.storage.geotiff.DataSubset
All Implemented Interfaces:
Localized
Direct Known Subclasses:
CompressedSubset
class DataSubset extends TiledGridCoverage implements Localized
Raster data obtained from a GeoTIFF file in the domain requested by user. The number of dimensions is 2 for standard TIFF files, but this class accepts higher number of dimensions if 3- or 4-dimensional data are stored in a GeoTIFF file using some convention. This base class transfers uncompressed data. Compressed data are handled by specialized subclasses.

Cell Coordinates

When there is no subsampling, DataSubset uses the same cell coordinates than DataCube. When there is a subsampling, cell coordinates in this subset are divided by the subsampling factors. Conversion is done by TiledGridCoverage.toFullResolution(long, int).

Tile Matrix Coordinates

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

  • Field Details

    • source

      final DataCube source
      The resource which contain this DataSubset. Used for fetching information like the input channel and where to report warnings.

    • tileOffsets

      private final Vector tileOffsets
      For each tile, the byte offset of that tile as compressed and stored on disk. Tile X index varies fastest, followed by tile Y index, then tile Z index if any. The first tile included in this DataSubset is at index TiledGridCoverage.indexOfFirstTile.
      See Also:

    • tileByteCounts

      private final Vector tileByteCounts
      For each tile, the number of (compressed) bytes in that tile. Elements are in the same order than tileOffsets.
      See Also:

    • numTiles

      private final int numTiles
      Total number of tiles in the image. This is used for computing the stride between a band and the next band in tileOffsets and tileByteCounts vectors.

    • numBanks

      protected final int numBanks
      Number of banks retained for the target image data buffer. This is equal to the number of bands only for planar images, and 1 in all other cases. If the user asked to read only a subset of the bands, then "number of bands" in above sentence is the subset size.

    • sourcePixelStride

      protected final int sourcePixelStride
      Number of interleaved sample values in a pixel in the GeoTIFF file (ignoring band subset). For planar images (banded sample model), this is equal to 1. For pixel interleaved image, this is equal to the number of bands in the original image.

      Note: a sample may be a fraction of byte. For example, in a bilevel image, a sample is a bit and 8 samples are packed in each byte. Conversely a sample may also be 1, 2, 4 or 8 bytes.

      See Also:

    • targetPixelStride

      protected final int targetPixelStride
      Number of interleaved sample values in a pixel of the image to load in memory. This is similar to sourcePixelStride, but taking in account the number of bands requested by user at reading time.

    • emptyTiles

      private TilePlaceholder emptyTiles
      Provider of empty tiles, created only if needed. Empty tiles are tiles with a length of 0 declared in the TIFF header. This interpretation is a GDAL extension, not a TIFF standard.

    • NOOP

      private static final Closeable NOOP
      No-operation "resource" for createInflater() default value.

  • Constructor Details

  • Method Details

    • getLocale

      public final Locale getLocale()
      Returns the locale for warning or error messages, or null if unspecified.
      Specified by:
      getLocale in interface Localized
      Overrides:
      getLocale in class TiledGridCoverage
      Returns:
      the locale for warning or error messages, or null if unspecified.

    • getIdentifier

      protected final org.opengis.util.GenericName getIdentifier()
      Returns an human-readable identification of this coverage. The namespace should be the filename and the tip can be an image index, citation, or overview level.
      Specified by:
      getIdentifier in class TiledGridCoverage
      Returns:
      an human-readable identification of this coverage.

    • getDataType

      protected final DataType getDataType()
      Returns the type of data in all tiles. Note that more than one pixel may be packed in a single element of the returned type (e.g. bilevel image using only one bit per pixel). The SampleModel.getSampleSize(int) method should be invoked for a complement of information.

    • getBankCapacity

      protected final int getBankCapacity(int pixelsPerElement)
      Returns the size of a bank (not necessarily a band) in number of primitive elements (bytes, integers, …). This is tile width × height × targetPixelStride divided by the number of sample values per element, with each row starting on an element boundary.
      Parameters:
      pixelsPerElement - always 1 except when two or more pixels are packed in each element.
      Returns:
      expected number of primitive elements in the bank.

    • input

      final ChannelDataInput input() throws IOException
      Returns the input of bytes for compressed raster data. If the TIFF tag FillOrder is 2 (which should be very rare), the input stream reverse the order of all bits in each byte.
      Throws:
      IOException

    • readTiles

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

      This method is thread-safe. Synchronization is done on DataCube.getSynchronizationLock().

      Specified by:
      readTiles in class TiledGridCoverage
      Parameters:
      iterator - an iterator over the tiles that intersect the Area Of Interest specified by user.
      Returns:
      tiles decoded from the TIFF file.
      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).

    • createInflater

      Closeable createInflater()
      Invoked in a synchronized block before the first call to readSlice(…). Subclasses can override this method for allocating resources to be reused for reading each tile. The Closeable.close() method of the returned object will be invoked (even if an exception has been thrown during the reading process) in the same synchronized block after the last call to readSlice(…).

      The default implementation returns a no-operation object. Direct subclasses can ignore; they do not need to invoke super.createInflater().

    • readSlice

      Raster readSlice(long[] offsets, long[] byteCounts, long[] lower, long[] upper, int[] subsampling, Point location) throws IOException, DataStoreException
      Reads a two-dimensional slice of the data cube from the given input channel. This method is usually invoked for reading the tile in full, in which case the lower argument is (0,0) and the upper argument is the tile size. But those arguments may identify a smaller region if the DataSubset contains only one (potentially large) tile.

      The length of lower, upper and subsampling arrays shall be 2.

      Default implementation

      The default implementation in this base class assumes uncompressed data without band subset. Subsampling on the X axis is not supported if the image has interleaved pixels. Packed pixels (é.g. bilevel images with 8 pixels per byte) are not supported. Those restrictions are verified by DataCube.canReadDirect(TiledGridResource.Subset). Subclasses must override for handling decompression or for resolving above-cited limitations.
      Parameters:
      offsets - position in the channel where tile data begins, one value per bank.
      byteCounts - number of bytes for the compressed tile data, one value per bank.
      lower - (x, y) coordinates of the first pixel to read relative to the tile.
      upper - (x, y) coordinates after the last pixel to read relative to the tile.
      subsampling - (sx, sy) subsampling factors.
      location - pixel coordinates in the upper-left corner of the tile to return.
      Returns:
      a single tile decoded from the GeoTIFF file.
      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).
      See Also:

    • fillRemainingRows

      final void fillRemainingRows(Buffer bank)
      Applies the fill value if it is different than the default value (zero) to all remaining rows. This method is needed because the buffer filled by read methods may have less data than the buffer capacity if the current tile is smaller than the expected tile size (e.g. last tile is truncated).
      Parameters:
      bank - the buffer where to fill remaining rows.