org.geotools.coverage.grid
Class GridCoverage2D

Object
  extended by PropertySourceImpl
      extended by AbstractCoverage
          extended by AbstractGridCoverage
              extended by GridCoverage2D
All Implemented Interfaces:
Serializable, PropertySource, RenderedCoverage, Coverage, GridCoverage
Direct Known Subclasses:
Calculator2D

public class GridCoverage2D
extends AbstractGridCoverage
implements RenderedCoverage

Basic access to grid data values backed by a two-dimensional rendered image. Each band in an image is represented as a sample dimension.

Grid coverages are usually two-dimensional. However, their envelope may have more than two dimensions. For example, a remote sensing image may be valid only over some time range (the time of satellite pass over the observed area). Envelopes for such grid coverage can have three dimensions: the two usual ones (horizontal extent along x and y), and a third one for start time and end time (time extent along t). However, the grid range for all extra-dimension must have a size not greater than 1. In other words, a GridCoverage2D can be a slice in a 3 dimensional grid coverage. Each slice can have an arbitrary width and height (like any two-dimensional images), but only 1 voxel depth (a "voxel" is a three-dimensional pixel).

Serialization note:
Because it is serializable, GridCoverage2D can be included as method argument or as return type in Remote Method Invocation (RMI). However, the pixel data are not sent during serialization. Instead, the image data are transmitted "on-demand" using socket communications. This mechanism is implemented using JAI SerializableRenderedImage class. While serialization (usually on server side) should work on J2SE 1.4 and above, deserialization (usually on client side) of GridCoverage2D instances requires J2SE 1.5.

Since:
2.1
Author:
Martin Desruisseaux (IRD)
See Also:
Serialized Form
Module:

Nested Class Summary
protected  class GridCoverage2D.Renderable
          A view of a grid coverage as a renderable image.
 
Field Summary
protected  GridGeometry2D gridGeometry
          The grid geometry.
protected  PlanarImage image
          The raster data.
 
Fields inherited from class AbstractGridCoverage
LOGGER
 
Fields inherited from class AbstractCoverage
crs
 
Fields inherited from class PropertySourceImpl
cachedPropertyNames, properties, propertySources
 
Constructor Summary
protected GridCoverage2D(CharSequence name, GridCoverage2D coverage)
          Deprecated. Extends Calculator2D instead. This constructor will become package-privated in a future GeoTools version.
protected GridCoverage2D(CharSequence name, PlanarImage image, GridGeometry2D gridGeometry, GridSampleDimension[] bands, GridCoverage[] sources, Map<?,?> properties)
          Deprecated. Use the constructor with a Hints argument instead.
protected GridCoverage2D(CharSequence name, PlanarImage image, GridGeometry2D gridGeometry, GridSampleDimension[] bands, GridCoverage[] sources, Map<?,?> properties, Hints hints)
          Constructs a grid coverage with the specified grid geometry and sample dimensions.
 
Method Summary
 boolean dispose(boolean force)
          Provides a hint that a coverage will no longer be accessed from a reference in user space.
 Object evaluate(DirectPosition point)
          Returns the value vector 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.
 double[] evaluate(Point2D coord, double[] dest)
          Returns a sequence of double values for a given two-dimensional point in the coverage.
 float[] evaluate(Point2D coord, float[] dest)
          Returns a sequence of float values for a given two-dimensional point in the coverage.
 int[] evaluate(Point2D coord, int[] dest)
          Returns a sequence of integer values for a given two-dimensional point in the coverage.
 GridCoverage2D geophysics(boolean geo)
          Deprecated. Replaced by view(org.geotools.coverage.grid.ViewType).
 CoordinateReferenceSystem getCoordinateReferenceSystem2D()
          Returns the two-dimensional part of this grid coverage CRS.
 String getDebugString(DirectPosition coord)
          Returns a debug string for the specified coordinate.
 Envelope getEnvelope()
          Returns the bounding box for the coverage domain in coordinate reference system coordinates.
 Envelope2D getEnvelope2D()
          Returns the two-dimensional bounding box for the coverage domain in coordinate reference system coordinates.
 GridGeometry2D getGridGeometry()
          Returns information for the grid coverage geometry.
 Interpolation getInterpolation()
          Returns the interpolation used for all evaluate(...) methods.
 int getNumSampleDimensions()
          Returns the number of bands in the grid coverage.
 int[] getOptimalDataBlockSizes()
          Returns the optimal size to use for each dimension when accessing grid values.
 RenderableImage getRenderableImage(int xAxis, int yAxis)
          Returns 2D view of this grid coverage as a renderable image.
 RenderedImage getRenderedImage()
          Returns grid data as a rendered image.
 GridSampleDimension getSampleDimension(int index)
          Retrieve sample dimension information for the coverage.
 GridSampleDimension[] getSampleDimensions()
          Returns all sample dimensions for this grid coverage.
 Set<ViewType> getViewTypes()
          Returns the set of views that this coverage represents.
 boolean isDataEditable()
          Returns true if grid data can be edited.
 void prefetch(Rectangle2D area)
          Hints that the given area may be needed in the near future.
 void show(String title)
          {inheritDoc}
 void show(String title, int xAxis, int yAxis)
          {inheritDoc}
 String toString()
          Returns a string representation of this grid coverage.
 GridCoverage2D view(ViewType type)
          Returns a view of the specified type.
 
Methods inherited from class AbstractGridCoverage
formatEvaluateError, formatEvaluateError, getDataBlock, getDataBlock, getDataBlock, getDataBlock, getDataBlock, getDataBlock, getGridPacking, getNumOverviews, getOverview, getOverviewGridGeometry, getPackedDataBlock, getSources, pointOutsideCoverage, pointOutsideCoverage, setDataBlock, setDataBlock, setDataBlock, setDataBlock, setDataBlock, setDataBlock, setPackedDataBlock
 
Methods inherited from class AbstractCoverage
evaluate, evaluate, evaluateInverse, find, find, getCommonPointRule, getCoordinateReferenceSystem, getDimension, getDomainElements, getDomainExtents, getLocale, getName, getRangeElements, getRangeType, list, select, show
 
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
 
Methods inherited from interface GridCoverage
getDataBlock, getDataBlock, getDataBlock, getDataBlock, getDataBlock, getDataBlock, getGridPacking, getNumOverviews, getOverview, getOverviewGridGeometry, getPackedDataBlock, getSources, setDataBlock, setDataBlock, setDataBlock, setDataBlock, setDataBlock, setDataBlock
 
Methods inherited from interface Coverage
evaluate, evaluate, evaluateInverse, find, find, getCommonPointRule, getCoordinateReferenceSystem, getDomainElements, getDomainExtents, getRangeElements, getRangeType, list, select
 
Methods inherited from interface PropertySource
getProperty, getPropertyClass, getPropertyNames, getPropertyNames
 

Field Detail

image

protected final transient PlanarImage image
The raster data.


gridGeometry

protected final GridGeometry2D gridGeometry
The grid geometry.

Constructor Detail

GridCoverage2D

@Deprecated
protected GridCoverage2D(CharSequence name,
                                    GridCoverage2D coverage)
Deprecated. Extends Calculator2D instead. This constructor will become package-privated in a future GeoTools version.

Constructs a new grid coverage with the same parameter than the specified coverage. This constructor is useful when creating a coverage with identical data, but in which some method has been overridden in order to process data differently (e.g. interpolating them).

Parameters:
name - The name for this coverage, or null for the same than coverage.
coverage - The source grid coverage.

GridCoverage2D

@Deprecated
protected GridCoverage2D(CharSequence name,
                                    PlanarImage image,
                                    GridGeometry2D gridGeometry,
                                    GridSampleDimension[] bands,
                                    GridCoverage[] sources,
                                    Map<?,?> properties)
                  throws IllegalArgumentException
Deprecated. Use the constructor with a Hints argument instead.

Throws:
IllegalArgumentException
Since:
2.2

GridCoverage2D

protected GridCoverage2D(CharSequence name,
                         PlanarImage image,
                         GridGeometry2D gridGeometry,
                         GridSampleDimension[] bands,
                         GridCoverage[] sources,
                         Map<?,?> properties,
                         Hints hints)
                  throws IllegalArgumentException
Constructs a grid coverage with the specified grid geometry and sample dimensions. The envelope (including the coordinate reference system) is inferred from the grid geometry.

This constructor accepts an optional set of properties. Keys are String objects (CaselessStringKey are accepted as well), while values may be any Object.

Parameters:
name - The grid coverage name.
image - The image.
gridGeometry - The grid geometry (must contains an envelope with its coordinate reference system and a "grid to CRS" transform).
bands - Sample dimensions for each image band, or null for default sample dimensions. If non-null, then this array's length must matches the number of bands in image.
sources - The sources for this grid coverage, or null if none.
properties - The set of properties for this coverage, or null none.
hints - An optional set of hints, or null if none.
Throws:
IllegalArgumentException - If the number of bands differs from the number of sample dimensions.
Since:
2.5
Method Detail

isDataEditable

public boolean isDataEditable()
Returns true if grid data can be edited. The default implementation returns true if image is an instance of WritableRenderedImage.

Specified by:
isDataEditable in interface GridCoverage
Overrides:
isDataEditable in class AbstractGridCoverage

getGridGeometry

public GridGeometry2D getGridGeometry()
Returns information for the grid coverage geometry. Grid geometry includes the valid range of grid coordinates and the georeferencing.

Specified by:
getGridGeometry in interface GridCoverage

getEnvelope

public Envelope getEnvelope()
Returns the bounding box for the coverage domain in coordinate reference system coordinates. The returned envelope have at least two dimensions. It may have more dimensions if the coverage has some extent in other dimensions (for example a depth, or a start and end time).

Specified by:
getEnvelope in interface Coverage
Overrides:
getEnvelope in class AbstractCoverage
Returns:
The bounding box for the coverage domain in coordinate system coordinates.

getEnvelope2D

public Envelope2D getEnvelope2D()
Returns the two-dimensional bounding box for the coverage domain in coordinate reference system coordinates. If the coverage envelope has more than two dimensions, only the dimensions used in the underlying rendered image are returned.

Returns:
The two-dimensional bounding box.

getCoordinateReferenceSystem2D

public CoordinateReferenceSystem getCoordinateReferenceSystem2D()
Returns the two-dimensional part of this grid coverage CRS. If the complete CRS is two-dimensional, then this method returns the same CRS. Otherwise it returns a CRS for the two first axis having a length greater than 1 in the grid range. Note that those axis are garanteed to appears in the same order than in the complete CRS.

Returns:
The two-dimensional part of the grid coverage CRS.
See Also:
AbstractCoverage.getCoordinateReferenceSystem()

getNumSampleDimensions

public int getNumSampleDimensions()
Returns the number of bands in the grid coverage.

Specified by:
getNumSampleDimensions in interface Coverage

getSampleDimension

public GridSampleDimension 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. A coverage must have at least one sample dimension.

Specified by:
getSampleDimension in interface Coverage

getSampleDimensions

public GridSampleDimension[] getSampleDimensions()
Returns all sample dimensions for this grid coverage.

Returns:
All sample dimensions.

getInterpolation

public Interpolation getInterpolation()
Returns the interpolation used for all evaluate(...) methods. The default implementation returns InterpolationNearest.

Returns:
The interpolation.

evaluate

public Object evaluate(DirectPosition point)
                throws CannotEvaluateException
Returns the value vector for a given point in the coverage. A value for each sample dimension is included in the vector.

Specified by:
evaluate in interface Coverage
Throws:
CannotEvaluateException

evaluate

public byte[] evaluate(DirectPosition coord,
                       byte[] dest)
                throws 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.
Returns:
An array containing values.
Throws:
CannotEvaluateException - if the values can't be computed at the specified coordinate. More specifically, PointOutsideCoverageException is thrown if the evaluation failed because the input point has invalid coordinates.

evaluate

public int[] evaluate(DirectPosition coord,
                      int[] dest)
               throws 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.
Returns:
An array containing values.
Throws:
CannotEvaluateException - if the values can't be computed at the specified coordinate. More specifically, PointOutsideCoverageException is thrown if the evaluation failed because the input point has invalid coordinates.

evaluate

public float[] evaluate(DirectPosition coord,
                        float[] dest)
                 throws 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.
Returns:
An array containing values.
Throws:
CannotEvaluateException - if the values can't be computed at the specified coordinate. More specifically, PointOutsideCoverageException is thrown if the evaluation failed because the input point has invalid coordinates.

evaluate

public double[] evaluate(DirectPosition coord,
                         double[] dest)
                  throws 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.
Returns:
An array containing values.
Throws:
CannotEvaluateException - if the values can't be computed at the specified coordinate. More specifically, PointOutsideCoverageException is thrown if the evaluation failed because the input point has invalid coordinates.

evaluate

public int[] evaluate(Point2D coord,
                      int[] dest)
               throws CannotEvaluateException
Returns a sequence of integer values for a given two-dimensional point in the coverage.

Parameters:
coord - The coordinate point where to evaluate.
dest - An array in which to store values, or null.
Returns:
An array containing values.
Throws:
CannotEvaluateException - if the values can't be computed at the specified coordinate. More specifically, PointOutsideCoverageException is thrown if the evaluation failed because the input point has invalid coordinates.

evaluate

public float[] evaluate(Point2D coord,
                        float[] dest)
                 throws CannotEvaluateException
Returns a sequence of float values for a given two-dimensional point in the coverage.

Parameters:
coord - The coordinate point where to evaluate.
dest - An array in which to store values, or null.
Returns:
An array containing values.
Throws:
CannotEvaluateException - if the values can't be computed at the specified coordinate. More specifically, PointOutsideCoverageException is thrown if the evaluation failed because the input point has invalid coordinates.

evaluate

public double[] evaluate(Point2D coord,
                         double[] dest)
                  throws CannotEvaluateException
Returns a sequence of double values for a given two-dimensional point in the coverage.

Parameters:
coord - The coordinate point where to evaluate.
dest - An array in which to store values, or null.
Returns:
An array containing values.
Throws:
CannotEvaluateException - if the values can't be computed at the specified coordinate. More specifically, PointOutsideCoverageException is thrown if the evaluation failed because the input point has invalid coordinates.

getDebugString

public String getDebugString(DirectPosition coord)
Returns a debug string for the specified coordinate. This method produces a string with pixel coordinates and pixel values for all bands (with geophysics values or category name in parenthesis). Example for a 1-banded image:
(1171,1566)=[196 (29.6 °C)]

Parameters:
coord - The coordinate point where to evaluate.
Returns:
A string with pixel coordinates and pixel values at the specified location, or null if coord is outside coverage.

getOptimalDataBlockSizes

public int[] getOptimalDataBlockSizes()
Returns the optimal size to use for each dimension when accessing grid values. The default implementation returns the image's tiles size.

Specified by:
getOptimalDataBlockSizes in interface GridCoverage

getRenderedImage

public RenderedImage getRenderedImage()
Returns grid data as a rendered image.

Specified by:
getRenderedImage in interface RenderedCoverage
Returns:
The grid data as a rendered image.

getRenderableImage

public RenderableImage getRenderableImage(int xAxis,
                                          int yAxis)
Returns 2D view of this grid coverage as a renderable image. This method allows interoperability with Java2D.

Specified by:
getRenderableImage in interface Coverage
Overrides:
getRenderableImage in class AbstractCoverage
Parameters:
xAxis - Dimension to use for x axis.
yAxis - Dimension to use for y axis.
Returns:
A 2D view of this grid coverage as a renderable image.

show

public void show(String title,
                 int xAxis,
                 int yAxis)
{inheritDoc}

Overrides:
show in class AbstractCoverage
Parameters:
title - The window title, or null for default value.
xAxis - Dimension to use for the x display axis.
yAxis - Dimension to use for the y display axis.

show

public void show(String title)
{inheritDoc}

Overrides:
show in class AbstractCoverage
Parameters:
title - The window title, or null for default value.

prefetch

public void prefetch(Rectangle2D area)
Hints that the given area may be needed in the near future. Some implementations may spawn a thread or threads to compute the tiles while others may ignore the hint.

Parameters:
area - A rectangle indicating which geographic area to prefetch. This area's coordinates must be expressed according the grid coverage's coordinate reference system, as given by AbstractCoverage.getCoordinateReferenceSystem().

geophysics

@Deprecated
public GridCoverage2D geophysics(boolean geo)
Deprecated. Replaced by view(org.geotools.coverage.grid.ViewType).


view

public GridCoverage2D view(ViewType type)
Returns a view of the specified type. Valid types are: This method may be understood as applying the JAI's piecewise operation with breakpoints specified by the Category objects in each sample dimension. However, it is more general in that the transformation specified with each breakpoint doesn't need to be linear. On an implementation note, this method tries to use the first of the following operations which is found applicable: identity, lookup, rescale, piecewise and in last ressort a more general (but slower) sample transcoding algorithm.

Parameters:
type - The kind of view wanted.
Returns:
The grid coverage. Never null, but may be this.
Since:
2.5
See Also:
GridSampleDimension.geophysics(boolean), Category.geophysics(boolean), LookupDescriptor, RescaleDescriptor, PiecewiseDescriptor

getViewTypes

public Set<ViewType> getViewTypes()
Returns the set of views that this coverage represents. The same coverage may be used for more than one view. For example a coverage could be valid both as a PACKED and RENDERED view.

Returns:
The set of views that this coverage represents.
Since:
2.5

dispose

public boolean dispose(boolean force)
Provides a hint that a coverage will no longer be accessed from a reference in user space. This method disposes the image only if at least one of the following conditions is true (otherwise this method do nothing):

This safety check helps to prevent the disposal of an image that still used in a JAI operation chain. It doesn't prevent the disposal in every cases however. When unsure about whatever a coverage is still in use or not, it is safer to not invoke this method and rely on the garbage collector instead.

Overrides:
dispose in class AbstractCoverage
Parameters:
force - true for forcing an inconditionnal disposal, or false for performing a conservative disposal. The recommanded value is false.
Returns:
true if this method disposed at least some resources, or false if this method vetoed against the disposal.
Since:
2.4
See Also:
PlanarImage.dispose()

toString

public String toString()
Returns a string representation of this grid coverage. This is mostly for debugging purpose and may change in any future version.

Overrides:
toString in class AbstractCoverage


Copyright © 1996-2009 Geotools. All Rights Reserved.