org.geotoolkit.image.io
Class DimensionSlice

Object
  DimensionIdentification
      DimensionSlice

All Implemented Interfaces:

WarningProducer, Localized

public class DimensionSlice
extends DimensionIdentification

Tuple of a dimension identifier and index in that dimension for a slice to read or write in a data file. This class is relevant mostly for n-dimensional datasets where n>2. Each DimensionSlice instance applies to only one dimension; if the indices of a slice need to be specified for more than one dimension, then many instances of DimensionSlice will be required.

Note: The DimensionSlice name is used in the WCS 2.0 specification for the same purpose. The semantic of attributes are similar but not identical: the getDimensionIds() method in this class is equivalent to the dimension attribute in WCS 2.0, and the getSliceIndex() method is close to the slicePoint attribute. The main differences compared to WCS 2.0 are:

• The dimension can be identified by an index type, by an axis direction or by the name type as used in WCS 2.0.
• The dimension can be identified by more than one identifier, with conflicts trigging a warning.
• The slice point is an index offset in the discrete coverage, rather than a metric value in the continuous dimension.

This class refers always to the indices in the file, which can be either the source or the destination:

• When used with SpatialImageReadParam, this class contains the index of the section to read from the file (the source region).
• When used with SpatialImageWriteParam, this class contains the index of the section to write in the file (the destination offset).

In addition to the index, DimensionSlice also specifies the dimension on which the index applies. See the DimensionIdentification javadoc for more information about how dimensions are identified.

Example 1: Setting the indices in the time and depth dimensions
Instances of DimensionSlice can be created and used as below:

SpatialImageReadParam parameters = imageReader.getDefaultReadParam();

DimensionSlice timeSlice = parameters.newDimensionSlice();
timeSlice.addDimensionId("time");
timeSlice.setSliceIndex(25);

DimensionSlice depthSlice = parameters.newDimensionSlice();
depthSlice.addDimensionId("depth");
depthSlice.setSliceIndex(40);

// Read the (x,y) plane at time[25] and depth[40]
BufferedImage image = imageReader.read(0, parameters);

Example 2: Setting the indices in the third dimension
In a 4-D dataset having (x, y, z, t) dimensions when the time is known to be the dimension at index 3 (0-based numbering), read the (x, y) plane at time t₂₅:

DimensionSlice timeSlice = parameters.newDimensionSlice();
timeSlice.addDimensionId(3);
timeSlice.setSliceIndex(25);

If no setSliceIndex(int) method is invoked, then the default value is 0. This means that for the above-cited 4-D dataset, only the image at the first time (t₀) is selected by default. See Handling more than two dimensions in SpatialImageReadParam javadoc for more details.

Example 3: Setting the index of the vertical axis
Read the (x, y) plane at elevation z₂₅, where the index of the z dimension is unknown. We don't even known if the z dimension is actually a height or a depth. We can identify the dimension by its name, but it works only with file formats that provide support for named dimensions (like NetCDF). So we also identify the dimension by axis directions, which should works for any format:

DimensionSlice elevationSlice = parameters.newDimensionSlice();
elevationSlice.addDimensionId("height", "depth");
elevationSlice.addDimensionId(AxisDirection.UP, AxisDirection.DOWN);
elevationSlice.setSliceIndex(25);

If there is ambiguity (for example if both a dimension named "height" and an other dimension named "depth" exist), then a warning will be emitted at reading time and the index 25 will be set to the dimension named "height" because that name has been specified first.

Since:

3.08

Version:

3.15

Author:

Martin Desruisseaux (Geomatys)

See Also:

SpatialImageReadParam, MultidimensionalImageStore

Module:

coverage/geotk-coverageio (download)

View source code for this class

Nested Class Summary

static class

DimensionSlice.API The standard Java API used for selecting the slice to read or write in a particular dimension.

Field Summary

Fields inherited from interface WarningProducer

LOGGER

Constructor Summary

protected

DimensionSlice(DimensionSlice original) Creates a new instance initialized to the same values than the given instance.

Method Summary

int	getSliceIndex() Returns the index of the section to read or write along the dimension represented by this object.
void	setSliceIndex(int index) Sets the index of the region to read along the dimension represented by this object.
String	toString() Returns a string representation of this object.

Methods inherited from class DimensionIdentification

addDimensionId, addDimensionId, addDimensionId, findDimensionIndex, getDimensionIds, getLocale, hasDimensionIds, removeDimensionId, warningOccurred

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DimensionSlice

protected DimensionSlice(DimensionSlice original)

Creates a new instance initialized to the same values than the given instance. This copy constructor provides a way to substitute the instances created by SpatialImageReadParam.newDimensionSlice() by custom instances overriding some methods, as in the example below:

class MyParameters extends SpatialImageReadParam {
    MyParameters(ImageReader reader) {
        super(reader);
    }

    public DimensionSlice newDimensionSlice() {
        return new MySelection(super.newDimensionSlice());
    }
}

class MySelection extends DimensionSlice {
    MySelection(DimensionSlice original) {
        super(original);
    }

    // Override some methods here.
}

Parameters:

original - The instance to copy.

Method Detail

getSliceIndex

public int getSliceIndex()

Returns the index of the section to read or write along the dimension represented by this object. This method applies the following rules:

• For SpatialImageReadParam:
  • If the API is COLUMNS or ROWS, then this method invokes IIOParam.getSourceRegion() and returns the x or y attribute respectively, or 0 if the source region is not set.
  • Otherwise if the API is BANDS, then this method invokes IIOParam.getSourceBands() and returns the index of the first band, or 0 if the source bands are not set.
  • Otherwise this method returns the value set by the last call to setSliceIndex(int).
• For SpatialImageWriteParam:
  • If the API is COLUMNS or ROWS, then this method invokes IIOParam.getDestinationOffset() and returns the x or y attribute respectively, or 0 if the offset is not set.
  • Otherwise this method returns the value set by the last call to setSliceIndex(int).

Note: This method could have been named getFirstIndex() because it returns the index of the first element to read (often the lower index, but not always). However there would be no getLastIndex() method, because the default values to return when the source region or source bands are unspecified depend on information known only to the ImageReader when the input is set. This is probably not a major issue since the main purpose of this method is to get the index in extra dimensions where no standard Java API is available.

Returns:

The index of the first element to read/write in the dimension represented by this object.

See Also:

SpatialImageReadParam.getSliceIndex(Object[])

setSliceIndex

public void setSliceIndex(int index)

Sets the index of the region to read along the dimension represented by this object. This method applies the following rules:

• For SpatialImageReadParam:
  • If the API is COLUMNS or ROWS, then this method invokes IIOParam.setSourceRegion(Rectangle) with a x or y attribute set to the given index, and the corresponding width or height attribute set to 1.
  • Otherwise if the API is BANDS, then this method invokes IIOParam.setSourceBands(int[]) with the given index.
  • Otherwise this method stores the given index.
• For SpatialImageWriteParam:
  • If the API is COLUMNS or ROWS, then this method invokes IIOParam.setDestinationOffset(Point) with a x or y attribute set to the given index.
  • Otherwise this method stores the given index.

Parameters:

index - The slice point to read/write in the dimension represented by this object.

See Also:

SpatialImageReadParam.getSliceIndex(Object[])

toString

public String toString()

Returns a string representation of this object. The default implementation formats on a single line the class name, the list of dimension identifiers, the index and the API (if any).

Overrides:

toString in class DimensionIdentification

See Also:

SpatialImageReadParam.toString()