Class GridDerivation
GridDerivation
are created by calls to GridGeometry.derive()
.
Properties of the desired grid geometry can be specified by calls to the following methods,
in that order (each method is optional):
rounding(GridRoundingMode)
,margin(int...)
and/orchunkSize(int...)
in any ordersubgrid(GridGeometry)
,subgrid(Envelope, double...)
orsubgrid(GridExtent, int...)
slice(DirectPosition)
and/orsliceByRatio(double, int...)
build()
.
The getIntersection()
method can also be invoked for the GridExtent
part without subsampling.
All methods in this class preserve the number of dimensions. For example the slice(DirectPosition)
method sets
the grid size to 1 in all dimensions specified by the slice point,
but does not remove those dimensions from the grid geometry.
For dimensionality reduction, see GridGeometry.reduce(int...)
.
 Since:
 1.0
 See Also:
Defined in the sisfeature
module

Field Summary
Modifier and TypeFieldDescriptionprotected final GridGeometry
The base grid geometry from which to derive a new grid geometry. 
Constructor Summary
ModifierConstructorDescriptionprotected
GridDerivation
(GridGeometry base) Creates a new builder for deriving a grid geometry from the specified base. 
Method Summary
Modifier and TypeMethodDescriptionbuild()
Builds a grid geometry with the configuration specified by the other methods in thisGridDerivation
class.chunkSize
(int... cellCounts) Specifies the size of tiles or chunks in the base grid geometry.clipping
(GridClippingMode mode) Specifies whether to clip the derived grid extent to the extent of the base grid geometry.double
Deprecated.To be removed for avoiding operations that mix potentially unrelated dimensions.Returns the extent of the modified grid geometry, ignoring subsampling or changes in resolution.int[]
Returns the strides for accessing cells along each axis of the base grid.int[]
Returns the offsets to be subtracted from pixel coordinates before subsampling.int[]
Deprecated.RenamedgetSubsampling()
(without "s" because "subsampling" is uncountable).margin
(int... cellCounts) Specifies an amount of cells by which to expandGridExtent
after rounding.maximumSubsampling
(int... subsampling) Specifies the maximum subsampling values (inclusive) for each dimension.resize
(GridExtent extent, double... scales) Deprecated.This method does not handle margin, chunk size and clipping according their contract.rounding
(GridRoundingMode mode) Controls behavior of rounding from floating point values to integers.slice
(DirectPosition slicePoint) Requests a grid geometry for a slice at the given "real world" position.sliceByRatio
(double sliceRatio, int... dimensionsToKeep) Requests a grid geometry for a slice at the given relative position.subgrid
(GridExtent areaOfInterest, int... subsampling) Requests a grid geometry over a subregion of the base grid geometry and optionally with subsampling.subgrid
(GridGeometry areaOfInterest) Adapts the base grid for the geographic area and resolution of the given grid geometry.Requests a grid geometry over a subenvelope and optionally with a different a coarser resolution.subsample
(int... subsampling) Deprecated.Replaced bysubgrid(GridExtent, int...)
with anull
extent.Returns a string representation of thisGridDerivation
for debugging purpose.

Field Details

base
The base grid geometry from which to derive a new grid geometry.


Constructor Details

GridDerivation
Creates a new builder for deriving a grid geometry from the specified base. Parameters:
base
 the base to use as a template for deriving a new grid geometry. See Also:


Method Details

rounding
Controls behavior of rounding from floating point values to integers. This setting modifies computations performed by the following methods (it has no effect on other methods in thisGridDerivation
class): If this method is never invoked, the default value isGridRoundingMode.NEAREST
. If this method is invoked too late, anIllegalStateException
is thrown. Parameters:
mode
 the new rounding mode. Returns:
this
for method call chaining. Throws:
IllegalStateException
 ifsubgrid(Envelope, double...)
orslice(DirectPosition)
has already been invoked.

clipping
Specifies whether to clip the derived grid extent to the extent of the base grid geometry. The default value isGridClippingMode.STRICT
. Parameters:
mode
 whether to clip the derived grid extent. Returns:
this
for method call chaining. Throws:
IllegalStateException
 ifsubgrid(Envelope, double...)
orslice(DirectPosition)
has already been invoked. Since:
 1.1

margin
Specifies an amount of cells by which to expandGridExtent
after rounding. This setting modifies computations performed by the following methods: For each dimension i of the grid computed by above methods, the low grid coordinate is subtracted bycellCount[i]
and the high grid coordinate is increased bycellCount[i]
. This calculation is done in units of the base grid cells, i.e. before subsampling. For example if subsampling is 2, then a margin of 6 cells specified with this method will result in a margin of 3 cells in the grid extent computed by thebuild()
method.Use case: if the caller wants to apply bilinear interpolations in an image, (s)he will need 1 more pixel on each image border. If the caller wants to apply bicubic interpolations, (s)he will need 2 more pixels on each image border.If this method is never invoked, the default value is zero for all dimensions. If this method is invoked too late, anIllegalStateException
is thrown. If thecellCounts
array length is shorter than the grid dimension, then zero is assumed for all missing dimensions. Parameters:
cellCounts
 number of cells by which to expand the grid extent. Returns:
this
for method call chaining. Throws:
IllegalArgumentException
 if a value is negative.IllegalStateException
 ifsubgrid(Envelope, double...)
orslice(DirectPosition)
has already been invoked. See Also:

chunkSize
Specifies the size of tiles or chunks in the base grid geometry. If a chunk size is specified, then the grid extent computed bybuild()
will span an integer amount of chunks. The grid coordinates (0, 0, …) locate the corner of a chunk.This property operates on the same methods than the margin. If both a margin and a chunk size are specified, then margins are added first and the resulting grid coordinates are rounded to chunk size. This calculation is done in units of the base grid cells, i.e. before subsampling. For example if subsampling is 2, then a tile size of 20×20 pixels specified with this method will result in a tile size of 10×10 cells in the grid extent computed by the
build()
method.If this method is never invoked, the default value is one for all dimensions. If this method is invoked too late, an
IllegalStateException
is thrown. If thecellCounts
array length is shorter than the grid dimension, then one is assumed for all missing dimensions. Parameters:
cellCounts
 number of cells in all tiles or chunks. Returns:
this
for method call chaining. Throws:
IllegalArgumentException
 if a value is zero or negative.IllegalStateException
 ifsubgrid(Envelope, double...)
orslice(DirectPosition)
has already been invoked. Since:
 1.1

maximumSubsampling
Specifies the maximum subsampling values (inclusive) for each dimension. If a subsampling value is greater than a specified value in the corresponding dimension, the subsampling will be clamped to the specified maximal value. Setting a maximum value of 1 in a dimension is equivalent to disabling subsampling in that dimension.If this method is never invoked, then there is no maximum value. If this method is invoked too late, an
IllegalStateException
is thrown. If thecellCounts
array length is shorter than the grid dimension, then all missing dimensions have no maximum value. Parameters:
subsampling
 maximal subsampling values (inclusive). Returns:
this
for method call chaining. Throws:
IllegalArgumentException
 if a value is zero or negative.IllegalStateException
 ifsubgrid(Envelope, double...)
orslice(DirectPosition)
has already been invoked. Since:
 1.1

resize
Deprecated.This method does not handle margin, chunk size and clipping according their contract. It is replaced bysubgrid(GridExtent, int...)
.Requests a grid geometry where cell sizes have been scaled by the given factors, which result in a change of grid size. The new grid geometry is given a "grid to CRS" transform computed as the concatenation of given scale factors (applied on grid indices) followed by the grid to CRS transform of the grid geometry specified at construction time. The resulting grid extent can be specified explicitly (typically as an extent computed byGridExtent.resize(long...)
) or computed automatically by this method.Example: if the original grid geometry had an extent of [0 … 5] in x and [0 … 8] in y, then a call toresize(null, 0.1, 0.1)
will build a grid geometry with an extent of [0 … 50] in x and [0 … 80] in y. This new extent covers the same geographic area than the old extent but with pixels having a size of 0.1 times the old pixels size. The grid to CRS transform of the new grid geometry will be preconcatenated with scale factors of 0.1 in compensation for the shrink in pixels size.Notes:
 This method can be invoked only once.
 This method can not be used together with a
subgrid(…)
method.  If a nondefault rounding mode or a nondefault clipping mode is desired, they should be specified before to invoke this method.
 If the grid extent is recomputed by this method, then the margin and chunkSize(int...) will be taken in account.
 This method does not reduce the number of dimensions of the grid geometry.
For dimensionality reduction, see
GridGeometry.reduce(int...)
.
scales
parameter in this method can be seen as an alternative to theresolution
parameter insubgrid(Envelope, double...)
working in grid coordinates space instead of CRS coordinates space. Parameters:
extent
 the grid extent to set as a result of the given scale, ornull
for computing it automatically. If nonnull, then this given extent is used asis without checking intersection with the base grid geometry.scales
 the scale factors to apply on grid indices. If the length of this array is smaller than the number of grid dimension, then a scale of 1 is assumed for all missing dimensions. Returns:
this
for method call chaining. Throws:
IllegalStateException
 if asubgrid(…)
orslice(…)
method has already been invoked. See Also:

subgrid
Adapts the base grid for the geographic area and resolution of the given grid geometry. The new grid geometry will cover the spatiotemporal region given byareaOfInterest
envelope (coordinate operations are applied as needed if the Coordinate Reference Systems are not the same). The new grid geometry resolution will be integer multiples of thebase
grid geometry resolution.Usage: This method can be helpful for implementation ofIfGridCoverageResource.read(GridGeometry, int...)
. Example:class MyDataStorage extends GridCoverageResource { @Override public GridCoverage read(GridGeometry domain, int... range) throws DataStoreException { GridDerivation change = getGridGeometry().derive().subgrid(domain); GridExtent toRead = change.buildExtent(); int[] subsampling = change.getSubsampling()); // Do reading here. } }
gridExtent
contains only an envelope, then this method delegates tosubgrid(Envelope, double...)
. Otherwise ifgridExtent
contains only an extent, then this method delegates tosubgrid(GridExtent, int...)
. Otherwise the following information are mandatory: Extent in
areaOfInterest
.  Grid to CRS conversion in
areaOfInterest
.  Grid to CRS conversion in
base
grid.
 Coordinate reference system in
areaOfInterest
.  Coordinate reference system in
base
grid.  Extent in
base
grid.
Notes:
 This method can be invoked only once.
 This method can not be used together with another
subgrid(…)
method.  Rounding mode, clipping mode, margin and chunk size, if different than default values, should be set before to invoke this method.
 Slicing can be applied after this method.
 This method does not reduce the number of dimensions of the grid geometry.
For dimensionality reduction, see
GridGeometry.reduce(int...)
.
 Parameters:
areaOfInterest
 the area of interest and desired resolution as a grid geometry. Returns:
this
for method call chaining. Throws:
DisjointExtentException
 if the given grid of interest does not intersect the grid extent.IncompleteGridGeometryException
 if a mandatory property of a grid geometry is absent.IllegalGridGeometryException
 if an error occurred while converting the envelope coordinates to grid coordinates.IllegalStateException
 if asubgrid(…)
orslice(…)
method has already been invoked. See Also:
 Extent in

subgrid
Requests a grid geometry over a subenvelope and optionally with a different a coarser resolution. The given envelope does not need to be expressed in the same coordinate reference system (CRS) than the CRS of the base grid geometry; coordinate conversions or transformations will be applied as needed. That envelope CRS may have fewer dimensions than the base grid geometry CRS, in which case grid dimensions not mapped to envelope dimensions will be returned unchanged. The target resolution, if provided, shall be in same units and same order than the given envelope axes. If the length ofresolution
array is less than the number of dimensions ofareaOfInterest
, then no subsampling will be applied on the missing dimensions.Notes:
 This method can be invoked only once.
 This method can not be used together with another
subgrid(…)
method.  Rounding mode, clipping mode, margin and chunk size, if different than default values, should be set before to invoke this method.
 Slicing can be applied after this method.
 This method does not reduce the number of dimensions of the grid geometry.
For dimensionality reduction, see
GridGeometry.reduce(int...)
.  If the given envelope is known to be expressed in the same CRS than the grid geometry,
then the CRS of the envelope
can be left unspecified (
null
). It may give a slight performance improvement by avoiding the check for coordinate transformation.  Subsampling computed by this method may be fractional. Consequently calls to
getSubsampling()
andgetSubsamplingOffsets()
after this method may cause anIllegalStateException
to be thrown.
 Parameters:
areaOfInterest
 the desired spatiotemporal region in any CRS (transformations will be applied as needed), ornull
for not restricting the subgrid to a subarea.resolution
 the desired resolution in the same units and order than the axes of the given envelope, ornull
or an empty array if no subsampling is desired. The array length should be equal to theareaOfInterest
dimension, but this is not mandatory (zero or missing values mean no subsampling, extraneous values are ignored). Returns:
this
for method call chaining. Throws:
DisjointExtentException
 if the given area of interest does not intersect the grid extent.IncompleteGridGeometryException
 if the base grid geometry has no extent, no "grid to CRS" transform, or no CRS (unlessareaOfInterest
has no CRS neither, in which case the CRS are assumed the same).IllegalGridGeometryException
 if an error occurred while converting the envelope coordinates to grid coordinates.IllegalStateException
 if asubgrid(…)
orslice(…)
method has already been invoked. See Also:

subgrid
Requests a grid geometry over a subregion of the base grid geometry and optionally with subsampling. The given grid geometry must have the same number of dimension than the base grid geometry. If the length ofsubsampling
array is less than the number of dimensions, then no subsampling will be applied on the missing dimensions.Notes:
 This method can be invoked only once.
 This method can not be used together with another
subgrid(…)
method.  Rounding mode, clipping mode, margin and chunk size, if different than default values, should be set before to invoke this method.
 Slicing can be applied after this method.
 This method does not reduce the number of dimensions of the grid geometry.
For dimensionality reduction, see
GridGeometry.reduce(int...)
.
 Parameters:
areaOfInterest
 the desired grid extent in unit of base grid cell (i.e. ignoring subsampling), ornull
for not restricting the subgrid to a subarea.subsampling
 the subsampling to apply on each grid dimension, ornull
if none. All values shall be greater than zero. If the array length is shorter than the number of dimensions, missing values are assumed to be 1. Returns:
this
for method call chaining. Throws:
DisjointExtentException
 if the given area of interest does not intersect the grid extent.IncompleteGridGeometryException
 if the base grid geometry has no extent, no "grid to CRS" transform, or no CRS (unlessareaOfInterest
has no CRS neither, in which case the CRS are assumed the same).IllegalStateException
 if asubgrid(…)
orslice(…)
method has already been invoked. Since:
 1.1
 See Also:

subsample
Deprecated.Replaced bysubgrid(GridExtent, int...)
with anull
extent.Applies a subsampling on the grid geometry to build. This method can be invoked as an alternative tosubgrid(…)
methods if only the resolution needs to be changed. The extent of the built grid geometry will be derived fromgetIntersection()
as below for each dimension i: The low is divided by
subsampling[i]
, rounded toward zero.  The size is divided by
subsampling[i]
, rounded toward zero.  The high is recomputed from above low and size.
Preconditions
This method assumes that subsampling are divisors of chunk sizes and are not greater than the maximum subsampling. It is caller responsibility to ensure that those preconditions are met. Parameters:
subsampling
 the subsampling to apply on each grid dimension. All values shall be greater than zero. If the array length is shorter than the number of dimensions, missing values are assumed to be 1. Returns:
this
for method call chaining. Throws:
IllegalStateException
 if a subsampling has already been set, for example by a call tosubgrid(…)
. See Also:
 The low is divided by

slice
Requests a grid geometry for a slice at the given "real world" position. The given position can be expressed in any coordinate reference system (CRS). The position should not define a coordinate for all dimensions, otherwise the slice would degenerate to a single point. Dimensions can be left unspecified either by assigning toslicePoint
a CRS without those dimensions, or by assigning the NaN value to some coordinates.Example: if the coordinate reference system of base grid geometry has (longitude, latitude, time) axes, then a (longitude, latitude) slice at time t can be created with one of the following two positions: A threedimensional position with (
Double.NaN
,Double.NaN
, t) coordinates.  A onedimensional position with (t) coordinate and the coordinate reference system set to the temporal component of the grid geometry CRS.
Notes:
 This method can be invoked after
subgrid(Envelope, double...)
, but not before.  If a nondefault rounding mode is desired, it should be specified before to invoke this method.
 This method does not reduce the number of dimensions of the grid geometry.
For dimensionality reduction, see
GridGeometry.reduce(int...)
.  If the given point is known to be expressed in the same CRS than the grid geometry,
then the CRS of the point
can be left unspecified (
null
). It may give a slight performance improvement by avoiding the check for coordinate transformation.
 Parameters:
slicePoint
 the coordinates where to get a slice. If no coordinate reference system is attached to it, we consider it's the same as base grid geometry. Returns:
this
for method call chaining. Throws:
IncompleteGridGeometryException
 if the base grid geometry has no extent, no "grid to CRS" transform, or no CRS (unlessslicePoint
has no CRS neither, in which case the CRS are assumed the same).IllegalGridGeometryException
 if an error occurred while converting the point coordinates to grid coordinates.PointOutsideCoverageException
 if the given point is outside the grid extent.
 A threedimensional position with (

sliceByRatio
Requests a grid geometry for a slice at the given relative position. The relative position is specified by a ratio between 0 and 1 where 0 maps to low grid coordinates, 1 maps to high grid coordinates and 0.5 maps to the median position. The slicing is applied on all dimensions except the specified dimensions to keep.Example: given a ndimensional cube, the following call creates a slice of the two first dimensions (numbered 0 and 1, typically the dimensions of x and y axes) located at the center (ratio 0.5) of all other dimensions (typically z and/or t axes):gridGeometry.derive().sliceByRatio(0.5, 0, 1).build();
 Parameters:
sliceRatio
 the ratio to apply on all grid dimensions except the ones to keep.dimensionsToKeep
 the grid dimension to keep unchanged. Returns:
this
for method call chaining. Throws:
IncompleteGridGeometryException
 if the base grid geometry has no extent.IndexOutOfBoundsException
 if adimensionsToKeep
value is out of bounds.

build
Builds a grid geometry with the configuration specified by the other methods in thisGridDerivation
class. Returns:
 the modified grid geometry. May be the
base
grid geometry if no change apply.  Throws:
IllegalGridGeometryException
 if the grid geometry can not be computed because of arguments given to asubgrid(…)
or other methods. See Also:

getIntersection
Returns the extent of the modified grid geometry, ignoring subsampling or changes in resolution. This is the intersection of thebase
grid geometry with the (grid or geospatial) envelope given to asubgrid(…)
method, expanded by the specified margin (if any) and potentially with some grid sizes set to 1 if aslice(…)
method has been invoked. The returned extent is in units of thebase
grid cells, i.e. subsampling is ignored.This method can be invoked after
build()
for getting additional information. Returns:
 intersection of grid geometry extents in units of
base
grid cells.

getSubsamplings
Deprecated.RenamedgetSubsampling()
(without "s" because "subsampling" is uncountable). 
getSubsampling
public int[] getSubsampling()Returns the strides for accessing cells along each axis of the base grid. Those values define part of the conversion from derived grid coordinates (x, y, z) to base grid coordinates (x′, y′, z′) as below (generalize to as many dimensions as needed): x′ = s₀⋅x + t₀
 y′ = s₁⋅y + t₁
 z′ = s₂⋅z + t₂
getSubsamplingOffsets()
returns the {t₀, t₁, t₂} values. All subsampling values are strictly positive integers.Application to iterationsThis method can be invoked after
Iteration overareaOfInterest
grid coordinates with a stride Δx=1 corresponds to an iteration inbase
grid coordinates with a stride of Δx′=s₀, a stride Δy=1 corresponds to a stride Δy′=s₁, etc.build()
for getting additional information. Ifsubgrid(GridExtent, int...)
has been invoked, then this method returns the values that were given in thesubsampling
argument. Returns:
 an estimation of the strides for accessing cells along each axis of
base
grid.  Throws:
IllegalStateException
 if the subsampling factors are not integers. It may happen if the derived grid has been constructed by a call tosubgrid(Envelope, double...)
. Since:
 1.1
 See Also:

getSubsamplingOffsets
public int[] getSubsamplingOffsets()Returns the offsets to be subtracted from pixel coordinates before subsampling. In a conversion from derived grid to base grid coordinates (the opposite direction of subsampling), the offset is the value to add after multiplication by the scale factor. It may be negative.This method can be invoked after
build()
for getting additional information. Returns:
 conversion from the new grid to the original grid specified to the constructor.
 Throws:
IllegalStateException
 if the subsampling offsets are not integers. It may happen if the derived grid has been constructed by a call tosubgrid(Envelope, double...)
. Since:
 1.1
 See Also:

getGlobalScale
Deprecated.To be removed for avoiding operations that mix potentially unrelated dimensions.Returns an estimation of the scale factor when converting subgrid coordinates tobase
grid coordinates. This is for information purpose only since this method combines potentially different scale factors for all dimensions. Returns:
 an estimation of the scale factor for all dimensions.

toString
Returns a string representation of thisGridDerivation
for debugging purpose. The returned string is implementation dependent and may change in any future version.
