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
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 eachDataSubset
, 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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
Information about a tile to be read.Nested classes/interfaces inherited from class org.apache.sis.internal.storage.TiledGridCoverage
TiledGridCoverage.AOI, TiledGridCoverage.Snapshot
Nested classes/interfaces inherited from class org.apache.sis.coverage.grid.GridCoverage
GridCoverage.Evaluator
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate TilePlaceholder
Provider of empty tiles, created only if needed.private static final Closeable
No-operation "resource" forcreateInflater()
default value.protected final int
Number of banks retained for the target image data buffer.private final int
Total number of tiles in the image.(package private) final DataCube
The resource which contain thisDataSubset
.protected final int
Number of interleaved sample values in a pixel in the GeoTIFF file (ignoring band subset).protected final int
Number of interleaved sample values in a pixel of the image to load in memory.private final Vector
For each tile, the number of (compressed) bytes in that tile.private final Vector
For each tile, the byte offset of that tile as compressed and stored on disk.Fields inherited from class org.apache.sis.internal.storage.TiledGridCoverage
BIDIMENSIONAL, colors, fillValue, includedBands, model, X_DIMENSION, Y_DIMENSION
Fields inherited from class org.apache.sis.coverage.grid.GridCoverage
gridGeometry
-
Constructor Summary
ConstructorsConstructorDescriptionDataSubset
(DataCube source, TiledGridResource.Subset subset) Creates a new data subset. -
Method Summary
Modifier and TypeMethodDescription(package private) Closeable
Invoked in a synchronized block before the first call toreadSlice(…)
.(package private) final void
fillRemainingRows
(Buffer bank) Applies the fill value if it is different than the default value (zero) to all remaining rows.protected final int
getBankCapacity
(int pixelsPerElement) Returns the size of a bank (not necessarily a band) in number of primitive elements (bytes, integers, …).protected final DataType
Returns the type of data in all tiles.protected final org.opengis.util.GenericName
Returns an human-readable identification of this coverage.final Locale
Returns the locale for warning or error messages, ornull
if unspecified.(package private) final ChannelDataInput
input()
Returns the input of bytes for compressed raster data.(package private) Raster
readSlice
(long[] offsets, long[] byteCounts, long[] lower, long[] upper, int[] subsampling, Point location) Reads a two-dimensional slice of the data cube from the given input channel.protected final Raster[]
readTiles
(TiledGridCoverage.AOI iterator) Returns all tiles in the given area of interest.Methods inherited from class org.apache.sis.internal.storage.TiledGridCoverage
getPixelsPerElement, getSubsampling, getTileSize, render
Methods inherited from class org.apache.sis.coverage.grid.GridCoverage
createConvertedValues, evaluator, forConvertedValues, getCoordinateReferenceSystem, getEnvelope, getGridGeometry, getSampleDimensions, toString, toTree
-
Field Details
-
source
The resource which contain thisDataSubset
. Used for fetching information like the input channel and where to report warnings. -
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 thisDataSubset
is at indexTiledGridCoverage.indexOfFirstTile
. -
tileByteCounts
For each tile, the number of (compressed) bytes in that tile. Elements are in the same order thantileOffsets
. -
numTiles
private final int numTilesTotal number of tiles in the image. This is used for computing the stride between a band and the next band intileOffsets
andtileByteCounts
vectors. -
numBanks
protected final int numBanksNumber 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 sourcePixelStrideNumber 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 targetPixelStrideNumber of interleaved sample values in a pixel of the image to load in memory. This is similar tosourcePixelStride
, but taking in account the number of bands requested by user at reading time. -
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
No-operation "resource" forcreateInflater()
default value.
-
-
Constructor Details
-
DataSubset
DataSubset(DataCube source, TiledGridResource.Subset subset) throws DataStoreException Creates a new data subset. All parameters should have been validated byImageFileDirectory.validateMandatoryTags()
before this call. This constructor should be invoked inside a synchronized block.- Parameters:
source
- the resource which contain thisDataSubset
.subset
- description of theowner
subset to cover.- Throws:
ArithmeticException
- if the number of tiles overflows 32 bits integer arithmetic.DataStoreException
-
-
Method Details
-
getLocale
Returns the locale for warning or error messages, ornull
if unspecified.- Specified by:
getLocale
in interfaceLocalized
- Overrides:
getLocale
in classTiledGridCoverage
- 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 classTiledGridCoverage
- Returns:
- an human-readable identification of this coverage.
-
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). TheSampleModel.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
Returns the input of bytes for compressed raster data. If the TIFF tagFillOrder
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 thisDataSubset
: (0,0) is the tile in the upper-left corner of thisDataSubset
(not necessarily the upper-left corner of the image stored in the TIFF file). TheRaster.getMinX()
andgetMinY()
coordinates of returned rasters will start at the givenoffsetAOI
values.This method is thread-safe. Synchronization is done on
DataCube.getSynchronizationLock()
.- Specified by:
readTiles
in classTiledGridCoverage
- 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 toreadSlice(…)
. Subclasses can override this method for allocating resources to be reused for reading each tile. TheCloseable.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 toreadSlice(…)
.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 thelower
argument is (0,0) and theupper
argument is the tile size. But those arguments may identify a smaller region if theDataSubset
contains only one (potentially large) tile.The length of
lower
,upper
andsubsampling
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 byDataCube.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
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.
-