org.geotools.coverage
Class CoverageStack

java.lang.Object
  extended by javax.media.jai.PropertySourceImpl
      extended by org.geotools.coverage.AbstractCoverage
          extended by org.geotools.coverage.CoverageStack
All Implemented Interfaces:
java.io.Serializable, javax.media.jai.PropertySource, org.opengis.coverage.Coverage

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 GridCoverage2D is for a different date. This CoverageStack manages the two-dimensional coverages as if the whole set was a three-dimensional coverage.

Each coverage element in the stack usually covers the same geographic area, but this is not a requirement. As of GeoTools 2.5, elements are not required to have the same coordinate reference system neither, but they are required to handle the transformation from this coverage CRS to their CRS.

Coverage elements are often two-dimensional, but this is not a requirement. This stack will simply append one dimension to the element CRS. Coverage elements may be themself backed by instances of CoverateStack, thus allowing construction of coverages with four or more dimensions.

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

GridCoverage2D objects tend to be big. In order to keep memory usage raisonable, this implementation doesn't requires all GridCoverage objects at once. Instead, it requires an array of CoverageStack.Element objects, which will load the coverage content only when first needed. 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 caching mechanism, caching is the responsability of CoverageStack.Element implementations. Note that this simple caching mechanism is suffisient if evaluate(...) methods are invoked with increasing z values.

Each coverage element is expected to extends 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.

CoverageStack implementation is thread-safe.

Since:
2.1
Version:
$Id: CoverageStack.java 32440 2009-02-09 11:14:54Z acuster $
Author:
Martin Desruisseaux (IRD)
See Also:
Serialized Form

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
          An element in a coverage stack.
 
Nested classes/interfaces inherited from class org.geotools.coverage.AbstractCoverage
AbstractCoverage.Renderable
 
Field Summary
 int zDimension
          The dimension of the z ordinate (the last value in coordinate points).
 
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<? extends org.opengis.coverage.Coverage> 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<? extends CoverageStack.Element> 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.util.List<org.opengis.coverage.Coverage> coveragesAt(double z)
          Returns the coverages to be used for the specified z value.
 java.lang.Object evaluate(org.opengis.geometry.DirectPosition coord)
          Returns a sequence of values for a given point in the coverage.
 boolean[] evaluate(org.opengis.geometry.DirectPosition coord, boolean[] dest)
          Returns a sequence of boolean values for a given point in the coverage.
 byte[] evaluate(org.opengis.geometry.DirectPosition coord, byte[] dest)
          Returns a sequence of byte values for a given point in the coverage.
 double[] evaluate(org.opengis.geometry.DirectPosition coord, double[] dest)
          Returns a sequence of double values for a given point in the coverage.
 float[] evaluate(org.opengis.geometry.DirectPosition coord, float[] dest)
          Returns a sequence of float values for a given point in the coverage.
 int[] evaluate(org.opengis.geometry.DirectPosition coord, int[] dest)
          Returns a sequence of integer values for a given point in the coverage.
 org.opengis.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 true 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.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, 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 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
 

Field Detail

zDimension

public final int zDimension
The dimension of the z ordinate (the last value in coordinate points). This is always the coordinate reference system dimension minus 1.

Since:
2.3
Constructor Detail

CoverageStack

public CoverageStack(java.lang.CharSequence name,
                     java.util.Collection<? extends org.opengis.coverage.Coverage> coverages)
              throws java.io.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 GeoTools 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 intos an 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<? extends CoverageStack.Element> elements)
              throws java.io.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:
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.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.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 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. Consequently, calling any evaluate(...) 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.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 coord is outside coverage.
org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

evaluate

public boolean[] evaluate(org.opengis.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 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.
org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

evaluate

public byte[] evaluate(org.opengis.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 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.
org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

evaluate

public int[] evaluate(org.opengis.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 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.
org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

evaluate

public float[] evaluate(org.opengis.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 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.
org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

evaluate

public double[] evaluate(org.opengis.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 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.
org.opengis.coverage.CannotEvaluateException - if the computation failed for some other reason.

coveragesAt

public java.util.List<org.opengis.coverage.Coverage> coveragesAt(double z)
Returns the coverages to be used for the specified z value. Special cases:

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.


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 "org.geotools.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.


Copyright © 1996-2010 Geotools. All Rights Reserved.