Class GridCoverageBuilder
GridCoverage
instances.
A grid coverage is a function described by three parts:
- A domain, which describes the input values (e.g. geographic coordinates).
- One or more ranges, which describe the output values that the coverage can produce.
- The actual values, distributed on a regular grid.
setDomain(…)
, setRanges(…)
or setValues(…)
method.
Those methods are overloaded with many variants accepting different kind of arguments. For example, values can
be specified as a RenderedImage
, a Raster
or some other types.
GridCoverage
from a matrix of values is to set the values in a
WritableRaster
and to specify the domain as an Envelope
:
Limitations
Current implementation creates only two-dimensional coverages. A future version may extend this builder API for creating n-dimensional coverages.- Since:
- 1.1
- Version:
- 1.2
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate DataBuffer
The data buffer containing the coverage values.private GridGeometry
The domain (input) of the coverage function, ornull
if unspecified.private long
Set of grid axes to reverse, as a bit mask.private RenderedImage
The raster containing the coverage values.The properties to give to the image, ornull
if none.private List<SampleDimension>
The range (output) of the coverage function, ornull
if unspecified.private Raster
The raster containing the coverage values.private Dimension
The image size, ornull
if unspecified.private int
The band to be made visible (usually 0). -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionaddImageProperty
(String key, Object value) Adds a value associated to an image property.addRange
(SampleDimension band) Adds a sample dimension for one band.build()
Creates the grid coverage from the domain, ranges and values given to setter methods.private GridGeometry
Returns the domain with axis flips applied.flipGridAxis
(int dimension) Reverses axis direction in the specified grid dimension.private static String
missingProperty
(String name) Returns an error message for the exception to thrown when a mandatory property is missing.setDomain
(GridGeometry grid) Sets the domain envelope (including its CRS) and/or the transform from grid indices to domain coordinates.setDomain
(org.opengis.geometry.Envelope domain) Sets the domain as an enclosing envelope (including its CRS).setRanges
(Collection<? extends SampleDimension> bands) Sets the sample dimensions for all bands.setRanges
(SampleDimension... bands) Sets the sample dimensions for all bands.setValues
(DataBuffer data, Dimension size) Sets a two-dimensional slice of sample values as a Java2D data buffer.Sets a two-dimensional slice of sample values as a raster.setValues
(RenderedImage data) Sets a two-dimensional slice of sample values as a rendered image.private static void
verifyGridExtent
(GridExtent extent, int... expectedSize) Verifies that the grid extent has the expected size.
-
Field Details
-
domain
The domain (input) of the coverage function, ornull
if unspecified. Ifnull
, an identify "grid to CRS" transform will be assumed.- See Also:
-
ranges
The range (output) of the coverage function, ornull
if unspecified. If non-null, then the size of this list must be equal to the number of bands. -
visibleBand
private int visibleBand -
image
The raster containing the coverage values. Exactly one ofimage
,raster
andbuffer
shall be non-null.- See Also:
-
raster
The raster containing the coverage values. May be aWritableRaster
, in which case aBufferedImage
may be created. Exactly one ofimage
,raster
andbuffer
shall be non-null.- See Also:
-
buffer
The data buffer containing the coverage values. Exactly one ofimage
,raster
andbuffer
shall be non-null.- See Also:
-
size
The image size, ornull
if unspecified. It needs to be specified only if values were specified as a buffer without information about the grid size.- See Also:
-
flippedAxes
private long flippedAxesSet of grid axes to reverse, as a bit mask. For any dimension i, the bit at1L << i
is set to 1 if the grid axis at that dimension should be flipped.- See Also:
-
properties
The properties to give to the image, ornull
if none.- See Also:
-
-
Constructor Details
-
GridCoverageBuilder
public GridCoverageBuilder()Creates an initially empty builder.
-
-
Method Details
-
setDomain
Sets the domain envelope (including its CRS) and/or the transform from grid indices to domain coordinates. The givenGridGeometry
does not need to contain aGridExtent
because that extent will be computed automatically if needed. However if an extent is present, then it must be consistent with the size of data given tosetValues(…)
method (will be verified atbuild()
time).- Parameters:
grid
- the new grid geometry, ornull
for removing previous domain setting.- Returns:
this
for method invocation chaining.
-
setDomain
Sets the domain as an enclosing envelope (including its CRS). The given envelope should contain all pixel area. For example, the envelope lower corner should locate the lower-left (or upper-left, depending on y axis orientation) pixel corner, not pixel center. If the given envelope contains a CRS, then that CRS will be the coverage CRS. A transform from grid indices to domain coordinates will be created automatically. That transform will map grid dimensions to envelope dimensions in the same order (i.e. the matrix representation of the affine transform will be diagonal, ignoring the translation column).Axis directions
By default grid indices increase in the same direction than domain coordinates. When applied to images with pixels located by (column, row) indices, it means that by default row indices in the image are increasing toward up if the y coordinates in the coverage domain (e.g. latitude values) are also increasing toward up. It often results in images flipped vertically, because popular image formats such as PNG use row indices increasing in the opposite direction (toward down). This effect can be compensated by invokingflipGridAxis(1)
.Design note:GridCoverageBuilder
does not flip the y axis by default because not all file formats have row indices increasing toward down. A counter-example is the netCDF format. Even if we consider that the majority of images have y axis flipped, things become less obvious when considering data in more than two dimensions. Having the same default policy (no flipping) for all dimensions make problem analysis easier.GridCoverageBuilder
provides method only for flipping axes. If more sophisticated operations is desired (for example a rotation), thensetDomain(GridGeometry)
should be used instead of this method.Default implementation
The default implementation creates a newGridGeometry
from the given envelope then invokessetDomain(GridGeometry)
. Subclasses can override that later method as a single overriding point for all domain settings.- Parameters:
domain
- envelope of the coverage domain together with its CRS, ornull
for removing previous domain setting.- Returns:
this
for method invocation chaining.- See Also:
-
setRanges
Sets the sample dimensions for all bands. The list size must be equal to the number of bands in the data specified tosetValues(…)
method (it will be verified atbuild()
time).- Parameters:
bands
- the new sample dimensions, ornull
for removing previous range setting.- Returns:
this
for method invocation chaining.- Throws:
IllegalArgumentException
- if the given list is empty.- See Also:
-
setRanges
Sets the sample dimensions for all bands. The array length must be equal to the number of bands in the data specified tosetValues(…)
method (it will be verified atbuild()
time).- Parameters:
bands
- the new sample dimensions, ornull
for removing previous range setting.- Returns:
this
for method invocation chaining.- Throws:
IllegalArgumentException
- if the given array is empty.- See Also:
-
addRange
Adds a sample dimension for one band. This method can be invoked repeatedly until the number of sample dimensions is equal to the number of bands in the data specified tosetValues(…)
.- Parameters:
band
- the sample dimension to add.- Returns:
this
for method invocation chaining.- See Also:
-
setValues
Sets a two-dimensional slice of sample values as a rendered image. If sample dimensions are specified, then the number of bands must be equal to the number of sample dimensions.Note: row indices in an image are usually increasing down, while geographic coordinates are usually increasing up. Consequently, the
flipGridAxis(1)
method may need to be invoked after this method.- Parameters:
data
- the rendered image to be wrapped in aGridCoverage
. Cannot benull
.- Returns:
this
for method invocation chaining.- See Also:
-
setValues
Sets a two-dimensional slice of sample values as a raster. If sample dimensions are specified, then the number of bands must be equal to the number of sample dimensions.Note: row indices in a raster are usually increasing down, while geographic coordinates are usually increasing up. Consequently, the
flipGridAxis(1)
method may need to be invoked after this method.- Parameters:
data
- the raster to be wrapped in aGridCoverage
. Cannot benull
.- Returns:
this
for method invocation chaining.- See Also:
-
setValues
Sets a two-dimensional slice of sample values as a Java2D data buffer. The number of banks will be the number of bands in the image. If sample dimensions are specified, then the number of bands must be equal to the number of sample dimensions.- Parameters:
data
- the data buffer to be wrapped in aGridCoverage
. Cannot benull
.size
- the image size in pixels, ornull
if unspecified. If null, then the image size will be taken from the grid extent.- Returns:
this
for method invocation chaining.- Throws:
IllegalArgumentException
- ifwidth
orheight
is negative or equals to zero.
-
flipGridAxis
Reverses axis direction in the specified grid dimension. For example if grid indices are (column, row), thenflipGridAxis(1)
will reverse the direction of rows axis. Invoking this method a second time for the same dimension will cancel the flipping.When building coverage with a domain specified by an envelope (i.e. with no explicit grid to CRS transform), the default
GridCoverageBuilder
behavior is to create aGridGeometry
with grid indices increasing in the same direction than domain coordinates. This method allows to reverse direction for an axis. The most typical usage is to reverse the direction of the y axis in images.- Parameters:
dimension
- index of the dimension in the grid to reverse direction.- Returns:
this
for method invocation chaining.- See Also:
-
addImageProperty
Adds a value associated to an image property. This method can be invoked only once for eachkey
. Those properties will be given to theRenderedImage
created by thebuild()
method.- Parameters:
key
- key of the property to set.value
- value to associate to the given key.- Returns:
this
for method invocation chaining.- Throws:
IllegalArgumentException
- if a value is already associated to the given key.- Since:
- 1.1
-
build
Creates the grid coverage from the domain, ranges and values given to setter methods. The returned coverage is often aGridCoverage2D
instance, but not necessarily.- Returns:
- grid coverage created from specified domain, ranges and sample values.
- Throws:
IllegalStateException
- if some properties are inconsistent, for example grid extent not matching image size or number of sample dimensions not matching the number of bands. This exception often wraps anIllegalGridGeometryException
,IllegalArgumentException
orNullArgumentException
.
-
domainWithAxisFlips
private GridGeometry domainWithAxisFlips(GridGeometry grid) throws org.opengis.referencing.operation.TransformException Returns the domain with axis flips applied. If there is no axis to flip,domain
is returned unchanged (without completion for missing extent; we leave that toGridCoverage2D
constructor).- Throws:
org.opengis.referencing.operation.TransformException
- See Also:
-
verifyGridExtent
Verifies that the grid extent has the expected size. This method does not verify grid location (low coordinates) because it is okay to have it anywhere. TheexpectedSize
array can be shorter than the number of dimensions (i.e. it may be a slice in a data cube); this method usesGridExtent.getSubspaceDimensions(int)
for determining which dimensions to check.This verification can be useful because
DataBuffer
does not contain any information about image size, soBufferedGridCoverage.render(GridExtent)
will rely on the size provided by the grid extent. If those information do not reflect accurately the image size, the image will not be rendered properly.- Parameters:
extent
- the extent to verify.expectedSize
- the expected image size.- Throws:
IllegalGridGeometryException
- if the extent does not have the expected size.
-
missingProperty
Returns an error message for the exception to thrown when a mandatory property is missing.- Parameters:
name
- name of the missing property.- Returns:
- message for the exception to throw.
-