org.geotools.coverage.grid
Class GridCoverage2D

Object
  PropertySourceImpl
      AbstractCoverage
          AbstractGridCoverage
              GridCoverage2D

All Implemented Interfaces:

Serializable, PropertySource, RenderedCoverage, Coverage, GridCoverage

Direct Known Subclasses:

Interpolator2D

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

See Also:

Serialized Form

Module:

modules/library/coverage (gt2-coverage.jar) (Maven report) (SVN head)

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) Construct a new grid coverage with the same parameter than the specified coverage.
protected	GridCoverage2D(CharSequence name, PlanarImage image, GridGeometry2D gridGeometry, GridSampleDimension[] bands, GridCoverage[] sources, Map properties) Constructs a grid coverage with the specified grid geometry and sample dimensions.

Method Summary

protected GridCoverage2D	createGeophysics(boolean geo) Invoked by geophysics(boolean) when the packed or geophysics companion of this grid coverage need to be created.
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) If true, returns the geophysics companion of this grid coverage.
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.
GridGeometry	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.
SampleDimension	getSampleDimension(int index) Retrieve sample dimension information for the coverage.
GridSampleDimension[]	getSampleDimensions() Returns all sample dimensions for this grid coverage.
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}

Methods inherited from class AbstractGridCoverage

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

dispose, evaluate, evaluate, evaluateInverse, find, find, getCommonPointRule, getCoordinateReferenceSystem, getDimension, getDimensionNames, getDimensionNames, getDomainElements, getDomainExtents, getLocale, getMetadataNames, getMetadataValue, getName, getRangeElements, getRangeType, list, select, 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

Methods inherited from interface GridCoverage

getDataBlock, getDataBlock, getDataBlock, getDataBlock, getDataBlock, getDataBlock, getGridPacking, getNumOverviews, getOverview, getOverviewGridGeometry, getPackedDataBlock, setDataBlock, setDataBlock, setDataBlock, setDataBlock, setDataBlock, setDataBlock, setPackedDataBlock

Methods inherited from interface Coverage

evaluate, evaluate, evaluateInverse, find, find, getCommonPointRule, getCoordinateReferenceSystem, getDimensionNames, getDomainElements, getDomainExtents, getMetadataNames, getMetadataValue, getRangeElements, getRangeType, getSources, 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

protected GridCoverage2D(CharSequence name,
                         GridCoverage2D coverage)

Construct 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

protected GridCoverage2D(CharSequence name,
                         PlanarImage image,
                         GridGeometry2D gridGeometry,
                         GridSampleDimension[] bands,
                         GridCoverage[] sources,
                         Map properties)
                  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. "Properties" in Java Advanced Imaging is what OpenGIS calls "Metadata". 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.

Throws:

IllegalArgumentException - if the number of bands differs from the number of sample dimensions.

Since:

2.2

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 GridGeometry 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.

getCoordinateReferenceSystem2D

public CoordinateReferenceSystem getCoordinateReferenceSystem2D()

Returns the two-dimensional part of this grid coverage CRS. This is usually (but not always) identical to the full 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 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. 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.

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

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

public GridCoverage2D geophysics(boolean geo)

If true, returns the geophysics companion of this grid coverage. In a geophysics grid coverage, all sample values are equals to geophysics ("real world") values without the need for any transformation. In such geophysics coverage, the sample to geophysics transform is the identity transform for all sample dimensions. "No data" values are expressed by NaN numbers.

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 will really try 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.

GridCoverage objects live by pair: a geophysics one (used for computation) and a non-geophysics one (used for packing data, usually as integers). The geo argument specifies which object from the pair is wanted, regardless if this method is invoked on the geophysics or non-geophysics instance of the pair. In other words, the result of geophysics(b1).geophysics(b2).geophysics(b3) depends only on the value in the last call (b3).

Parameters:

geo - true to get a grid coverage with sample values equals to geophysics values, or false to get the packed version.

Returns:

The grid coverage. Never null, but may be this.

See Also:

GridSampleDimension.geophysics(boolean), Category.geophysics(boolean), LookupDescriptor, RescaleDescriptor, PiecewiseDescriptor

createGeophysics

protected GridCoverage2D createGeophysics(boolean geo)

Invoked by geophysics(boolean) when the packed or geophysics companion of this grid coverage need to be created. Subclasses may override this method in order to modify the object to be created.

Parameters:

geo - true to get a grid coverage with sample values equals to geophysics values, or false to get the packed version.

Returns:

The newly created grid coverage.

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):

• force is true, or
• The underlying image has no sinks other than the views (geophysics, display, etc.).

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()