Package org.apache.sis.coverage.grid
Class GridCoverage2D
java.lang.Object
org.apache.sis.coverage.BandedCoverage
org.apache.sis.coverage.grid.GridCoverage
org.apache.sis.coverage.grid.GridCoverage2D
Basic access to grid data values backed by a two-dimensional
RenderedImage
.
While images are two-dimensional, the coverage envelope may have more dimensions.
In other words the rendered image can be a two-dimensional slice in a n-dimensional space.
The only restriction is that the grid extent has a
size equals to 1 in all dimensions except two of them.
Example:
a remote sensing image may be valid only over some time range
(the temporal period of the satellite passing over observed area).
Envelopes for such grid coverage can have three dimensions:
the two usual ones (horizontal extent along x and y),
and a third dimension for start time and end time (temporal extent along t).
This "two-dimensional" grid coverage can have any number of columns along x axis
and any number of rows along y axis, but only one plan along t axis.
This single plan can have a lower bound (the start time) and an upper bound (the end time).
Image size and location
The image width and height must be equal to the grid extent size in the two dimensions of the slice. However, the image origin (minimal x and y values) does not need to be equal to the grid extent low values; a translation will be applied as needed.Image bands
Each band in an image is represented as aSampleDimension
.- Since:
- 1.1
- Version:
- 1.2
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate final class
Implementation of evaluator returned byBandedCoverage.evaluator()
.Nested classes/interfaces inherited from class org.apache.sis.coverage.grid.GridCoverage
GridCoverage.Evaluator, GridCoverage.Lazy
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) static final int
A constant for identifying code that relying on having 2 dimensions.private final RenderedImage
The sample values stored as aRenderedImage
.private final AtomicReference<GridGeometry>
The two-dimensional components of the coordinate reference system and "grid to CRS" transform.private final long
Offsets to apply for converting grid coverage coordinates to image pixel coordinates.private final long
Offsets to apply for converting grid coverage coordinates to image pixel coordinates.private final int
Indices of extent dimensions corresponding to image x and y coordinates.private final int
Indices of extent dimensions corresponding to image x and y coordinates.Fields inherited from class org.apache.sis.coverage.grid.GridCoverage
gridGeometry
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
GridCoverage2D
(GridCoverage2D source, List<SampleDimension> range, org.opengis.referencing.operation.MathTransform1D[] converters, boolean isConverted) Creates a new grid coverage for the conversion of specified source coverage.GridCoverage2D
(GridCoverage source, RenderedImage data) Constructs a grid coverage using the same domain and range than the given coverage, but different data.(package private)
GridCoverage2D
(GridCoverage source, GridGeometry domain, GridExtent extent, RenderedImage data) Creates a new grid coverage for the resampling of specified source coverage.GridCoverage2D
(GridGeometry domain, List<? extends SampleDimension> range, RenderedImage data) Constructs a grid coverage using the specified domain, range and data. -
Method Summary
Modifier and TypeMethodDescription(package private) static GridGeometry
addExtentIfAbsent
(GridGeometry domain, RenderedImage data) If the given domain does not have aGridExtent
, creates a new grid geometry with an extent computed from the given image.(package private) static GridGeometry
addExtentIfAbsent
(GridGeometry domain, Rectangle bounds) If the given domain does not have aGridExtent
, creates a new grid geometry with an extent computed from the given image bounds.(package private) void
appendDataLayout
(TreeTable.Node root, Vocabulary vocabulary, TableColumn<CharSequence> column) Appends a "data layout" branch (if it exists) to the tree representation of this coverage.protected GridCoverage
createConvertedValues
(boolean converted) Creates a grid coverage that contains real values or sample values, depending ifconverted
istrue
orfalse
respectively.private static GridExtent
createExtent
(int dimension, Rectangle bounds, org.opengis.referencing.crs.CoordinateReferenceSystem crs) Creates a grid extent with the low and high coordinates of the given image bounds.(package private) static List<? extends SampleDimension>
defaultIfAbsent
(List<? extends SampleDimension> range, RenderedImage data, int numBands) If the sample dimensions are null, creates default sample dimensions with default names.Creates a new function for computing or interpolating sample values at given locations.(package private) final DataType
Returns the constant identifying the primitive type used for storing sample values.Returns the two-dimensional part of this grid geometry.render
(GridExtent sliceExtent) Returns a grid data region as a rendered image.private static RenderedImage
Returns the wrapped image if the only difference is a translation, ordata
otherwise.private static void
verifyBandCount
(List<? extends SampleDimension> range, RenderedImage data) Verifies that the number of bands in the image is equal to the number of sample dimensions.private static void
verifyImageSize
(GridExtent extent, RenderedImage data, int[] imageAxes) Verifies that the domain is consistent with image size.Methods inherited from class org.apache.sis.coverage.grid.GridCoverage
convert, forConvertedValues, getCoordinateReferenceSystem, getEnvelope, getGridGeometry, getSampleDimensions, toString, toTree
-
Field Details
-
BIDIMENSIONAL
static final int BIDIMENSIONALA constant for identifying code that relying on having 2 dimensions. This is the minimal number of dimension required for this coverage.- See Also:
-
data
The sample values stored as aRenderedImage
. -
gridToImageX
private final long gridToImageXOffsets to apply for converting grid coverage coordinates to image pixel coordinates. This isRenderedImage.getMinX()
−GridExtent.getLow(xDimension)
for the x offset and a similar formula for the y offset. -
gridToImageY
private final long gridToImageYOffsets to apply for converting grid coverage coordinates to image pixel coordinates. This isRenderedImage.getMinX()
−GridExtent.getLow(xDimension)
for the x offset and a similar formula for the y offset. -
xDimension
private final int xDimensionIndices of extent dimensions corresponding to image x and y coordinates. Typical values are 0 forxDimension
and 1 foryDimension
, but different values are allowed. -
yDimension
private final int yDimensionIndices of extent dimensions corresponding to image x and y coordinates. Typical values are 0 forxDimension
and 1 foryDimension
, but different values are allowed. -
gridGeometry2D
The two-dimensional components of the coordinate reference system and "grid to CRS" transform. This is derived fromGridCoverage.gridGeometry
when first needed, retaining only the components at dimension indicesxDimension
andyDimension
. The sameAtomicReference
instance may be shared withGridCoverage.convertedView
andGridCoverage.packedView
.- See Also:
-
-
Constructor Details
-
GridCoverage2D
private GridCoverage2D(GridCoverage2D source, List<SampleDimension> range, org.opengis.referencing.operation.MathTransform1D[] converters, boolean isConverted) Creates a new grid coverage for the conversion of specified source coverage.- Parameters:
source
- the coverage containing source values.range
- the sample dimensions to assign to the converted grid coverage.converters
- conversion from source to converted coverage, one transform per band.isConverted
- whether this grid coverage is for converted or packed values.
-
GridCoverage2D
GridCoverage2D(GridCoverage source, GridGeometry domain, GridExtent extent, RenderedImage data) Creates a new grid coverage for the resampling of specified source coverage.- Parameters:
source
- the coverage containing source values.domain
- the grid extent, CRS and conversion from cell indices to CRS.extent
- thedomain.getExtent()
value.data
- the sample values as aRenderedImage
, with one band for each sample dimension.
-
GridCoverage2D
Constructs a grid coverage using the same domain and range than the given coverage, but different data. This constructor can be used when new data have been computed by an image processing operation, but each pixel of the result have the same coordinates and the same units of measurement than in the source coverage.- Parameters:
source
- the coverage from which to copy grid geometry and sample dimensions.data
- the sample values as aRenderedImage
, with one band for each sample dimension.- Throws:
IllegalGridGeometryException
- if the image size is not consistent with the grid geometry.IllegalArgumentException
- if the image number of bands is not the same than the number of sample dimensions.- Since:
- 1.2
-
GridCoverage2D
public GridCoverage2D(GridGeometry domain, List<? extends SampleDimension> range, RenderedImage data) Constructs a grid coverage using the specified domain, range and data. If the given domain does not have an extent, then a defaultGridExtent
will be computed from given image. Otherwise the image width and height must be equal to the grid extent size in the two dimensions of the slice.The image origin (minimal x and y values) can be anywhere; it does not need to be the same as the grid extent low values. Translations will be applied automatically when needed.
This constructor throws an
IllegalGridGeometryException
if one of the following errors is detected in thedomain
argument:- The given domain has less than two dimensions.
- The given domain has more than two dimensions having an extent size greater than 1.
- The extent size along x and y axes is not equal to the image width and height.
- Parameters:
domain
- the grid extent (may be absent), CRS and conversion from cell indices. Ifnull
a default grid geometry will be created with no CRS and identity conversion.range
- sample dimensions for each image band. The size of this list must be equal to the number of bands. Ifnull
, default sample dimensions will be created with no transfer function.data
- the sample values as aRenderedImage
, with one band for each sample dimension.- Throws:
IllegalGridGeometryException
- if thedomain
does not met the above-documented conditions.IllegalArgumentException
- if the image number of bands is not the same than the number of sample dimensions.ArithmeticException
- if the distance between grid location and image location exceeds thelong
capacity.- See Also:
-
-
Method Details
-
unwrapIfSameSize
Returns the wrapped image if the only difference is a translation, ordata
otherwise. -
addExtentIfAbsent
If the given domain does not have aGridExtent
, creates a new grid geometry with an extent computed from the given image. The new grid will start at the same location than the image and will have the same size.- Parameters:
domain
- the domain to complete. May benull
.data
- user supplied image, ornull
if missing.- Returns:
- the potentially completed domain (may be
null
).
-
addExtentIfAbsent
If the given domain does not have aGridExtent
, creates a new grid geometry with an extent computed from the given image bounds. The new grid will start at the same location than the image and will have the same size.This method does nothing if the given domain already has an extent; it does not verify that the extent is consistent with image size. This verification should be done by the caller.
- Parameters:
domain
- the domain to complete. May benull
.bounds
- image or raster bounds (cannot benull
).- Returns:
- the potentially completed domain (may be
null
).
-
createExtent
private static GridExtent createExtent(int dimension, Rectangle bounds, org.opengis.referencing.crs.CoordinateReferenceSystem crs) Creates a grid extent with the low and high coordinates of the given image bounds. The coordinate reference system is used for extracting grid axis names, in particular theDimensionNameType.VERTICAL
andDimensionNameType.TIME
dimensions. TheDimensionNameType.COLUMN
andDimensionNameType.ROW
dimensions can not be inferred from CRS analysis; they are added from knowledge that we have an image.- Parameters:
dimension
- number of dimensions.bounds
- bounds of the image for which to create a grid extent.crs
- coordinate reference system, ornull
if none.
-
verifyImageSize
Verifies that the domain is consistent with image size. We do not verify image location; it can be anywhere. -
defaultIfAbsent
static List<? extends SampleDimension> defaultIfAbsent(List<? extends SampleDimension> range, RenderedImage data, int numBands) If the sample dimensions are null, creates default sample dimensions with default names. The default names are "gray", "red, green, blue" or "cyan, magenta, yellow" if the color model is identified as such, or numbers if the color model is not recognized.- Parameters:
range
- the list of sample dimensions, potentially null.data
- the image for which to build sample dimensions, ornull
.numBands
- the number of bands in the given image, or 0 if none.- Returns:
- the given list of sample dimensions if it was non-null, or a default list otherwise.
-
verifyBandCount
Verifies that the number of bands in the image is equal to the number of sample dimensions. The number of bands is fetched from the sample model, which in theory shall never be null. However, this class has a little bit of tolerance to missing sample model. It may happen when the image is used only as a matrix storage. -
getBandType
Returns the constant identifying the primitive type used for storing sample values.- Overrides:
getBandType
in classGridCoverage
-
getGridGeometry2D
Returns the two-dimensional part of this grid geometry. If the complete geometry is already two-dimensional, then this method returns the same geometry. Otherwise it returns a geometry for the two first axes having a size greater than 1 in the grid envelope. Note that those axes are guaranteed to appear in the same order than in the complete geometry.- Returns:
- the two-dimensional part of the grid geometry.
- See Also:
-
createConvertedValues
Creates a grid coverage that contains real values or sample values, depending ifconverted
istrue
orfalse
respectively.- Overrides:
createConvertedValues
in classGridCoverage
- 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.
-
evaluator
Creates a new function for computing or interpolating sample values at given locations.Multi-threading
Evaluator
s are not thread-safe. For computing sample values concurrently, a newEvaluator
instance should be created for each thread.- Overrides:
evaluator
in classGridCoverage
- Returns:
- a new function for computing or interpolating sample values.
- Since:
- 1.1
-
render
Returns a grid data region as a rendered image. ThesliceExtent
argument specifies the area of interest and may benull
for requesting the whole image. The coordinates given byRenderedImage.getMinX()
andgetMinY()
will be the image location relative to the location specified insliceExtent
low coordinates (see super-class javadoc for more discussion). The image width and height will be thesliceExtent
sizes if this method can honor exactly the request, but this method is free to return a smaller or larger image if doing so reduce the amount of data to create or copy. This implementation returns a view as much as possible, without copying sample values.- Specified by:
render
in classGridCoverage
- Parameters:
sliceExtent
- area of interest, ornull
for the whole image.- Returns:
- the grid slice as a rendered image. Image location is relative to
sliceExtent
. - Throws:
org.opengis.geometry.MismatchedDimensionException
- if the given extent does not have the same number of dimensions than this coverage.DisjointExtentException
- if the given extent does not intersect this grid coverage.CannotEvaluateException
- if this method cannot produce the rendered image for another reason.- See Also:
-
appendDataLayout
@Debug void appendDataLayout(TreeTable.Node root, Vocabulary vocabulary, TableColumn<CharSequence> column) Appends a "data layout" branch (if it exists) to the tree representation of this coverage. That branch will be inserted between "coverage domain" and "sample dimensions" branches.- Overrides:
appendDataLayout
in classGridCoverage
- Parameters:
root
- root of the tree where to add a branch.vocabulary
- localized resources for vocabulary.column
- the single column where to write texts.
-