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 JAISerializableRenderedImage
class. While serialization (usually on server side) should work on J2SE 1.4 and above, deserialization (usually on client side) ofGridCoverage2D
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 Description protected class
GridCoverage2D.Renderable
A view of a grid coverage as a renderable image.
-
Field Summary
Fields Modifier and Type Field 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
-
-
Constructor Summary
Constructors Modifier Constructor Description 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.GridCoverage2D(CharSequence name, GridCoverage2D coverage)
Constructs a new grid coverage with the same parameter than the specified coverage.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
dispose(boolean force)
Provides a hint that a coverage will no longer be accessed from a reference in user space.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).Object
evaluate(Position point)
Returns the value vector for a given location (world coordinates).byte[]
evaluate(Position coord, byte[] dest)
Returns a sequence of byte values for a given location (world coordinates).double[]
evaluate(Position coord, double[] dest)
Returns a sequence of double values for a given location (world coordinates).float[]
evaluate(Position coord, float[] dest)
Returns a sequence of float values for a given location (world coordinates).int[]
evaluate(Position 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.CoordinateReferenceSystem
getCoordinateReferenceSystem2D()
Returns the two-dimensional part of this grid coverage CRS.String
getDebugString(Position coord)
Returns a debug string for the specified coordinate.Bounds
getEnvelope()
Returns the bounding box for the coverage domain in coordinate reference system coordinates.ReferencedEnvelope
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 allevaluate(...)
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()
Returnstrue
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, ornull
for the same thancoverage
.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 anyObject
.- 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, ornull
for default sample dimensions. If non-null, then this array's length must matches the number of bands inimage
.sources
- The sources for this grid coverage, ornull
if none.properties
- The set of properties for this coverage, ornull
none.hints
- An optional set of hints, ornull
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()
Returnstrue
if grid data can be edited. The default implementation returnstrue
ifimage
is an instance ofWritableRenderedImage
.- Specified by:
isDataEditable
in interfaceGridCoverage
- Overrides:
isDataEditable
in classAbstractGridCoverage
- 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 Bounds 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 interfaceCoverage
- Overrides:
getEnvelope
in classAbstractCoverage
- Returns:
- The bounding box for the coverage domain in coordinate system coordinates.
-
getEnvelope2D
public ReferencedEnvelope 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 allevaluate(...)
methods. The default implementation returnsInterpolationNearest
.- Returns:
- The interpolation.
-
evaluate
public Object evaluate(Position 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(Position coord, byte[] dest) throws CannotEvaluateException
Returns a sequence of byte values for a given location (world coordinates).- Specified by:
evaluate
in interfaceCoverage
- Overrides:
evaluate
in classAbstractCoverage
- Parameters:
coord
- World coordinates of the location to evaluate.dest
- An array in which to store values, ornull
.- 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(Position coord, int[] dest) throws CannotEvaluateException
Returns a sequence of integer values for a given location (world coordinates).- Specified by:
evaluate
in interfaceCoverage
- Overrides:
evaluate
in classAbstractCoverage
- Parameters:
coord
- World coordinates of the location to evaluate.dest
- An array in which to store values, ornull
.- 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(Position coord, float[] dest) throws CannotEvaluateException
Returns a sequence of float values for a given location (world coordinates).- Specified by:
evaluate
in interfaceCoverage
- Overrides:
evaluate
in classAbstractCoverage
- Parameters:
coord
- World coordinates of the location to evaluate.dest
- An array in which to store values, ornull
.- 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(Position coord, double[] dest) throws CannotEvaluateException
Returns a sequence of double values for a given location (world coordinates).- Specified by:
evaluate
in interfaceCoverage
- Overrides:
evaluate
in classAbstractCoverage
- Parameters:
coord
- World coordinates of the location to evaluate.dest
- An array in which to store values, ornull
.- 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, ornull
.- 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, ornull
.- 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, ornull
.- 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) coordinatesdest
- 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) coordinatesdest
- 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) coordinatesdest
- 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(Position 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
ifcoord
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 interfaceCoverage
- Overrides:
getRenderableImage
in classAbstractCoverage
- 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 classAbstractCoverage
- Parameters:
title
- The window title, ornull
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 classAbstractCoverage
- Parameters:
title
- The window title, ornull
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 byAbstractCoverage.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
istrue
, 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 classAbstractCoverage
- Parameters:
force
-true
for forcing an inconditionnal disposal, orfalse
for performing a conservative disposal. The recommanded value isfalse
.- Returns:
true
if this method disposed at least some resources, orfalse
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 classAbstractCoverage
-
-