Interface Coverage
- All Known Subinterfaces:
GridCoverage
,GridCoverageResponse
- All Known Implementing Classes:
AbstractCoverage
,AbstractGridCoverage
,DefaultGridCoverageResponse
,GridCoverage2D
,Interpolator2D
For example consider the following different internal representations of coverage:
- A coverage may be represented by a set of polygons which exhaustively tile a plane (that is each point on the plane falls in precisely one polygon). The value returned by the coverage for a point is the value of an attribute of the polygon that contains the point.
- A coverage may be represented by a grid of values (a Discrete Grid Point Coverage). If the coverage is a Continuous Quadrilateral Grid Coverage using Nearest Neighbour interpolation method, then the value returned by the coverage for a point is that of the grid value whose location is nearest the point.
- Coverage may be represented by a mathematical function. The value returned by the coverage for a point is just the return value of the function when supplied the coordinates of the point as arguments.
- Coverage may be represented by combination of these. For example, coverage may be represented by a combination of mathematical functions valid over a set of polynomials.
Metadata
The legacy OGC 01-004 specification provided some methods for fetching metadata values attached to a coverage. The ISO 19123 specification do not provides such methods. Implementations that want to provide such metadata are encouraged to implement thePropertySource
or WritablePropertySource
interface.- Since:
- GeoAPI 2.1
- Author:
- Stephane Fellah, Martin Desruisseaux (IRD), Wim Koolhoven, Alexander Petkov
-
Method Summary
Modifier and TypeMethodDescriptionReturn the value vector for a given point in the coverage.boolean[]
Return a sequence of boolean values for a given point in the coverage.byte[]
Return a sequence of unsigned byte values for a given point in the coverage.double[]
Return a sequence of double values for a given point in the coverage.float[]
Return a sequence of float values for a given point in the coverage.int[]
Return a sequence of integer values for a given point in the coverage.evaluate
(Position p, Collection<String> list) Returns a set of records of feature attribute values for the specified direct position.Returns the coordinate reference system to which the objects in its domain are referenced.The bounding box for the coverage domain in coordinate reference system coordinates.int
The number of sample dimensions in the coverage.Describes the range of the coverage.getRenderableImage
(int xAxis, int yAxis) Returns 2D view of this coverage as a renderable image.getSampleDimension
(int index) Retrieve sample dimension information for the coverage.Returns the sources data for a coverage.
-
Method Details
-
getCoordinateReferenceSystem
CoordinateReferenceSystem getCoordinateReferenceSystem()Returns the coordinate reference system to which the objects in its domain are referenced. This is the CRS used when accessing a coverage or grid coverage with theevaluate(...)
methods. This coordinate reference system is usually different than coordinate system of the grid. It is the target coordinate reference system of thegridToCRS
math transform.Grid coverage can be accessed (re-projected) with new coordinate reference system with the
GridCoverageProcessor
component. In this case, a new instance of a grid coverage is created.- Returns:
- The coordinate reference system used when accessing a coverage or grid coverage with the
evaluate(...)
methods.
-
getEnvelope
Bounds getEnvelope()The bounding box for the coverage domain in coordinate reference system coordinates. For grid coverages, the grid cells are centered on each grid coordinate. The envelope for a 2-D grid coverage includes the following corner positions.(Minimum row - 0.5, Minimum column - 0.5) for the minimum coordinates (Maximum row - 0.5, Maximum column - 0.5) for the maximum coordinates
- Returns:
- The bounding box for the coverage domain in coordinate system coordinates.
-
getRangeType
RecordType getRangeType()Describes the range of the coverage. It consists of a list of attribute name/data type pairs. A simple list is the most common form of range type, butRecordType
can be used recursively to describe more complex structures. The range type for a specific coverage shall be specified in an application schema.- Returns:
- The coverage range.
-
evaluate
Set<Record> evaluate(Position p, Collection<String> list) throws PointOutsideCoverageException, CannotEvaluateException Returns a set of records of feature attribute values for the specified direct position. The parameterlist
is a sequence of feature attribute names each of which identifies a field of the range type. Iflist
is null, the operation shall return a value for every field of the range type. Otherwise, it shall return a value for each field included inlist
. If the direct position passed is not in the domain of the coverage, then an exception is thrown. If the input direct position falls within two or more geometric objects within the domain, the operation shall return records of feature attribute values computed according to the common point rule.NOTE: Normally, the operation will return a single record of feature attribute values.
- Parameters:
p
- The position where to evaluate.list
- The field of interest, ornull
for every fields.- Returns:
- The feature attributes.
- Throws:
PointOutsideCoverageException
- if the point is outside the coverage domain.CannotEvaluateException
- If the point can't be evaluated for some other reason.
-
evaluate
Return the value vector for a given point in the coverage. A value for each sample dimension is included in the vector. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor.The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the
getCoordinateReferenceSystem()
method).WARNING: This method is inherited from the legacy OGC 01-004 specification and may be deprecated in a future version. We are for more experience and feedbacks on the value of this method.
- 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:
-
evaluate
boolean[] evaluate(Position point, boolean[] destination) throws PointOutsideCoverageException, CannotEvaluateException, ArrayIndexOutOfBoundsException Return a sequence of boolean values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor.The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the
getCoordinateReferenceSystem()
method).- Parameters:
point
- Point at which to find the coverage values.destination
- An optionally preallocated array in which to store the values, ornull
if none.- Returns:
- A sequence of boolean values for a given point in the coverage. If
destination
was non-null, then it is returned. Otherwise, a new array is allocated and returned. - Throws:
PointOutsideCoverageException
- if the point is outside the coverage envelope.CannotEvaluateException
- if the point can't be evaluated for some othe reason.ArrayIndexOutOfBoundsException
- if thedestination
array is not null and too small to hold the output.
-
evaluate
byte[] evaluate(Position point, byte[] destination) throws PointOutsideCoverageException, CannotEvaluateException, ArrayIndexOutOfBoundsException Return a sequence of unsigned byte values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor.The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the
getCoordinateReferenceSystem()
method).- Parameters:
point
- Point at which to find the coverage values.destination
- An optionally preallocated array in which to store the values, ornull
if none.- Returns:
- A sequence of unsigned byte values for a given point in the coverage. If
destination
was non-null, then it is returned. Otherwise, a new array is allocated and returned. - Throws:
PointOutsideCoverageException
- if the point is outside the coverage envelope.CannotEvaluateException
- if the point can't be evaluated for some othe reason.ArrayIndexOutOfBoundsException
- if thedestination
array is not null and too small to hold the output.
-
evaluate
int[] evaluate(Position point, int[] destination) throws PointOutsideCoverageException, CannotEvaluateException, ArrayIndexOutOfBoundsException Return a sequence of integer values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor.The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the
getCoordinateReferenceSystem()
method).- Parameters:
point
- Point at which to find the grid values.destination
- An optionally preallocated array in which to store the values, ornull
if none.- Returns:
- A sequence of integer values for a given point in the coverage. If
destination
was non-null, then it is returned. Otherwise, a new array is allocated and returned. - Throws:
PointOutsideCoverageException
- if the point is outside the coverage envelope.CannotEvaluateException
- if the point can't be evaluated for some othe reason.ArrayIndexOutOfBoundsException
- if thedestination
array is not null and too small to hold the output.- See Also:
-
evaluate
float[] evaluate(Position point, float[] destination) throws PointOutsideCoverageException, CannotEvaluateException, ArrayIndexOutOfBoundsException Return a sequence of float values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor.The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the
getCoordinateReferenceSystem()
method).- Parameters:
point
- Point at which to find the grid values.destination
- An optionally preallocated array in which to store the values, ornull
if none.- Returns:
- A sequence of float values for a given point in the coverage. If
destination
was non-null, then it is returned. Otherwise, a new array is allocated and returned. - Throws:
PointOutsideCoverageException
- if the point is outside the coverage envelope.CannotEvaluateException
- if the point can't be evaluated for some othe reason.ArrayIndexOutOfBoundsException
- if thedestination
array is not null and too small to hold the output.- See Also:
-
evaluate
double[] evaluate(Position point, double[] destination) throws PointOutsideCoverageException, CannotEvaluateException, ArrayIndexOutOfBoundsException Return a sequence of double values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor.The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the
getCoordinateReferenceSystem()
method).- Parameters:
point
- Point at which to find the grid values.destination
- An optionally preallocated array in which to store the values, ornull
if none.- Returns:
- A sequence of double values for a given point in the coverage. If
destination
was non-null, then it is returned. Otherwise, a new array is allocated and returned. - Throws:
PointOutsideCoverageException
- if the point is outside the coverage envelope.CannotEvaluateException
- If the point can't be evaluated for some othe reason.ArrayIndexOutOfBoundsException
- if thedestination
array is not null and too small to hold the output.- See Also:
-
getNumSampleDimensions
int getNumSampleDimensions()The number of sample dimensions in the coverage. For grid coverages, a sample dimension is a band.WARNING: This method is inherited from the legacy OGC 01-004 specification and may be deprecated in a future version. We are for more experience and feedbacks on the value of this method.
- Returns:
- The number of sample dimensions in the coverage.
-
getSampleDimension
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.WARNING: This method is inherited from the legacy OGC 01-004 specification and may be deprecated in a future version. We are for more experience and feedbacks on the value of this method.
- Parameters:
index
- Index for sample dimension to retrieve. Indices are numbered 0 to (n-1).- Returns:
- Sample dimension information for the coverage.
- Throws:
IndexOutOfBoundsException
- ifindex
is out of bounds.
-
getSources
Returns the sources data for a coverage. This is intended to allow applications to establish whatCoverage
s will be affected when others are updated, as well as to trace back to the "raw data".This implementation specification does not include interfaces for creating collections of coverages therefore the list size will usually be one indicating an adapted grid coverage, or zero indicating a raw grid coverage.
WARNING: This method is inherited from the legacy OGC 01-004 specification and may be deprecated in a future version. We are for more experience and feedbacks on the value of this method.
- Returns:
- The list of sources data for a coverage.
-
getRenderableImage
RenderableImage getRenderableImage(int xAxis, int yAxis) throws UnsupportedOperationException, IndexOutOfBoundsException Returns 2D view of this coverage as a renderable image. This optional operation allows interoperability with Java2D. If this coverage is aGridCoverage
backed by aRenderedImage
, the underlying image can be obtained with:getRenderableImage(0,1).createDefaultRendering()
- Parameters:
xAxis
- Dimension to use for the x axis.yAxis
- Dimension to use for the y axis.- Returns:
- A 2D view of this coverage as a renderable image.
- Throws:
UnsupportedOperationException
- if this optional operation is not supported.IndexOutOfBoundsException
- ifxAxis
oryAxis
is out of bounds.
-