org.geotools.coverage
Class CoverageStack

java.lang.Object
  javax.media.jai.PropertySourceImpl
      org.geotools.coverage.AbstractCoverage
          org.geotools.coverage.CoverageStack

All Implemented Interfaces:

org.opengis.coverage.Coverage, javax.media.jai.PropertySource, java.io.Serializable

public class CoverageStack

extends AbstractCoverage

Wraps a stack of coverages as an extra dimension. For example this class can wraps an array of GridCoverage2D on the same geographic area, but where each is for a different date. This manages the two-dimensional coverages as if the whole set was a huge three-dimensional coverage.

Each coverage element in the stack usually covers the same geographic area, but this is not a requirement. However, they must use the same coordinate reference system. For performance reason, the later condition will not be checked except at construction time if the CRS is provided in the envelope, and at evaluation time if Java assertion are enabled. If the CRS of coverage elements is uncertain, consider wrapping them in a TransformedCoverage object.

Coverage elements are often two-dimensional, but this is not a requirement. This stack will simply append one more dimension to the coverage element's CRS dimensions. Coverage elements may be other objects, thus allowing construction of coverages with four or more dimensions.

objects tend to be big. In order to keep memory usage raisonable, this implementation doesn't requires all objects at once. Instead, it requires an array of CoverageStack.Element objects, which will load the coverage content only when first needed. This implementation remember the last coverage elements used; it will not trig new data loading as long as consecutive calls to methods require the same coverage elements. Apart from this very simple caching mechanism, caching is the responsability of CoverageStack.Element implementations. Note that this simple caching mechanism is suffisient if methods are invoked with increasing z values.

Each coverage element is expected to extends over a range of z values (the new dimensions appended by this ). If an method is invoked with a z value not falling in the middle of a coverage element, a linear interpolation is applied.

Note: This implementation is thread-safe.

Since:

2.1

Version:

$Id: CoverageStack.java 17672 2006-01-19 00:25:55Z desruisseaux $

Author:

Martin Desruisseaux

See Also:

Serialized Form

Nested Class Summary

static class	CoverageStack.Adapter A convenience adapter class for wrapping a pre-loaded Coverage into an Element object.
static interface	CoverageStack.Element An element in a coverage stack.

Nested classes inherited from class org.geotools.coverage.AbstractCoverage

AbstractCoverage.Renderable

Field Summary

Fields inherited from class org.geotools.coverage.AbstractCoverage

crs

Fields inherited from class javax.media.jai.PropertySourceImpl

cachedPropertyNames, properties, propertySources

Constructor Summary

	CoverageStack(java.lang.CharSequence name, java.util.Collection coverages) Constructs a new coverage stack with all the supplied elements.
	CoverageStack(java.lang.CharSequence name, org.opengis.referencing.crs.CoordinateReferenceSystem crs, java.util.Collection elements) Constructs a new coverage stack with all the supplied elements.
protected	CoverageStack(java.lang.CharSequence name, CoverageStack source) Constructs a new coverage using the same elements than the specified coverage stack.

Method Summary

void	addIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener listener) Adds an IIOReadProgressListener to the list of registered progress listeners.
void	addIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener listener) Adds an IIOReadWarningListener to the list of registered warning listeners.
java.lang.Object	evaluate(org.opengis.spatialschema.geometry.DirectPosition coord) Returns a sequence of values for a given point in the coverage.
boolean[]	evaluate(org.opengis.spatialschema.geometry.DirectPosition coord, boolean[] dest) Returns a sequence of boolean values for a given point in the coverage.
byte[]	evaluate(org.opengis.spatialschema.geometry.DirectPosition coord, byte[] dest) Returns a sequence of byte values for a given point in the coverage.
double[]	evaluate(org.opengis.spatialschema.geometry.DirectPosition coord, double[] dest) Returns a sequence of double values for a given point in the coverage.
float[]	evaluate(org.opengis.spatialschema.geometry.DirectPosition coord, float[] dest) Returns a sequence of float values for a given point in the coverage.
int[]	evaluate(org.opengis.spatialschema.geometry.DirectPosition coord, int[] dest) Returns a sequence of integer values for a given point in the coverage.
org.opengis.spatialschema.geometry.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.
org.opengis.coverage.SampleDimension	getSampleDimension(int index) Retrieve sample dimension information for the coverage.
boolean	isInterpolationEnabled() Returns if interpolation are enabled in the z value dimension.
protected void	logLoading(java.util.logging.LogRecord record) Invoked automatically when an image is about to be loaded.
void	removeIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener listener) Removes an IIOReadProgressListener from the list of registered progress listeners.
void	removeIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener listener) Removes an IIOReadWarningListener from the list of registered warning listeners.
void	setInterpolationEnabled(boolean flag) Enable or disable interpolations in the z value dimension.
void	snap(org.opengis.spatialschema.geometry.DirectPosition point) Snaps the specified coordinate point to the coordinate of the nearest voxel available in this coverage.

Methods inherited from class org.geotools.coverage.AbstractCoverage

dispose, getCoordinateReferenceSystem, getDimension, getDimensionNames, getDimensionNames, getLocale, getMetadataNames, getMetadataValue, getName, getRenderableImage, getSources, show, show, toString

Methods inherited from class javax.media.jai.PropertySourceImpl

getProperties, getProperty, getPropertyClass, getPropertyNames, getPropertyNames

Methods inherited from class java.lang.Object

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

Constructor Detail

CoverageStack

public CoverageStack(java.lang.CharSequence name,
                     java.util.Collection coverages)
              throws java.io.IOException

Constructs a new coverage stack with all the supplied elements. All coverages must uses the same coordinate reference system. Additionnaly, all coverages must specify their z value in the last dimension of their envelope. The example below constructs two dimensional grid coverages (to be given as the argument) for the same area, but at different times:

 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(3); // A 3-dimensional envelope.
 envelope.setRange(...);                            // Set the horizontal part.
 for (int i=0; i<...; i++) {
     envelope.setRange(2, startTime, endTime);
     coverages.add(factory.create(..., crs, envelope, ...);
 }
 

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

Parameters:

name - The name for this coverage.

coverages - All Coverage elements for this stack.

Throws:

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

CoverageStack

public CoverageStack(java.lang.CharSequence name,
                     org.opengis.referencing.crs.CoordinateReferenceSystem crs,
                     java.util.Collection elements)
              throws java.io.IOException

Constructs a new coverage stack with all the supplied elements.

Parameters:

name - The name for this coverage.

crs - The coordinate reference system for this coverage.

elements - All coverage Elements for this stack.

Throws:

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

CoverageStack

protected CoverageStack(java.lang.CharSequence name,
                        CoverageStack source)

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

Method Detail

getEnvelope

public org.opengis.spatialschema.geometry.Envelope getEnvelope()

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

Specified by:

getEnvelope in interface org.opengis.coverage.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 org.opengis.coverage.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(org.opengis.spatialschema.geometry.DirectPosition point)
          throws java.io.IOException

Snaps the specified coordinate point to the coordinate of the nearest voxel available in this coverage. First, this method locate 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 locate the pixel under the coordinate in the coverage element. The is then set to the pixel center coordinate and to the z value of the selected coverage element. Consequently, calling any method with snapped coordinates will returns non-interpolated values.

Parameters:

point - The point to snap.

Throws:

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

evaluate

public java.lang.Object evaluate(org.opengis.spatialschema.geometry.DirectPosition coord)
                          throws org.opengis.coverage.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 is outside coverage.

org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

evaluate

public boolean[] evaluate(org.opengis.spatialschema.geometry.DirectPosition coord,
                          boolean[] dest)
                   throws org.opengis.coverage.CannotEvaluateException

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

Specified by:

evaluate in interface org.opengis.coverage.Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - The coordinate point where to evaluate.

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

Returns:

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

Throws:

PointOutsideCoverageException - if is outside coverage.

org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

evaluate

public byte[] evaluate(org.opengis.spatialschema.geometry.DirectPosition coord,
                       byte[] dest)
                throws org.opengis.coverage.CannotEvaluateException

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

Specified by:

evaluate in interface org.opengis.coverage.Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - The coordinate point where to evaluate.

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

Returns:

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

Throws:

PointOutsideCoverageException - if is outside coverage.

org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

evaluate

public int[] evaluate(org.opengis.spatialschema.geometry.DirectPosition coord,
                      int[] dest)
               throws org.opengis.coverage.CannotEvaluateException

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

Specified by:

evaluate in interface org.opengis.coverage.Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - The coordinate point where to evaluate.

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

Returns:

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

Throws:

PointOutsideCoverageException - if is outside coverage.

org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

evaluate

public float[] evaluate(org.opengis.spatialschema.geometry.DirectPosition coord,
                        float[] dest)
                 throws org.opengis.coverage.CannotEvaluateException

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

Specified by:

evaluate in interface org.opengis.coverage.Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - The coordinate point where to evaluate.

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

Returns:

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

Throws:

PointOutsideCoverageException - if is outside coverage.

org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

evaluate

public double[] evaluate(org.opengis.spatialschema.geometry.DirectPosition coord,
                         double[] dest)
                  throws org.opengis.coverage.CannotEvaluateException

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

Specified by:

evaluate in interface org.opengis.coverage.Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - The coordinate point where to evaluate.

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

Returns:

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

Throws:

PointOutsideCoverageException - if is outside coverage.

org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

isInterpolationEnabled

public boolean isInterpolationEnabled()

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

setInterpolationEnabled

public void setInterpolationEnabled(boolean flag)

Enable or disable interpolations in the z value dimension.

addIIOReadWarningListener

public void addIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener listener)

Adds an IIOReadWarningListener to the list of registered warning listeners.

removeIIOReadWarningListener

public void removeIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener listener)

Removes an IIOReadWarningListener from the list of registered warning listeners.

addIIOReadProgressListener

public void addIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener listener)

Adds an IIOReadProgressListener to the list of registered progress listeners.

removeIIOReadProgressListener

public void removeIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener listener)

Removes an IIOReadProgressListener from the list of registered progress listeners.

logLoading

protected void logLoading(java.util.logging.LogRecord record)

Invoked automatically when an image is about to be loaded. The default implementation logs the message in the 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.