Class GridExtent
- All Implemented Interfaces:
Serializable
,LenientComparable
GridExtent
are defined by low coordinates (often all zeros)
and high coordinates, inclusive.
For example a grid with a width of 512 cells can have a low coordinate of 0 and high coordinate of 511.
Rectangle
maximal values are exclusive.GridExtent
instances are immutable and thread-safe.
The same instance can be shared by different GridGeometry
instances.
GridEnvelope
interface in a future Apache SIS version.
This is pending GeoAPI update.- Since:
- 1.0
- See Also:
Defined in the sis-feature
module
-
Constructor Summary
ConstructorsConstructorDescriptionGridExtent
(long width, long height) Creates a new grid extent for an image or matrix of the given size.GridExtent
(Rectangle bounds) Creates a new grid extent for an image or matrix of the given bounds.GridExtent
(DimensionNameType[] axisTypes, long[] low, long[] high, boolean isHighIncluded) Constructs a new grid envelope set to the specified coordinates. -
Method Summary
Modifier and TypeMethodDescriptionboolean
contains
(long... indices) Returnstrue
if this extent contains the given cell indices.final boolean
Compares the specified object with this grid envelope for equality.boolean
equals
(Object object, ComparisonMode mode) Compares the specified object with this grid envelope for equality.expand
(long... margins) Returns a grid extent expanded by the given amount of cells on both sides along each dimension.getAxisType
(int index) Returns the type (vertical, temporal, …) of grid axis at given dimension.final int
Returns the number of dimensions.long
getHigh
(int index) Returns the valid maximum inclusive grid coordinate along the specified dimension.long
getLow
(int index) Returns the valid minimum inclusive grid coordinate along the specified dimension.double[]
Returns the grid coordinates of a representative point.long
getSize
(int index) Returns the number of integer grid coordinates along the specified dimension.double
getSize
(int index, boolean minusOne) Returns the number of grid coordinates as a double precision floating point value.int[]
getSubspaceDimensions
(int s) Returns indices of all dimensions where this grid extent has a size greater than 1.int
Returns a hash value for this grid envelope.insertDimension
(int offset, DimensionNameType axisType, long low, long high, boolean isHighIncluded) Returns a new grid envelope with the specified dimension inserted at the given index in this grid envelope.reduceDimension
(int... dimensions) Returns a grid extent that encompass only some dimensions of this grid extent.resize
(long... sizes) Sets the size of grid extent to the given values by moving low and high coordinates.boolean
Returnstrue
if all low coordinates are zero.subsample
(int... periods) Creates a new grid extent subsampled by the given amount of cells along each grid dimensions.toEnvelope
(MathTransform cornerToCRS) Transforms this grid extent to a "real world" envelope using the given transform.Returns a string representation of this grid envelope.translate
(long... translation) Returns an extent translated by the given amount of cells compared to this extent.
-
Constructor Details
-
GridExtent
Creates a new grid extent for an image or matrix of the given bounds. The axis types areDimensionNameType.COLUMN
andROW
in that order.- Parameters:
bounds
- the bounds to copy in the new grid extent.- Since:
- 1.1
-
GridExtent
public GridExtent(long width, long height) Creates a new grid extent for an image or matrix of the given size. The low grid coordinates are zeros and the axis types areDimensionNameType.COLUMN
andROW
in that order.- Parameters:
width
- number of pixels in each row.height
- number of pixels in each column.
-
GridExtent
Constructs a new grid envelope set to the specified coordinates. The given arrays contain a minimum (inclusive) and maximum value for each dimension of the grid coverage. The lowest valid grid coordinates are often zero, but this is not mandatory. As a convenience for this common case, a nulllow
array means that all low coordinates are zero.An optional (nullable)
axisTypes
argument can be used for attaching a label to each grid axis. For example if thisGridExtent
is four-dimensional, then the axis types may be {column (x), row (y), vertical (z), time (t)}, which means that the last axis is for the temporal dimension, the third axis is for the vertical dimension, etc. This information is related to the "real world" coordinate reference system axes, but not necessarily in the same order; it is caller responsibility to ensure that the grid axes are consistent with the CRS axes. TheaxisTypes
array shall not contain duplicated elements, but may containnull
elements if the type of some axes are unknown.- Parameters:
axisTypes
- the type of each grid axis, ornull
if unspecified.low
- the valid minimum grid coordinates (always inclusive), ornull
for all zeros.high
- the valid maximum grid coordinates, inclusive or exclusive depending on the next argument.isHighIncluded
-true
if thehigh
values are inclusive (as in ISO 19123 specification), orfalse
if they are exclusive (as in Java2D usage). This argument does not apply tolow
values, which are always inclusive.- Throws:
IllegalArgumentException
- if a coordinate value in the low part is greater than the corresponding coordinate value in the high part.- See Also:
-
getLow()
getHigh()
insertDimension(int, DimensionNameType, long, long, boolean)
-
-
Method Details
-
getDimension
public final int getDimension()Returns the number of dimensions.- Returns:
- the number of dimensions.
- See Also:
-
startsAtZero
public boolean startsAtZero()Returnstrue
if all low coordinates are zero. This is a very common case since many grids start their cell numbering at zero.- Returns:
- whether all low coordinates are zero.
- See Also:
-
getLow
public long getLow(int index) Returns the valid minimum inclusive grid coordinate along the specified dimension.- Parameters:
index
- the dimension for which to obtain the coordinate value.- Returns:
- the low coordinate value at the given dimension, inclusive.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equals or greater than the grid dimension.- See Also:
-
getHigh
public long getHigh(int index) Returns the valid maximum inclusive grid coordinate along the specified dimension.- Parameters:
index
- the dimension for which to obtain the coordinate value.- Returns:
- the high coordinate value at the given dimension, inclusive.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equals or greater than the grid dimension.- See Also:
-
getSize
public long getSize(int index) Returns the number of integer grid coordinates along the specified dimension. This is equal togetHigh(dimension) - getLow(dimension) + 1
.- Parameters:
index
- the dimension for which to obtain the size.- Returns:
- the number of integer grid coordinates along the given dimension.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equals or greater than the grid dimension.ArithmeticException
- if the size is too large for thelong
primitive type.- See Also:
-
getSize
public double getSize(int index, boolean minusOne) Returns the number of grid coordinates as a double precision floating point value. Invoking this method is equivalent to invokinggetSize(int)
and converting the result fromlong
to thedouble
primitive type, except that this method does not overflow (i.e. does not throwArithmeticException
).- Parameters:
index
- the dimension for which to obtain the size.minusOne
-true
for returning size−1 instead of size.- Returns:
- the number of integer grid coordinates along the given dimension.
-
getPointOfInterest
public double[] getPointOfInterest()Returns the grid coordinates of a representative point. This point may be used for estimating a grid resolution. The default implementation returns the median (or center) coordinates of this grid extent, but subclasses can override this method if another point is considered more representative.- Returns:
- the grid coordinates of a representative point.
-
getSubspaceDimensions
public int[] getSubspaceDimensions(int s) Returns indices of all dimensions where this grid extent has a size greater than 1. This method can be used for getting the grid extent of a s-dimensional slice in a n-dimensional cube where s ≤ n.Example: suppose that we want to get a two-dimensional slice (y,z) in a four-dimensional data cube (x,y,z,t). The first step is to specify the x and t coordinates of the slice. In this example we set x to 5 and t to 8.This method returns exactly s indices. If there is more than s dimensions having a size greater than 1, then a
Above code created a slice at the requested position, but that slice still have 4 dimensions. It is a "slice" because the x and t dimensions ofGridGeometry grid = ...; // Geometry of the (x,y,z,t) grid. GridGeometry slice4D = grid.slice(new GeneralDirectPosition(5, NaN, NaN, 8));
slice4D
have only one cell. If a two-dimensional slice is desired, then above operations can be completed as below. In this example, the result ofgetSubspaceDimensions(2)
call will be {1,2}.
Note that in this particular example, it would have been more efficient to executeint[] subDimensions = slice4D.getExtent().getSubspaceDimensions(2); GridGeometry slice2D = slice4D.reduce(subDimensions);
grid.reduce(1,2)
directly. ThisgetSubspaceDimensions(int)
method is more useful for inferring aslice2D
from aslice4D
which has been created elsewhere, or when we do not really want theslice2D
but only its dimension indices.SubspaceNotSpecifiedException
is thrown. If there is less than s dimensions having a size greater than 1, then the returned list of dimensions is completed with some dimensions of size 1, starting with the first dimensions in this grid extent, until there is exactly s dimensions. If this grid extent does not have at least s dimensions, then aCannotEvaluateException
is thrown.- Parameters:
s
- number of dimensions of the sub-space.- Returns:
- indices of sub-space dimensions, in increasing order in an array of length s.
- Throws:
SubspaceNotSpecifiedException
- if there is more than s dimensions having a size greater than 1.CannotEvaluateException
- if this grid extent does not have at least s dimensions.
-
getAxisType
Returns the type (vertical, temporal, …) of grid axis at given dimension. This information is provided because the grid axis type can not always be inferred from the context. Some examples are:getAxisType(0)
may returnDimensionNameType.COLUMN
,TRACK
orLINE
.getAxisType(1)
may returnDimensionNameType.ROW
,CROSS_TRACK
orSAMPLE
.getAxisType(2)
may returnDimensionNameType.VERTICAL
.getAxisType(3)
may returnDimensionNameType.TIME
.
- Parameters:
index
- the dimension for which to obtain the axis type.- Returns:
- the axis type at the given dimension. May be absent if the type is unknown.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equals or greater than the grid dimension.
-
toEnvelope
Transforms this grid extent to a "real world" envelope using the given transform. The transform shall map cell corner to real world coordinates.- Parameters:
cornerToCRS
- a transform from cell corners to real world coordinates.- Returns:
- this grid extent in real world coordinates.
- Throws:
TransformException
- if the envelope can not be computed with the given transform.- Since:
- 1.1
- See Also:
-
insertDimension
public GridExtent insertDimension(int offset, DimensionNameType axisType, long low, long high, boolean isHighIncluded) Returns a new grid envelope with the specified dimension inserted at the given index in this grid envelope. To append a new dimension after all existing dimensions, setoffset
togetDimension()
.- Parameters:
offset
- where to insert the new dimension, from 0 togetDimension()
inclusive.axisType
- the type of the grid axis to add, ornull
if unspecified.low
- the valid minimum grid coordinate (always inclusive).high
- the valid maximum grid coordinate, inclusive or exclusive depending on the next argument.isHighIncluded
-true
if thehigh
value is inclusive (as in ISO 19123 specification), orfalse
if it is exclusive (as in Java2D usage). This argument does not apply tolow
value, which is always inclusive.- Returns:
- a new grid envelope with the specified dimension added.
- Throws:
IllegalArgumentException
- if the low coordinate value is greater than the high coordinate value.- Since:
- 1.1
-
expand
Returns a grid extent expanded by the given amount of cells on both sides along each dimension. This method adds the given margins to the high coordinates and subtracts the same margins from the low coordinates. If a negative margin is supplied, the extent size decreases accordingly.Number of arguments
Themargins
array length should be equal to the number of dimensions. If the array is shorter, missing values default to 0 (i.e. sizes in unspecified dimensions are unchanged). If the array is longer, extraneous values are ignored.- Parameters:
margins
- amount of cells to add or subtract on both sides for each dimension.- Returns:
- a grid extent expanded by the given amount, or
this
if there is no change. - Throws:
ArithmeticException
- if expanding this extent by the given margins overflowslong
capacity.- See Also:
-
resize
Sets the size of grid extent to the given values by moving low and high coordinates. This method modifies grid coordinates as if they were multiplied by (given size) / (current size), rounded toward zero and with the value farthest from zero adjusted by ±1 for having a size exactly equals to the specified value. In the common case where the low value is zero, this is equivalent to setting the high value tosize
- 1.Number of arguments
Thesizes
array length should be equal to the number of dimensions. If the array is shorter, sizes in unspecified dimensions are unchanged. If the array is longer, extraneous values are ignored.- Parameters:
sizes
- the new grid sizes for each dimension.- Returns:
- a grid extent having the given sizes, or
this
if there is no change. - Throws:
ArithmeticException
- if resizing this extent to the given size overflowslong
capacity.- See Also:
-
reduceDimension
Returns a grid extent that encompass only some dimensions of this grid extent. This method copies the specified dimensions of this grid extent into a new grid extent. The given dimensions must be in strictly ascending order without duplicated values. The number of dimensions of the sub grid envelope will bedimensions.length
.This method performs a dimensionality reduction and can be used as the converse of
insertDimension(int, DimensionNameType, long, long, boolean)
. This method can not be used for changing dimension order.- Parameters:
dimensions
- the dimensions to select, in strictly increasing order.- Returns:
- the sub-envelope, or
this
if the given array contains all dimensions of this grid extent. - Throws:
IndexOutOfBoundsException
- if an index is out of bounds.- Since:
- 1.1
- See Also:
-
subsample
Creates a new grid extent subsampled by the given amount of cells along each grid dimensions. This method divides low coordinates and grid sizes by the given periods, rounding toward zero. The high coordinates are adjusted accordingly (this is often equivalent to dividing high coordinates by the periods too, but a difference of one cell may exist).Note: The envelope computed from a grid extent may become larger after subsampling, not smaller. This effect can be understood intuitively if we consider that cells become larger after subsampling, which implies that accurate representation of the same envelope may require fractional cells on some grid borders.This method does not reduce the number of dimensions of the grid extent. For dimensionality reduction, seereduceDimension(int[])
.Number of arguments
Theperiods
array length should be equal to the number of dimensions. If the array is shorter, missing values default to 1 (i.e. samplings in unspecified dimensions are unchanged). If the array is longer, extraneous values are ignored.- Parameters:
periods
- the subsampling. Length shall be equal to the number of dimension and all values shall be greater than zero.- Returns:
- the subsampled extent, or
this
is subsampling results in the same extent. - Throws:
IllegalArgumentException
- if a period is not greater than zero.- See Also:
-
translate
Returns an extent translated by the given amount of cells compared to this extent. The returned extent has the same size than this extent, i.e. both low and high grid coordinates are displaced by the same amount of cells.Example: for an extent (x: [0…10], y: [2…4], z: [0…1]) and a translation {-2, 2}, the resulting extent would be (x: [-2…8], y: [4…6], z: [0…1]).Number of arguments
Thetranslation
array length should be equal to the number of dimensions. If the array is shorter, missing values default to 0 (i.e. no translation in unspecified dimensions). If the array is longer, extraneous values are ignored.- Parameters:
translation
- translation to apply on each axis in order.- Returns:
- a grid extent whose coordinates (both low and high ones) have been translated by given amounts. If the given translation is a no-op (no value or only 0 ones), then this extent is returned as is.
- Throws:
ArithmeticException
- if the translation results in coordinates that overflow 64-bits integer.- Since:
- 1.1
- See Also:
-
contains
public boolean contains(long... indices) Returnstrue
if this extent contains the given cell indices. An index is considered inside the grid extent if its value is betweenlow
andhigh
bounds, inclusive.Number of arguments
Theindices
array length should be equal to the number of dimensions. If the array is shorter, missing index values are considered inside the extent. If the array is longer, extraneous values are ignored.- Parameters:
indices
- indices of the grid cell to check.- Returns:
- whether the given indices are inside this extent.
- Since:
- 1.2
-
hashCode
public int hashCode()Returns a hash value for this grid envelope. This value needs not to remain consistent between different implementations of the same class. -
equals
Compares the specified object with this grid envelope for equality. This method delegates toequals(object, ComparisonMode.STRICT)
.- Specified by:
equals
in interfaceLenientComparable
- Overrides:
equals
in classObject
- Parameters:
object
- the object to compare with this grid envelope for equality.- Returns:
true
if the given object is equal to this grid envelope.- See Also:
-
equals
Compares the specified object with this grid envelope for equality. If the mode isComparisonMode.IGNORE_METADATA
or more flexible, then the axis types are ignored.- Specified by:
equals
in interfaceLenientComparable
- Parameters:
object
- the object to compare with this grid envelope for equality.mode
- the strictness level of the comparison.- Returns:
true
if the given object is equal to this grid envelope.- Since:
- 1.1
- See Also:
-
toString
Returns a string representation of this grid envelope. The returned string is implementation dependent and is provided for debugging purposes only.
-