org.geotoolkit.image.io
Interface MultidimensionalImageStore

All Known Implementing Classes:

NetcdfImageReader

public interface MultidimensionalImageStore

Interface for ImageReader and ImageWriter implementations handling data which can have more than two dimensions. The standard Java Image I/O API is designed for two-dimensional data. The Geotk library can gives access to supplemental dimensions in two different ways:

• Using many DimensionSlice objects (one for each dimension) associated to a single SpatialImageReadParam object controlling the reading process. This approach is similar in spirit to the WCS 2.0 specification, but requires knowledge of Geotk API.

• Using the standard Java Image I/O API for bands and image index. An advantage of this approach is to work with libraries having no knowledge of the Geotk-specific DimensionSlice class. This is the approach enabled by this MultidimensionalImageStore interface.

Assigning a third dimension to bands
Whatever a third dimension is assigned to bands or not is plugin-specific. Plugins that have no concept of bands (like NetCDF which has the concept of n-dimensional data cube instead) can do that. For example in a dataset having (x, y, z, t) dimensions, it may be useful to handle the z dimension as bands. After the method calls below, users can select one or many elevation indices through the standard IIOParam.setSourceBands(int[]) API. Compared to the DimensionSlice API, it allows loading more than one slice in one read operation.

MultidimensionalImageStore reader = ...;
DimensionIdentification bandsDimension = reader.getDimensionForAPI(DimensionSlice.API.BANDS);
bandsDimension.addDimensionId(2); // 0-based index of the third dimension.

When a dimension is assigned to bands as in the above example, SpatialImageReadParam and SpatialImageWriteParam will initialize the IIOParam.sourceBands array to {0}, meaning to fetch only the first band by default. This is the desired behavior since the number of bands in NetCDF files is typically large and those bands are not color components. This is different than the usual IIOParam behavior which is to initialize source bands to null (meaning to fetch all bands).

Note: The rule described above is not a special case. It is a natural consequence of the fact that the default index of every dimension slice is 0.

After the z dimension in the above example has been assigned to the bands API, the bands can be used as below:

• The (x,y) plane at z_{sourceBands[0]} is stored in band 0.
• The (x,y) plane at z_{sourceBands[1]} is stored in band 1.
• etc.

Note for implementors
ImageReader and ImageWriter implementors can determine which (if any) dimension index has been assigned to the bands API by using the code below:

DimensionSet dimensionsForAPI = ...; // Typically an ImageReader/Writer field.
DimensionIdentification bandsDimension = dimensionsForAPI.get(DimensionSlice.API.BANDS);
if (bandsDimension != null) {
    Collection<?> propertiesOfAxes = ...; // This is plugin-specific.
    int index = bandsDimension.findDimensionIndex(propertiesOfAxes);
    if (index >= 0) {
        // We have found the dimension index of bands.
    }
}

See also the DimensionSet javadoc for code snippet implementing the methods declared in this interface.

Since:

3.15

Version:

3.15

Author:

Martin Desruisseaux (Geomatys)

See Also:

DimensionSlice, SpatialImageReader.getDimension(int), SpatialImageReader.getGridEnvelope(int)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary

static int	X_DIMENSION The standard dimension index of pixel columns (x ordinates) in images, which is 0.
static int	Y_DIMENSION The standard dimension index of pixel rows (y ordinates) in images, which is 1.

Method Summary

DimensionSlice.API	getAPIForDimension(Object... identifiers) Returns the API assigned to the given dimension identifiers.
Set<DimensionSlice.API>	getAPIForDimensions() Returns the set of APIs for which at least one dimension has identifiers.
DimensionIdentification	getDimensionForAPI(DimensionSlice.API api) Returns the dimension assigned to the given API.

Field Detail

X_DIMENSION

static final int X_DIMENSION

The standard dimension index of pixel columns (x ordinates) in images, which is 0. This is for example the standard dimension index of image width in grid envelopes.

In theory, the MultidimensionalImageStore API allows some flexibility about which dimension is the "image width". However in practice, the 0 dimension is often hard-coded, sometime as an index (in which case this X_DIMENSION field shall be used), or sometime in the way loops are structured (in which case a // X_DIMENSION comment shall be put). The purpose of this constant is to allow traceability of code making such hard-coded assumption, in case more flexibility is needed in the future.

Since:

3.19

See Also:

Constant Field Values

Y_DIMENSION

static final int Y_DIMENSION

The standard dimension index of pixel rows (y ordinates) in images, which is 1. This is for example the standard dimension index of image height in grid envelopes.

In theory, the MultidimensionalImageStore API allows some flexibility about which dimension is the "image height". However in practice, the 1 dimension is often hard-coded, sometime as an index (in which case this Y_DIMENSION field shall be used), or sometime in the way loops are structured (in which case a // Y_DIMENSION comment shall be put). The purpose of this constant is to allow traceability of code making such hard-coded assumption, in case more flexibility is needed in the future.

Since:

3.19

See Also:

Constant Field Values

Method Detail

getDimensionForAPI

DimensionIdentification getDimensionForAPI(DimensionSlice.API api)

Returns the dimension assigned to the given API. This method never return null. However the returned dimension can be used only if the addDimensionId(...) method has been invoked at least once on the returned instance.

Parameters:

api - The API for which to return a dimension.

Returns:

The dimension assigned to the given API.

getAPIForDimension

DimensionSlice.API getAPIForDimension(Object... identifiers)

Returns the API assigned to the given dimension identifiers. The identifiers can be any kind of objects accepted by the DimensionIdentification.addDimensionId(...) methods. Unknown identifiers are silently ignored.

If more than one dimension is found for the given identifiers, then a warning is emitted and this method returns the first dimension matching the given identifiers. If no dimension is found, null is returned.

Parameters:

identifiers - The identifiers of the dimension to query.

Returns:

The API assigned to the given dimension, or DimensionSlice.API.NONE if none.

getAPIForDimensions

Set<DimensionSlice.API> getAPIForDimensions()

Returns the set of APIs for which at least one dimension has identifiers. This is typically an empty set until the following code is invoked at least once:

getDimensionForAPI(...).addDimensionId(...);

Returns:

The API for which at least one dimension has identifiers.