org.geotoolkit.coverage
Class CoverageStack

Object
  PropertySourceImpl
      AbstractCoverage
          CoverageStack

All Implemented Interfaces:

Serializable, PropertySource, Localized, Coverage

@ThreadSafe
public class CoverageStack
extends AbstractCoverage

Creates a (n+1) dimensional coverage from a collection of n dimensional coverages. For example given a list of Coverage2D at elevations z₀, z₁ … z_max, this class creates a new 3-dimensional coverages where the envelope is:

• the union of all coverage envelopes in the two first dimensions,
• [z₀ … z_max] in the third dimension.

Collections of CoverageStacks can be given recursively to other CoverageStack for creating new coverages with higher dimensionality.

NOTE: For documentation purpose, the new dimension handled by CoverageStack is named z. But this is only a naming convention - the new dimension can really be anything, including time.

Construction
GridCoverage2D objects tend to be big. In order to keep memory usage reasonable, this implementation doesn't requires all GridCoverage2D objects at once. Instead, it requires an array of CoverageStack.Element objects, which will load the coverage content only when first needed.

Each element usually have the same envelope, but this is not a requirement. Elements are not required to share the same Coordinate Reference System neither, but they are required to handle the transformation from this coverage CRS to their CRS.

Usage
Each coverage element is expected to extend over a range of z values. If an evaluate(...) method is invoked with a z value not falling in the middle of a coverage element, a linear interpolation is applied.

Caching
This CoverageStack implementation remember the last coverage elements used; it will not trig new data loading as long as consecutive calls to evaluate(...) methods require the same coverage elements. Apart from this very simple mechanism, caching is the responsibility of CoverageStack.Element implementations. Note that this simple caching mechanism is sufficient if evaluate(...) methods are invoked with increasing z values.

Since:

2.1

Version:

3.16

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

Serialized Form

Module:

coverage/geotk-coverage (download)

View source code for this class

Nested Class Summary

static class	CoverageStack.Adapter A convenience adapter class for wrapping a pre-loaded Coverage into an CoverageStack.Element object.
static interface	CoverageStack.Element Reference to a single n dimensional coverage in a (n+1) dimensional coverage stack.

Nested classes/interfaces inherited from class AbstractCoverage

AbstractCoverage.Renderable

Field Summary

int	zDimension The dimension of the z ordinate.

Fields inherited from class AbstractCoverage

crs

Fields inherited from class PropertySourceImpl

cachedPropertyNames, properties, propertySources

Constructor Summary

	CoverageStack(CharSequence name, Collection<? extends Coverage> coverages) Constructs a new coverage stack with all the supplied elements.
	CoverageStack(CharSequence name, CoordinateReferenceSystem crs, Collection<? extends CoverageStack.Element> elements) Constructs a new coverage stack with all the supplied elements.
protected	CoverageStack(CharSequence name, CoverageStack source) Constructs a new coverage using the same elements than the specified coverage stack.

Method Summary

void	addIIOReadProgressListener(IIOReadProgressListener listener) Adds an IIOReadProgressListener to the list of registered progress listeners.
void	addIIOReadWarningListener(IIOReadWarningListener listener) Adds an IIOReadWarningListener to the list of registered warning listeners.
List<Coverage>	coveragesAt(double z) Returns the coverages to be used for the specified z value.
Object	evaluate(DirectPosition coord) Returns a sequence of values for a given point in the coverage.
boolean[]	evaluate(DirectPosition coord, boolean[] dest) Returns a sequence of boolean values for a given point in the coverage.
byte[]	evaluate(DirectPosition coord, byte[] dest) Returns a sequence of byte values for a given point in the coverage.
double[]	evaluate(DirectPosition coord, double[] dest) Returns a sequence of double values for a given point in the coverage.
float[]	evaluate(DirectPosition coord, float[] dest) Returns a sequence of float values for a given point in the coverage.
int[]	evaluate(DirectPosition coord, int[] dest) Returns a sequence of integer values for a given point in the coverage.
Envelope	getEnvelope() Returns the bounding box for the coverage domain in coordinate system coordinates.
int	getNumSampleDimensions() Returns the number of sample dimension in this coverage.
SampleDimension	getSampleDimension(int index) Retrieve sample dimension information for the coverage.
boolean	isInterpolationEnabled() Returns true if interpolation are enabled in the z value dimension.
protected void	logLoading(LogRecord record) Invoked automatically when an image is about to be loaded.
void	removeIIOReadProgressListener(IIOReadProgressListener listener) Removes an IIOReadProgressListener from the list of registered progress listeners.
void	removeIIOReadWarningListener(IIOReadWarningListener listener) Removes an IIOReadWarningListener from the list of registered warning listeners.
void	setInterpolationEnabled(boolean enabled) Enable or disable interpolations in the z value dimension.
void	snap(DirectPosition point) Snaps the specified coordinate point to the coordinate of the nearest voxel available in this coverage.

Methods inherited from class AbstractCoverage

dispose, evaluate, evaluateInverse, find, find, getCommonPointRule, getCoordinateReferenceSystem, getDimension, getDomainElements, getDomainExtents, getLocale, getName, getRangeElements, getRangeType, getRenderableImage, getSources, list, select, show, show, show, toString

Methods inherited from class PropertySourceImpl

getProperties, getProperty, getPropertyClass, getPropertyNames, getPropertyNames

Methods inherited from class Object

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

Field Detail

zDimension

public final int zDimension

The dimension of the z ordinate. This is typically the Coordinate Reference System dimension minus 1.

This field is named z dimension by convention only. The dimension doesn't need to be the vertical axis. It can be a temporal or any other kind of dimension.

Since:

2.3

Constructor Detail

CoverageStack

public CoverageStack(CharSequence name,
                     Collection<? extends Coverage> coverages)
              throws IOException

Constructs a new coverage stack with all the supplied elements. Every coverages must specify their z range in the last dimension of their envelope, and at least one of those envelopes shall be associated with a CRS (the later is always the case with Geotk implementations of Coverage). The example below constructs two dimensional grid coverages (to be given as the coverages argument) for the same geographic area, but at different elevations:

GridCoverageFactory     factory = ...;
CoordinateReferenceSystem crs2D = ...;  // Yours horizontal CRS.
TemporalCRS             timeCRS = ...;  // Yours CRS for time measurement.
CoordinateReferenceSystem crs3D = new CompoundCRS(crs3D, timeCRS);

List<Coverage> coverages = new ArrayList<Coverage>();
GeneralEnvelope envelope = new GeneralEnvelope(DefaultGeographicCRS.WGS84_3D);
envelope.setRange(0, westLongitudeBound, eastLongitudeBound);
envelope.setRange(1, southLatitudeBound, northLatitudeBound);
for (int i=0; i<...; i++) {
    envelope.setRange(2, minElevation, maxElevation);
    coverages.add(factory.create(..., crs, envelope, ...));
}

This convenience constructor wraps all coverage into Adapter objects. Users with a significant amount of data are encouraged to use the constructor expecting Element objects instead, in order to provide their own implementation loading data only when needed.

Parameters:

name - The name for this coverage.

coverages - All Coverage elements for this stack.

Throws:

IOException - if an I/O operation was required and failed.

CoverageStack

public CoverageStack(CharSequence name,
                     CoordinateReferenceSystem crs,
                     Collection<? extends CoverageStack.Element> elements)
              throws IOException

Constructs a new coverage stack with all the supplied elements. Each element can specify its z range either in the last dimension of its envelope, or as a separated range.

If crs is null, this constructor will try to infer the CRS from the element envelope but at least one of those must be associated with a full CRS (including the z dimension).

Parameters:

name - The name for this coverage.

crs - The coordinate reference system for this coverage, or null.

elements - All coverage Elements for this stack.

Throws:

IOException - if an I/O operation was required and failed.

CoverageStack

protected CoverageStack(CharSequence name,
                        CoverageStack source)

Constructs a new coverage using the same elements than the specified coverage stack.

Parameters:

name - The coverage name.

source - The stack to copy.

Method Detail

getEnvelope

public Envelope getEnvelope()

Returns the bounding box for the coverage domain in coordinate system coordinates.

Specified by:

getEnvelope in interface Coverage

Overrides:

getEnvelope in class AbstractCoverage

Returns:

The bounding box for the coverage domain in coordinate system coordinates.

getNumSampleDimensions

public int getNumSampleDimensions()

Returns the number of sample dimension in this coverage.

getSampleDimension

public SampleDimension getSampleDimension(int index)

Retrieve sample dimension information for the coverage. For a grid coverage, a sample dimension is a band. The sample dimension information include such things as description, data type of the value (bit, byte, integer...), the no data values, minimum and maximum values and a color table if one is associated with the dimension.

snap

public void snap(DirectPosition point)
          throws IOException

Snaps the specified coordinate point to the coordinate of the nearest voxel available in this coverage. Invoking any evaluate(...) method with snapped coordinates will return non-interpolated values.

• First, this method locates the coverage element at or near the last ordinate value (the z value). If no coverage is available at the specified z value, then the nearest one is selected.
• Next, this method locates the pixel under the point coordinate in the coverage element.
• The point is then set to the pixel center coordinate and to the z value of the selected coverage element.

Parameters:

point - The point to snap.

Throws:

IOException - if an I/O operation was required but failed.

evaluate

public Object evaluate(DirectPosition coord)
                throws PointOutsideCoverageException,
                       CannotEvaluateException

Returns a sequence of values for a given point in the coverage. The default implementation delegates to the evaluate(DirectPosition, double[]) method.

Parameters:

coord - The coordinate point where to evaluate.

Returns:

The value at the specified point.

Throws:

PointOutsideCoverageException - if coord is outside coverage.

CannotEvaluateException - if the computation failed for some other reason.

evaluate

public boolean[] evaluate(DirectPosition coord,
                          boolean[] dest)
                   throws PointOutsideCoverageException,
                          CannotEvaluateException

Returns a sequence of boolean values for a given point in the coverage.

Specified by:

evaluate in interface Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - The coordinate point where to evaluate.

dest - An array in which to store values, or null to create a new array.

Returns:

The dest array, or a newly created array if dest was null.

Throws:

PointOutsideCoverageException - if coord is outside coverage.

CannotEvaluateException - if the computation failed for some other reason.

evaluate

public byte[] evaluate(DirectPosition coord,
                       byte[] dest)
                throws PointOutsideCoverageException,
                       CannotEvaluateException

Returns a sequence of byte values for a given point in the coverage.

Specified by:

evaluate in interface Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - The coordinate point where to evaluate.

dest - An array in which to store values, or null to create a new array.

Returns:

The dest array, or a newly created array if dest was null.

Throws:

PointOutsideCoverageException - if coord is outside coverage.

CannotEvaluateException - if the computation failed for some other reason.

evaluate

public int[] evaluate(DirectPosition coord,
                      int[] dest)
               throws PointOutsideCoverageException,
                      CannotEvaluateException

Returns a sequence of integer values for a given point in the coverage.

Specified by:

evaluate in interface Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - The coordinate point where to evaluate.

dest - An array in which to store values, or null to create a new array.

Returns:

The dest array, or a newly created array if dest was null.

Throws:

PointOutsideCoverageException - if coord is outside coverage.

CannotEvaluateException - if the computation failed for some other reason.

evaluate

public float[] evaluate(DirectPosition coord,
                        float[] dest)
                 throws PointOutsideCoverageException,
                        CannotEvaluateException

Returns a sequence of float values for a given point in the coverage.

Specified by:

evaluate in interface Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - The coordinate point where to evaluate.

dest - An array in which to store values, or null to create a new array.

Returns:

The dest array, or a newly created array if dest was null.

Throws:

PointOutsideCoverageException - if coord is outside coverage.

CannotEvaluateException - if the computation failed for some other reason.

evaluate

public double[] evaluate(DirectPosition coord,
                         double[] dest)
                  throws PointOutsideCoverageException,
                         CannotEvaluateException

Returns a sequence of double values for a given point in the coverage.

Specified by:

evaluate in interface Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - The coordinate point where to evaluate.

dest - An array in which to store values, or null to create a new array.

Returns:

The dest array, or a newly created array if dest was null.

Throws:

PointOutsideCoverageException - if coord is outside coverage.

CannotEvaluateException - if the computation failed for some other reason.

coveragesAt

public List<Coverage> coveragesAt(double z)

Returns the coverages to be used for the specified z value. Special cases:

• If there is no coverage available for the specified z value, returns an empty list.
• If there is only one coverage available, or if the specified z value falls exactly in the middle of the range value (i.e. no interpolation are needed), or if interpolations are disabled, then this method returns a singleton.
• Otherwise, this method returns a list containing at least 2 coverages, one before and one after the specified z value.

Parameters:

z - The z value for the coverages to be returned.

Returns:

The coverages for the specified values. May contains 0, 1 or 2 elements.

Since:

2.3

isInterpolationEnabled

public boolean isInterpolationEnabled()

Returns true if interpolation are enabled in the z value dimension. Interpolations are enabled by default.

Returns:

true if interpolation are enabled in the z value dimension.

setInterpolationEnabled

public void setInterpolationEnabled(boolean enabled)

Enable or disable interpolations in the z value dimension.

Parameters:

enabled - true if interpolation should be enabled in the z value dimension.

addIIOReadWarningListener

public void addIIOReadWarningListener(IIOReadWarningListener listener)

Adds an IIOReadWarningListener to the list of registered warning listeners.

Parameters:

listener - The listener to add.

removeIIOReadWarningListener

public void removeIIOReadWarningListener(IIOReadWarningListener listener)

Removes an IIOReadWarningListener from the list of registered warning listeners.

Parameters:

listener - The listener to remove.

addIIOReadProgressListener

public void addIIOReadProgressListener(IIOReadProgressListener listener)

Adds an IIOReadProgressListener to the list of registered progress listeners.

Parameters:

listener - The listener to add.

removeIIOReadProgressListener

public void removeIIOReadProgressListener(IIOReadProgressListener listener)

Removes an IIOReadProgressListener from the list of registered progress listeners.

Parameters:

listener - The listener to remove.

logLoading

protected void logLoading(LogRecord record)

Invoked automatically when an image is about to be loaded. The default implementation logs the message in the "org.geotoolkit.coverage" logger. Subclasses can override this method if they wants a different logging.

Parameters:

record - The log record. The message contains information about the images to load.