org.geotoolkit.image.io
Class DimensionIdentification

Object
  DimensionIdentification

All Implemented Interfaces:

WarningProducer, Localized

Direct Known Subclasses:

DimensionSlice

public class DimensionIdentification
extends Object
implements WarningProducer

Identifies a domain dimension by its index, its name or its axis direction. This class is relevant mostly for n-dimensional datasets where n>2. The dimension can be identified in any of the following ways:

• As a zero-based index using an Integer. This is the most straightforward approach when the set of dimensions is known.

  Example: If the dimensions are known to be (x, y, z, t), then the t dimension can be identified by the index 3.

• As a dimension name using a String. This is a better approach than indexes when dimensions have known names, because it is insensitive to dimension order and whatever other dimensions exist or not.

  Example: If the list of dimensions can be either ("longitude", "latitude", "depth", "time") or ("latitude", "longitude", "time"), then the index of the time dimension can be either 3 or 2. It is better to identify the time dimension by its name: "time".

• As a direction using an AxisDirection. This provides similar benefit to using a named dimension, but can work without knowledge of the actual name. It can also be used with file formats that don't support named dimensions.

More than one identifier can be used in order to increase the chance of finding the dimension. For example in order to fetch the z dimension, it may be necessary to specify two names: "height" and "depth". In case of ambiguity, a warning will be emitted to any registered listeners at image reading or writing time.

See the DimensionSlice javadoc for usage examples.

Since:

3.15

Version:

3.15

Author:

Martin Desruisseaux (Geomatys)

See Also:

MultidimensionalImageStore, IllegalImageDimensionException

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary

Fields inherited from interface WarningProducer

LOGGER

Constructor Summary

protected

DimensionIdentification(DimensionSet owner, DimensionSlice.API api) Creates a new DimensionIdentification instance for the given API.

Method Summary

void	addDimensionId(AxisDirection... axes) Adds an identifier for the dimension represented by this object.
void	addDimensionId(int index) Declares the index for the dimension represented by this object.
void	addDimensionId(String... names) Adds an identifier for the dimension represented by this object.
int	findDimensionIndex(Iterable<?> properties) Returns the index of this dimension in a data file.
Object[]	getDimensionIds() Returns all identifiers for this dimension.
Locale	getLocale() Returns the locale used for formatting error messages, or null if none.
boolean	hasDimensionIds() Returns true if this dimension contains at least one identifier.
void	removeDimensionId(Object... identifiers) Removes identifiers for the dimension represented by this object.
String	toString() Returns a string representation of this object.
boolean	warningOccurred(LogRecord record) Invoked when a warning occurred.

Methods inherited from class Object

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

Constructor Detail

DimensionIdentification

protected DimensionIdentification(DimensionSet owner,
                                  DimensionSlice.API api)
                           throws IllegalArgumentException

Creates a new DimensionIdentification instance for the given API. This constructor is protected for subclasses usage only. The public API for fetching new instances is the DimensionSet.getOrCreate(DimensionSlice.API) method.

Parameters:

owner - The collection that created this object.

api - The API to assign to this dimension.

Throws:

IllegalArgumentException - If an other dimension is already assigned to the given API.

Method Detail

addDimensionId

public void addDimensionId(int index)
                    throws IllegalArgumentException

Declares the index for the dimension represented by this object. For example in a 4-D dataset having (x, y, z, t) dimensions where the time dimension is known to be the dimension #3 (0-based numbering), users may want to read the (x, y) plane at time t₂₅. This can be done by invoking:

addDimensionId(3);
setSliceIndex(25);

Note: The setSliceIndex(int) method is available only if this object is actually an instance of DimensionSlice.

Parameters:

index - The index of the dimension. Must be non-negative.

Throws:

IllegalArgumentException - If the given dimension index is negative or already assigned to an other DimensionSlice instance.

addDimensionId

public void addDimensionId(String... names)
                    throws IllegalArgumentException

Adds an identifier for the dimension represented by this object. The dimension is identified by name, which works only with file formats that provide support for named dimensions (e.g. NetCDF). For example in a dataset having either (x, y, z, t) or (x, y, t) dimensions, users may want to read the (x, y) plane at time t₂₅ without knowing if the time dimension is the third or the fourth one. This can be done by invoking:

addDimensionId("time");
setSliceIndex(25);

Note: The setSliceIndex(int) method is available only if this object is actually an instance of DimensionSlice.

More than one name can be specified if they should be considered as possible identifiers for the same dimension. For example in order to set the index for the z dimension, it may be necessary to specify both the "height" and "depth" names.

Parameters:

names - The names of the dimension.

Throws:

IllegalArgumentException - If a name is already assigned to an other DimensionSlice instance.

addDimensionId

public void addDimensionId(AxisDirection... axes)
                    throws IllegalArgumentException

Adds an identifier for the dimension represented by this object. The dimension is identified by axis direction. For example in a dataset having either (x, y, z, t) or (x, y, t) dimensions, users may want to read the (x, y) plane at time t₂₅ without knowing if the time dimension is the third or the fourth one. This can be done by invoking:

addDimensionId(AxisDirection.FUTURE);
setSliceIndex(25);

Note: The setSliceIndex(int) method is available only if this object is actually an instance of DimensionSlice.

More than one direction can be specified if they should be considered as possible identifiers for the same dimension. For example in order to set the index for the z dimension, it may be necessary to specify both the UP and DOWN directions.

Parameters:

axes - The axis directions of the dimension.

Throws:

IllegalArgumentException - If a name is already assigned to an other DimensionSlice instance.

removeDimensionId

public void removeDimensionId(Object... identifiers)

Removes identifiers for the dimension represented by this object. The identifiers argument can contain the identifiers given to any addDimensionId(...) method. Unknown identifiers are silently ignored.

Parameters:

identifiers - The identifiers to remove.

getDimensionIds

public Object[] getDimensionIds()

Returns all identifiers for this dimension. The array returned by this method contains the arguments given to any addDimensionId(...) method call on this instance.

Returns:

All identifiers for this dimension.

hasDimensionIds

public boolean hasDimensionIds()

Returns true if this dimension contains at least one identifier. Invoking this method is equivalent to the code below, but is potentially more efficient:

boolean hasDimensionIds = (getDimensionIds().length != 0);

Returns:

true if this dimension contains at least one identifier.

findDimensionIndex

public int findDimensionIndex(Iterable<?> properties)

Returns the index of this dimension in a data file. This method is invoked by some SpatialImageReader or SpatialImageWriter subclasses when a dataset is about to be read from a file, or written to a file. The caller needs to know the set of dimensions that exist in the file dataset, which may not be identical to the set of dimensions declared in SpatialImageReadParam or SpatialImageWriteParam.

The default implementation makes the following choice:

1. If addDimensionId(int) has been invoked, then the value specified to that method is returned regardless the properties argument value.

2. Otherwise if an other addDimensionId(...) method has been invoked and the properties argument is non-null, then this method iterates over the given properties. The iteration must return exactly one element for each dimension, in order. If an element is equals to a value specified to a addDimensionId(...) method, then the position of that element in the properties iteration is returned.

3. Otherwise this method returns -1.

If more than one dimension match, then a warning is emitted and this method returns the index of the first property matching an identifier.

Parameters:

properties - Contains one property (the dimension name as a String or the axis direction as an AxisDirection) for each dimension in the dataset being read or written. The iteration order shall be the order of dimensions in the dataset. This argument can be null if no such properties are available.

Returns:

The index of the dimension, or -1 if none.

getLocale

public Locale getLocale()

Returns the locale used for formatting error messages, or null if none.

Specified by:

getLocale in interface Localized

Returns:

The locale, or null if not explicitly defined.

warningOccurred

public boolean warningOccurred(LogRecord record)

Invoked when a warning occurred. The default implementation forwards the warning to the image reader or writer if possible, or logs the warning otherwise.

Specified by:

warningOccurred in interface WarningProducer

Parameters:

record - The warning that occurred.

Returns:

true if the message has been sent to at least one warning listener, or false if it has been sent to the logging system as a fallback.

toString

public String toString()

Returns a string representation of this object. The default implementation formats on a single line the class name and the list of dimension identifiers.

Overrides:

toString in class Object

See Also:

SpatialImageReadParam.toString()