org.geotools.coverage.grid

Class GridCoverage2D

Object

PropertySourceImpl

AbstractCoverage

AbstractGridCoverage

GridCoverage2D

All Implemented Interfaces:

Serializable, PropertySource, Coverage, GridCoverage

Direct Known Subclasses:

Interpolator2D

public class GridCoverage2D
extends AbstractGridCoverage

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	GridCoverage2D.Renderable A view of a grid coverage as a renderable image.

Field Summary

Fields

Modifier and Type	Field and Description
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

Constructors

Modifier	Constructor and Description
	GridCoverage2D(CharSequence name, GridCoverage2D coverage) Constructs 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, Hints hints) Constructs a grid coverage with the specified grid geometry and sample dimensions.

Method Summary

Modifier and Type	Method and Description
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 location (world coordinates).
byte[]	evaluate(DirectPosition coord, byte[] dest) Returns a sequence of byte values for a given location (world coordinates).
double[]	evaluate(DirectPosition coord, double[] dest) Returns a sequence of double values for a given location (world coordinates).
float[]	evaluate(DirectPosition coord, float[] dest) Returns a sequence of float values for a given location (world coordinates).
int[]	evaluate(DirectPosition coord, int[] dest) Returns a sequence of integer values for a given location (world coordinates).
double[]	evaluate(GridCoordinates2D coord, double[] dest) Return sample dimension (band) values as an array of doubles for the given grid location.
float[]	evaluate(GridCoordinates2D coord, float[] dest) Return sample dimension (band) values as an array of floats for the given grid location.
int[]	evaluate(GridCoordinates2D coord, int[] dest) Return sample dimension (band) values as an array of integers for the given grid location.
double[]	evaluate(Point2D coord, double[] dest) Returns a sequence of double values for a given location (world coordinates).
float[]	evaluate(Point2D coord, float[] dest) Returns a sequence of float values for a given location (world coordinates).
int[]	evaluate(Point2D coord, int[] dest) Returns a sequence of integer values for a given location (world coordinates).
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.
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.

Methods inherited from class AbstractGridCoverage

formatEvaluateError, formatEvaluateError, getNumOverviews, getOverview, getOverviewGridGeometry, getSources

Methods inherited from class AbstractCoverage

evaluate, evaluate, getCoordinateReferenceSystem, getDimension, getLocale, getName, getRangeType, 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 Coverage

evaluate, evaluate, getCoordinateReferenceSystem, getRangeType

Field Detail

image

protected final transient PlanarImage image

The raster data.

gridGeometry

protected final GridGeometry2D gridGeometry

The grid geometry.

Constructor Detail

GridCoverage2D

public GridCoverage2D(CharSequence name,
                      GridCoverage2D coverage)

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

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

Returns:

true if grid data can be edited.

getGridGeometry

public GridGeometry2D getGridGeometry()

Returns information for the grid coverage geometry. Grid geometry includes the valid range of grid coordinates and the georeferencing.

Returns:

The information for the grid coverage geometry.

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.

Returns:

The number of sample dimensions in the 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.

Parameters:

index - Index for sample dimension to retrieve. Indices are numbered 0 to (n-1).

Returns:

Sample dimension information for the 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 location (world coordinates). A value for each sample dimension is included in the vector.

Parameters:

point - Point at which to find the grid values.

Returns:

The value vector for a given point in the coverage.

Throws:

PointOutsideCoverageException - if the point is outside the coverage envelope.

CannotEvaluateException - If the point can't be evaluated for some other reason.

See Also:

Raster.getDataElements(int, int, Object)

evaluate

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

Returns a sequence of byte values for a given location (world coordinates).

Specified by:

evaluate in interface Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - World coordinates of the location 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 location (world coordinates).

Specified by:

evaluate in interface Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - World coordinates of the location 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.

See Also:

Raster.getPixel(int, int, int[])

evaluate

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

Returns a sequence of float values for a given location (world coordinates).

Specified by:

evaluate in interface Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - World coordinates of the location 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.

See Also:

Raster.getPixel(int, int, float[])

evaluate

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

Returns a sequence of double values for a given location (world coordinates).

Specified by:

evaluate in interface Coverage

Overrides:

evaluate in class AbstractCoverage

Parameters:

coord - World coordinates of the location 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.

See Also:

Raster.getPixel(int, int, double[])

evaluate

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

Returns a sequence of integer values for a given location (world coordinates).

Parameters:

coord - World coordinates of the location 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 location (world coordinates).

Parameters:

coord - World coordinates of the location 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 location (world coordinates).

Parameters:

coord - World coordinates of the location 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(GridCoordinates2D coord,
                      int[] dest)

Return sample dimension (band) values as an array of integers for the given grid location. The range of valid grid coordinates can be retrieved as in this example:

 GridEnvelope2D gridBounds = coverage.getGridGeometry2D().getGridRange();
 

Parameters:

coord - grid (ie. pixel) coordinates

dest - an optionally pre-allocated array; if non-null, its length should be equal to the number of bands (sample dimensions)

Returns:

band values for the given grid (pixel) location

Throws:

PointOutsideCoverageException - if the supplied coords are outside the grid bounds

evaluate

public float[] evaluate(GridCoordinates2D coord,
                        float[] dest)

Return sample dimension (band) values as an array of floats for the given grid location. The range of valid grid coordinates can be retrieved as in this example:

 GridEnvelope2D gridBounds = coverage.getGridGeometry2D().getGridRange();
 

Parameters:

coord - grid (ie. pixel) coordinates

dest - an optionally pre-allocated array; if non-null, its length should be equal to the number of bands (sample dimensions)

Returns:

band values for the given grid (pixel) location

Throws:

PointOutsideCoverageException - if the supplied coords are outside the grid bounds

evaluate

public double[] evaluate(GridCoordinates2D coord,
                         double[] dest)

Return sample dimension (band) values as an array of doubles for the given grid location. The range of valid grid coordinates can be retrieved as in this example:

 GridEnvelope2D gridBounds = coverage.getGridGeometry2D().getGridRange();
 

Parameters:

coord - grid (ie. pixel) coordinates

dest - an optionally pre-allocated array; if non-null, its length should be equal to the number of bands (sample dimensions)

Returns:

band values for the given grid (pixel) location

Throws:

PointOutsideCoverageException - if the supplied coords are outside the grid bounds

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.

Returns:

The optimal size to use for each dimension when accessing grid values, or null if none.

getRenderedImage

public RenderedImage getRenderedImage()

Returns grid data as a rendered image.

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

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.

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