org.geotoolkit.coverage.grid
Class GridCoverage2D

Object
  PropertySourceImpl
      AbstractCoverage
          AbstractGridCoverage
              GridCoverage2D

All Implemented Interfaces:

Serializable, PropertySource, Localized, 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.

Two-dimensional slice in a n-dimensional space
Grid coverages are usually two-dimensional. However, their envelope may have more than two dimensions.

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 envelope for all extra-dimension must have a span 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
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.

Since:

1.2

Version:

3.00

Author:

Martin Desruisseaux (IRD)

See Also:

GridGeometry2D, GridSampleDimension, GridCoverageBuilder, Serialized Form

Module:

coverage/geotk-coverage (download)

View source code for this class

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

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.
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) Display this coverage in a windows.
void	show(String title, int xAxis, int yAxis) Display this coverage in a windows.
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, setDataBlock, setDataBlock, setDataBlock, setDataBlock, setDataBlock, setDataBlock

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

public 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 map of user properties. This map is useful for storing user-values like statistics. Keys shall be String or CaselessStringKey instances, while values can be any Object. The property values can be fetched by the methods defined in the PropertySource interface.

Note that GridCoverageBuilder provides more convenient ways to create GridCoverage2D instances. But all those convenience methods will ultimately delegate to this constructor.

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 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 span greater than 1 in the grid envelope. Note that those axis are guaranteed 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

@Debug
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 inter-operability 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)

Display this coverage in a windows. This convenience method is used for debugging purpose. The exact appareance of the windows and the tools provided may changes in future versions.

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)

Display this coverage in a windows. This convenience method is used for debugging purpose. The exact appareance of the windows and the tools provided may changes in future versions.

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

view

public GridCoverage2D view(ViewType type)

Returns a view of the specified type. Valid types are:

• GEOPHYSICS: all sample values are equals to geophysics ("real world") values without the need for any transformation. The sample to geophysics transform is identity for all sample dimensions. "No data" values (if any) are expressed as NaN numbers. This view is suitable for computation, but usually not for rendering.

• PACKED: sample values are typically integers. A sample to geophysics transform may exists for converting them to "real world" values.

• RENDERED: synonymous of PACKED for now. Will be improved in a future version.

• PHOTOGRAPHIC: synonymous of RENDERED for now. Will be improved in a future version.

• SAME: returns this coverage unchanged.

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

• 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 recommended 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