- Direct Known Subclasses:
BufferedGridCoverage
,GridCoverage2D
- Since:
- 1.0
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic interface
Interpolates values of sample dimensions at given positions. -
Field Summary
Modifier and TypeFieldDescriptionprotected final GridGeometry
The grid extent, coordinate reference system (CRS) and conversion from cell indices to CRS. -
Constructor Summary
ModifierConstructorDescriptionprotected
GridCoverage
(GridGeometry domain, List<? extends SampleDimension> ranges) Constructs a grid coverage using the specified grid geometry and sample dimensions. -
Method Summary
Modifier and TypeMethodDescriptionprotected GridCoverage
createConvertedValues
(boolean converted) Creates the grid coverage instance for the converted or packed values.Creates a new function for computing or interpolating sample values at given locations.forConvertedValues
(boolean converted) Returns a grid coverage that contains real values or sample values, depending ifconverted
istrue
orfalse
respectively.Returns the coordinate reference system to which the values in grid domain are referenced.Returns the bounding box for the coverage domain in CRS coordinates.Returns information about the domain of this grid coverage.Returns information about the range of this grid coverage.abstract RenderedImage
render
(GridExtent sliceExtent) Returns a two-dimensional slice of grid data as a rendered image.Returns a string representation of this grid coverage for debugging purpose.Returns a tree representation of some elements of this grid coverage.
-
Field Details
-
gridGeometry
The grid extent, coordinate reference system (CRS) and conversion from cell indices to CRS.- See Also:
-
-
Constructor Details
-
GridCoverage
Constructs a grid coverage using the specified grid geometry and sample dimensions. The grid geometry defines the "domain" (inputs) of the coverage function, and the sample dimensions define the "range" (output) of that function.- Parameters:
domain
- the grid extent, CRS and conversion from cell indices to CRS.ranges
- sample dimensions for each image band.- Throws:
NullPointerException
- if an argument isnull
or if the list contains a null element.IllegalArgumentException
- if therange
list is empty.
-
-
Method Details
-
getCoordinateReferenceSystem
Returns the coordinate reference system to which the values in grid domain are referenced. This is the target coordinate reference system of thegridToCRS
math transform.The default implementation delegates to
GridGeometry.getCoordinateReferenceSystem()
.- Specified by:
getCoordinateReferenceSystem
in classBandedCoverage
- Returns:
- the "real world" CRS of this coverage.
- Throws:
IncompleteGridGeometryException
- if the grid geometry has no CRS.
-
getEnvelope
Returns the bounding box for the coverage domain in CRS coordinates. The envelope encompasses all cell surfaces, from the left border of leftmost cell to the right border of the rightmost cell and similarly along other axes.The default implementation delegates to
GridGeometry.getEnvelope()
.- Specified by:
getEnvelope
in classBandedCoverage
- Returns:
- the bounding box for the coverage domain in CRS coordinates.
- Since:
- 1.2
-
getGridGeometry
Returns information about the domain of this grid coverage. Information includes the grid extent, CRS and conversion from cell indices to CRS.GridGeometry
can also provide derived information like bounding box and resolution.- Returns:
- grid extent, CRS and conversion from cell indices to CRS.
- See Also:
-
getSampleDimensions
Returns information about the range of this grid coverage. Information include names, sample value ranges, fill values and transfer functions for all bands in this grid coverage. The length of the returned list should be equal to the number of bands in the rendered image.- Specified by:
getSampleDimensions
in classBandedCoverage
- Returns:
- names, value ranges, fill values and transfer functions for all bands in this grid coverage.
- See Also:
-
forConvertedValues
Returns a grid coverage that contains real values or sample values, depending ifconverted
istrue
orfalse
respectively. If there is no transfer function defined by the sample dimensions, then this method returnsthis
. In all cases, the returned grid coverage r has the following properties:- The list returned by
r.getSampleDimensions()
is equal to the list returned bythis.getSampleDimensions()
with each element e replaced bye.forConvertedValues(converted)
. - The
RenderedImage
produced byr.render(extent)
is equivalent to the image returned bythis.render(extent)
with all sample values converted using the transfer function ifconverted
istrue
, or the inverse of transfer function ifconverted
isfalse
.
createConvertedValues(boolean)
when first needed, then caches the result for future invocations.- Parameters:
converted
-true
for a coverage containing converted values, orfalse
for a coverage containing packed values.- Returns:
- a coverage containing converted or packed values, depending on
converted
argument value. May bethis
but nevernull
. - Throws:
CannotEvaluateException
- if an error occurred while conversion the values.- See Also:
- The list returned by
-
createConvertedValues
Creates the grid coverage instance for the converted or packed values. This method is invoked byforConvertedValues(boolean)
when first needed. Then the result returned by this method is cached for future invocations offorConvertedValues(converted)
.Subclasses can override this method for customizing the converted coverages while leverage the caching done by
forConvertedValues(boolean)
.- Parameters:
converted
-true
for a coverage containing converted values, orfalse
for a coverage containing packed values.- Returns:
- a new coverage containing converted or packed values, depending on
converted
argument value. May bethis
but nevernull
. - Throws:
CannotEvaluateException
- if an error occurred while conversion the values.- Since:
- 1.3
-
evaluator
Creates a new function for computing or interpolating sample values at given locations. That function acceptsDirectPosition
in arbitrary Coordinate Reference System; conversions to grid indices are applied as needed.Multi-threading
Evaluator
s are not thread-safe. For computing sample values concurrently, a newEvaluator
instance should be created for each thread by invoking this method multiply times.- Specified by:
evaluator
in classBandedCoverage
- Returns:
- a new function for computing or interpolating sample values.
- Since:
- 1.1
-
render
Returns a two-dimensional slice of grid data as a rendered image. The givensliceExtent
argument specifies the coordinates of the slice in all dimensions that are not in the two-dimensional image. For example if this grid coverage has (x,y,z,t) dimensions and we want to render an image of data in the (x,y) dimensions, then the givensliceExtent
shall contain the (z,t) coordinates of the desired slice. Those coordinates are specified in a grid extent where low coordinate = high coordinate in the z and t dimensions. The two dimensions of the data to be shown (x and y in our example) shall be the only dimensions having a size greater than 1 cell.If the
sliceExtent
argument isnull
, then the default value isgetGridGeometry().getExtent()
. This means thatgridExtent
is optional for two-dimensional grid coverages or grid coverages where all dimensions except two have a size of 1 cell. If the grid extent contains more than 2 dimensions with a size greater than one cell, then aSubspaceNotSpecifiedException
is thrown.How to compute a slice extent from a slice point in "real world" coordinates
ThesliceExtent
is specified to this method as grid indices. If the z and t values are not grid indices but are relative to some Coordinate Reference System (CRS) instead, then the slice extent can be computed as below. First, a slice point containing the z and t coordinates should be constructed as aDirectPosition
in one of the following ways:- The
slicePoint
has a CRS with two dimensions less than this grid coverage CRS. - The
slicePoint
has the same CRS than this grid coverage, but the two coordinates to exclude are set toDouble.NaN
.
sliceExtent = getGridGeometry().derive().slice(slicePoint).getIntersection();
slicePoint
CRS is different than this grid coverage CRS (except for the number of dimensions), a coordinate transformation will be applied as needed.Characteristics of the returned image
Image dimensions x and y map to the first and second dimension respectively of the two-dimensionalsliceExtent
subspace. The coordinates given byRenderedImage.getMinX()
andgetMinY()
will be the image location relative to the location specified insliceExtent
low coordinates. For example, in the case of image minimum X coordinate:- A value of 0 means that the image left border is exactly where requested by
sliceExtent.getLow(xDimension)
. - A positive value means that the returned image is shifted to the right compared to specified extent. This implies that the image has less data than requested on left side. It may happen if the specified extent is partially outside grid coverage extent.
- A negative value means that the returned image is shifted to the left compared to specified extent.
This implies that the image has more data than requested on left side. It may happen if the image is tiled,
the specified
sliceExtent
covers many tiles, and expanding the specified extent is necessary for returning an integer amount of tiles.
sliceExtent
sizes if this method can honor exactly the request, or otherwise may be adjusted for the same reasons than x and y location discussed above.Implementations should return a view as much as possible, without copying sample values.
GridCoverage
subclasses can use theImageRenderer
class as a helper tool for that purpose. This method does not mandate any behavior regarding tiling (size of tiles, their numbering system, etc.). Some implementations may defer data loading until a tile is requested.- Parameters:
sliceExtent
- a subspace of this grid coverage where all dimensions except two have a size of 1 cell. May benull
if this grid coverage has only two dimensions with a size greater than 1 cell.- Returns:
- the grid slice as a rendered image. Image location is relative to
sliceExtent
. - Throws:
MismatchedDimensionException
- if the given extent does not have the same number of dimensions than this coverage.SubspaceNotSpecifiedException
- if the given argument is not sufficient for reducing the grid to a two-dimensional slice.DisjointExtentException
- if the given extent does not intersect this grid coverage.CannotEvaluateException
- if this method cannot produce the rendered image for another reason.
- The
-
toString
Returns a string representation of this grid coverage for debugging purpose. The returned string is implementation dependent and may change in any future version. Current implementation is equivalent to the following, where<default flags>
is the same set of flags thanGridGeometry.toString()
.return toTree(Locale.getDefault(), <default flags>).toString();
-
toTree
Returns a tree representation of some elements of this grid coverage. The tree representation is for debugging purpose only and may change in any future SIS version.- Parameters:
locale
- the locale to use for textual labels.bitmask
- combination ofGridGeometry
flags.- Returns:
- a tree representation of the specified elements.
- See Also:
-