Class GridExtent
- All Implemented Interfaces:
Serializable
,LenientComparable
- Direct Known Subclasses:
CanvasExtent
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
- Version:
- 1.3
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final Map<org.opengis.referencing.cs.AxisDirection,
org.opengis.metadata.spatial.DimensionNameType> The dimension name types for given coordinate system axis directions.private final long[]
Minimum and maximum grid coordinates.private static final org.opengis.metadata.spatial.DimensionNameType[]
Default axis types for the two-dimensional cases.private static final WeakValueHashMap<org.opengis.metadata.spatial.DimensionNameType[],
org.opengis.metadata.spatial.DimensionNameType[]> A pool of sharedDimensionNameType
arrays.private static final long
Serial number for inter-operability with different versions.private final org.opengis.metadata.spatial.DimensionNameType[]
Type of each axis (vertical, temporal, …) ornull
if unspecified. -
Constructor Summary
ConstructorsModifierConstructorDescription(package private)
GridExtent
(int xmin, int ymin, int width, int height) Creates a new grid extent for an image of the given size and location.private
GridExtent
(int dimension, org.opengis.metadata.spatial.DimensionNameType[] axisTypes) Creates an initially empty grid extent with the given number of dimensions.GridExtent
(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.private
GridExtent
(GridExtent extent) Creates a copy of the given grid extent.(package private)
GridExtent
(GridExtent enclosing, long[] coordinates) Creates a new grid extent with the same axes than the given extent, but different coordinates.(package private)
GridExtent
(AbstractEnvelope envelope, GridRoundingMode rounding, GridClippingMode clipping, int[] margin, int[] chunkSize, GridExtent enclosing, int[] modifiedDimensions) Creates a new grid extent by rounding the given envelope to (usually) nearest integers.GridExtent
(org.opengis.metadata.spatial.DimensionNameType[] axisTypes, long[] low, long[] high, boolean isHighIncluded) Constructs a new grid extent set to the specified coordinates. -
Method Summary
Modifier and TypeMethodDescription(package private) static long[]
allocate
(int dimension) Creates a new array of coordinates with the given number of dimensions.(package private) final void
appendTo
(Appendable out, Vocabulary vocabulary) Writes a string representation of this grid extent in the given buffer.private GridExtent
combine
(GridExtent other, boolean union) Implementation ofunion(GridExtent)
andintersect(GridExtent)
private void
complete
(GeneralEnvelope envelope, org.opengis.referencing.operation.MathTransform gridToCRS, boolean isCenter, org.opengis.geometry.Envelope fallback) If the envelope contains some NaN values, tries to replace them by constant values inferred from the math transform.boolean
contains
(long... indices) Returnstrue
if this extent contains the given cell indices.(package private) final MatrixSIS
cornerToCRS
(org.opengis.geometry.Envelope env, long flippedAxes, int[] sourceDimensions) Creates an affine transform from the coordinates of this grid to the coordinates of the given envelope.final boolean
Compares the specified object with this grid extent for equality.boolean
equals
(Object object, ComparisonMode mode) Compares the specified object with this grid extent for equality.expand
(long... margins) Returns a grid extent expanded by the given amount of cells on both sides along each dimension.private static long
extremum
(long a, long b, boolean max) Returns the minimum or maximum value between the given pair of values.(package private) final GridExtent
forChunkSize
(int... sizes) Returns a grid extent expanded by the minimal amount of cells needed for covering an integer amount of chunks.(package private) final Object
getAxisIdentification
(int index, int indexShown) Returns the axis number followed by the localized axis type if available.Optional<org.opengis.metadata.spatial.DimensionNameType>
getAxisType
(int index) Returns the type (vertical, temporal, …) of grid axis at given dimension.(package private) final org.opengis.metadata.spatial.DimensionNameType[]
final int
Returns the number of dimensions.(package private) GridCoordinatesView
getHigh()
Returns the valid maximum grid coordinates, inclusive.long
getHigh
(int index) Returns the valid maximum inclusive grid coordinate along the specified dimension.(package private) GridCoordinatesView
getLow()
Returns the valid minimum grid coordinates, inclusive.long
getLow
(int index) Returns the valid minimum inclusive grid coordinate along the specified dimension.long
getMedian
(int index) Returns the average of low and high coordinates, rounded toward positive infinity.double[]
Deprecated.double[]
getPointOfInterest
(org.opengis.referencing.datum.PixelInCell anchor) 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.Returns the grid coordinates for all dimensions where the grid has a size of 1.(package private) final int
Returns the number of dimensions where this grid extent has a size greater than 1.int[]
getSubspaceDimensions
(int s) Returns indices of all dimensions where this grid extent has a size greater than 1.int
hashCode()
Returns a hash value for this grid extent.insertDimension
(int offset, org.opengis.metadata.spatial.DimensionNameType axisType, long low, long high, boolean isHighIncluded) Returns a new grid extent with the specified dimension inserted at the given index in this grid extent.intersect
(GridExtent other) Returns the intersection of this grid extent with the given grid extent.(package private) final boolean
isSameSize
(GridExtent other) Returns whether this grid extent has the same size than the given extent.private static boolean
isZero
(long[] vector, int n) Returnstrue
if all values in the given vector are zero.reduceDimension
(int... dimensions) Deprecated.RenamedselectDimensions(int...)
for clarity.(package private) final GridExtent
reorder
(int[] dimensions) Changes axis order or reduces the number of dimensions.resize
(long... sizes) Sets the size of grid extent to the given values by moving low and high coordinates.selectDimensions
(int... dimensions) Returns a grid extent that encompass only some dimensions of this grid extent.(package private) final GridExtent
slice
(org.opengis.geometry.DirectPosition slicePoint, int[] modifiedDimensions) Creates a new grid extent which represent a slice of this grid at the given point.(package private) final GridExtent
sliceByRatio
(org.opengis.geometry.DirectPosition slicePoint, double sliceRatio, int[] dimensionsToKeep) Returns a slice of this grid extent computed by a ratio between 0 and 1 inclusive.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.(package private) final GeneralEnvelope
Returns the coordinates of this grid extent in an envelope.toEnvelope
(org.opengis.referencing.operation.MathTransform cornerToCRS) Transforms this grid extent to a "real world" envelope using the given transform.(package private) final GeneralEnvelope
toEnvelope
(org.opengis.referencing.operation.MathTransform cornerToCRS, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.geometry.Envelope fallback) Transforms this grid extent to a "real world" envelope using the given transform.(package private) final GeneralEnvelope[]
toEnvelopes
(org.opengis.referencing.operation.MathTransform cornerToCRS, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.geometry.Envelope fallback) Transforms this grid extent to "real world" envelopes using the given transform.(package private) static String
toSizeString
(long size) Returns a string representation of the given size, assumed computed byhigh - low + 1
.toString()
Returns a string representation of this grid extent.translate
(long... translation) Returns an extent translated by the given amount of cells compared to this extent.private void
translate2D
(long xmin, long ymin) Completes aGridExtent
construction with a final translation.(package private) static org.opengis.metadata.spatial.DimensionNameType[]
typeFromAxes
(org.opengis.referencing.crs.CoordinateReferenceSystem crs, int dimension) Infers the axis types from the given coordinate reference system.union
(GridExtent other) Returns the union of this grid extent with the given grid extent.upsample
(int... periods) Creates a new grid extent upsampled by the given amount of cells along each grid dimensions.private static org.opengis.metadata.spatial.DimensionNameType[]
validateAxisTypes
(org.opengis.metadata.spatial.DimensionNameType[] types) Verifies that the given array (if non-null) contains no duplicated values, then returns a copy of that array.private void
Checks if coordinate values in the low part are less than or equal to the corresponding coordinate value in the high part.(package private) static int[]
verifyDimensions
(int[] dimensions, int limit) Verifies the validity of a givendimensions
argument.withRange
(int index, long low, long high) Returns a grid extent identical to this grid extent except for the coordinate values in the specified dimension.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
AXIS_DIRECTIONS
private static final Map<org.opengis.referencing.cs.AxisDirection,org.opengis.metadata.spatial.DimensionNameType> AXIS_DIRECTIONSThe dimension name types for given coordinate system axis directions. This map contains only the "positive" axis directions. -
DEFAULT_TYPES
private static final org.opengis.metadata.spatial.DimensionNameType[] DEFAULT_TYPESDefault axis types for the two-dimensional cases. -
POOL
private static final WeakValueHashMap<org.opengis.metadata.spatial.DimensionNameType[],org.opengis.metadata.spatial.DimensionNameType[]> POOLA pool of sharedDimensionNameType
arrays. We use a pool because a small amount of arrays is shared by most grid extents. -
types
private final org.opengis.metadata.spatial.DimensionNameType[] typesType of each axis (vertical, temporal, …) ornull
if unspecified. If non-null, the array length shall be equal togetDimension()
. Any array element may be null if unspecified for that particular axis. The same array may be shared by manyGridExtent
instances.- See Also:
-
coordinates
private final long[] coordinatesMinimum and maximum grid coordinates. The first half contains minimum coordinates (inclusive), while the last half contains maximum coordinates (inclusive). Note that the later inclusiveness is the opposite of Java2D usage but conforms to ISO specification.
-
-
Constructor Details
-
GridExtent
private GridExtent(int dimension, org.opengis.metadata.spatial.DimensionNameType[] axisTypes) Creates an initially empty grid extent with the given number of dimensions. All grid coordinate values are initialized to zero. This constructor is private becauseGridExtent
coordinate values cannot be modified by public API.- Parameters:
dimension
- number of dimensions.axisTypes
- the axis types, ornull
if unspecified.- See Also:
-
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.- Throws:
IllegalArgumentException
- if the rectangle is empty.- 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.- Throws:
IllegalArgumentException
- if the width or the height is not greater than zero.
-
GridExtent
GridExtent(int xmin, int ymin, int width, int height) Creates a new grid extent for an image of the given size and location. This constructor is for internal usage: argument meanings differ from conventions in public constructors.- Parameters:
xmin
- column index of the first cell.ymin
- row index of the first cell.width
- number of pixels in each row.height
- number of pixels in each column.
-
GridExtent
public GridExtent(org.opengis.metadata.spatial.DimensionNameType[] axisTypes, long[] low, long[] high, boolean isHighIncluded) Constructs a new grid extent 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:
-
GridExtent
GridExtent(AbstractEnvelope envelope, GridRoundingMode rounding, GridClippingMode clipping, int[] margin, int[] chunkSize, GridExtent enclosing, int[] modifiedDimensions) Creates a new grid extent by rounding the given envelope to (usually) nearest integers. The envelope coordinates shall be cell indices with lower values inclusive and upper values exclusive.Double.NaN
envelope coordinates will be set to the correspondingenclosing
coordinates (an exception will be thrown ifenclosing
is null in that situation). Envelopes crossing the anti-meridian shall be simplified. The envelope CRS is ignored, except for identifying dimension names for information purpose. The way floating point values are rounded to integers may be adjusted in any future version.API note: this constructor is not public because its contract is a bit approximate.
- Parameters:
envelope
- the envelope containing cell indices to store in aGridExtent
.rounding
- controls behavior of rounding from floating point values to integers.clipping
- how to clip this extent to the enclosing extent. Ignored ifenclosing
is null.margin
- if non-null, expands the extent by that amount of cells on each envelope dimension.chunkSize
- if non-null, make the grid extent spanning an integer amount of chunks (tiles).enclosing
- if the new grid is a sub-grid of a larger grid, that larger grid. Otherwisenull
.modifiedDimensions
- ifenclosing
is non-null, the grid dimensions to set from the envelope. The length of this array shall be equal to theenvelope
dimension. This argument is ignored ifenclosing
is null.- Throws:
DisjointExtentException
- if the given envelope does not intersect the enclosing grid extent.- See Also:
-
GridExtent
GridExtent(GridExtent enclosing, long[] coordinates) Creates a new grid extent with the same axes than the given extent, but different coordinates. This constructor does not invokevalidateCoordinates()
; we presume that the caller's computation is correct.- Parameters:
enclosing
- the extent from which to copy axes, ornull
if none.coordinates
- the coordinates. This array is not cloned.
-
GridExtent
Creates a copy of the given grid extent. Thecoordinates
array is cloned while thetypes
array is shared between the two instances. This constructor is reserved to methods that modify the coordinates after construction. It must be private because we do not allow coordinates modifications by public API.- See Also:
-
-
Method Details
-
allocate
Creates a new array of coordinates with the given number of dimensions.- Throws:
IllegalArgumentException
- if the given number of dimensions is excessive.
-
validateCoordinates
Checks if coordinate values in the low part are less than or equal to the corresponding coordinate value in the high part.- Throws:
IllegalArgumentException
- if a coordinate value in the low part is greater than the corresponding coordinate value in the high part.
-
validateAxisTypes
private static org.opengis.metadata.spatial.DimensionNameType[] validateAxisTypes(org.opengis.metadata.spatial.DimensionNameType[] types) throws IllegalArgumentException Verifies that the given array (if non-null) contains no duplicated values, then returns a copy of that array. The returned copy may be shared by manyGridExtent
instances. Consequently, it shall not be modified.- Throws:
IllegalArgumentException
- if the given array contains duplicated elements.
-
translate2D
private void translate2D(long xmin, long ymin) Completes aGridExtent
construction with a final translation. Shall be invoked for two-dimensional extents only. -
typeFromAxes
static org.opengis.metadata.spatial.DimensionNameType[] typeFromAxes(org.opengis.referencing.crs.CoordinateReferenceSystem crs, int dimension) Infers the axis types from the given coordinate reference system. This method is the converse ofGridExtentCRS
.- Parameters:
crs
- the coordinate reference system, ornull
.dimension
- number of name type to infer. Shall not be greater than the CRS dimension.- Returns:
- axis types, or
null
if no axis were recognized.
-
getDimension
public final int getDimension()Returns the number of dimensions.- Returns:
- the number of dimensions.
- See Also:
-
getSubDimension
final int getSubDimension()Returns the number of dimensions where this grid extent has a size greater than 1. This is a value between 0 andgetDimension()
inclusive.- Returns:
- the number of dimensions where this grid extent has a size greater than 1.
- 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:
-
isZero
private static boolean isZero(long[] vector, int n) Returnstrue
if all values in the given vector are zero.- Parameters:
vector
- the vector to verify.n
- number of elements to verify. All remaining elements are ignored.- Returns:
- whether the n first elements in the given array are all zero.
-
getLow
GridCoordinatesView getLow()Returns the valid minimum grid coordinates, inclusive. The sequence contains a minimum value for each dimension of the grid coverage.- Returns:
- the valid minimum grid coordinates, inclusive.
- See Also:
-
getHigh
GridCoordinatesView getHigh()Returns the valid maximum grid coordinates, inclusive. The sequence contains a maximum value for each dimension of the grid coverage.- Returns:
- the valid maximum grid coordinates, inclusive.
- 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 equal 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 equal or greater than the grid dimension.- See Also:
-
getMedian
public long getMedian(int index) Returns the average of low and high coordinates, rounded toward positive infinity. This method is equivalent to computing any of the following, except that this method does not overflow even if the sum would overflow:- (low + high) / 2 rounded toward positive infinity, or
- (low + high + 1) / 2 rounded toward negative infinity.
- Parameters:
index
- the dimension for which to obtain the coordinate value.- Returns:
- the median coordinate value at the given dimension.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equal or greater than the grid dimension.- Since:
- 1.3
-
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 equal 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
Deprecated.Replaced bygetPointOfInterest(PixelInCell)
.- Returns:
- the grid coordinates of a representative point.
-
getPointOfInterest
public double[] getPointOfInterest(org.opengis.referencing.datum.PixelInCell anchor) 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.The
anchpr
argument tells which transform the caller intend to use for converting the grid coordinates to "real world" coordinates. With the default implementation, the coordinate values returned withCELL_CORNER
are 0.5 cell units higher than the coordinate values returned withCELL_CENTER
. Subclasses are free to ignore this argument.- Parameters:
anchor
- the convention to be used for conversion to "real world" coordinates.- Returns:
- the grid coordinates of a representative point.
- Since:
- 1.3
-
getSliceCoordinates
Returns the grid coordinates for all dimensions where the grid has a size of 1. Keys are dimensions as values from 0 inclusive togetDimension()
exclusive. Values are the low and high coordinates (which are equal) in the associated dimension.- Returns:
- grid coordinates for all dimensions where the grid has a size of 1.
- Since:
- 1.3
- See Also:
-
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. 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 ofThis method returns exactly s indices. If there is more than s dimensions having a size greater than 1, then aslice4D
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 executegrid.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 cannot 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 equal or greater than the grid dimension.
-
getAxisTypes
final org.opengis.metadata.spatial.DimensionNameType[] getAxisTypes() -
getAxisIdentification
Returns the axis number followed by the localized axis type if available. This is used for error messages only.- Parameters:
index
- index of the dimension as stored in this grid extent.indexShown
- index to write in the message. Often the same asindex
.
-
withRange
Returns a grid extent identical to this grid extent except for the coordinate values in the specified dimension. This grid extent is not modified.- Parameters:
index
- the dimension for which to set the coordinate values.low
- the low coordinate value at the given dimension, inclusive.high
- the high coordinate value at the given dimension, inclusive.- Returns:
- a grid extent with the specified coordinate values, or
this
if values are unchanged. - Throws:
IllegalArgumentException
- if the low coordinate value is greater than the high coordinate value.- Since:
- 1.3
- See Also:
-
toEnvelope
public GeneralEnvelope toEnvelope(org.opengis.referencing.operation.MathTransform cornerToCRS) throws org.opengis.referencing.operation.TransformException 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:
org.opengis.referencing.operation.TransformException
- if the envelope cannot be computed with the given transform.- Since:
- 1.1
- See Also:
-
GridGeometry.getEnvelope()
PixelInCell.CELL_CORNER
-
toEnvelope
final GeneralEnvelope toEnvelope(org.opengis.referencing.operation.MathTransform cornerToCRS, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.geometry.Envelope fallback) throws org.opengis.referencing.operation.TransformException Transforms this grid extent to a "real world" envelope using the given transform. The transform shall map cell corner to real world coordinates. This method does not set the envelope coordinate reference system.- Parameters:
cornerToCRS
- a transform from cell corners to real world coordinates.gridToCRS
- the transform specified by the user. May be the same ascornerToCRS
. If different, then this is assumed to map cell centers instead of cell corners.fallback
- bounds to use if some values are still NaN after conversion, ornull
if none.- Returns:
- this grid extent in real world coordinates.
- Throws:
org.opengis.referencing.operation.TransformException
- if the envelope cannot be computed with the given transform.- See Also:
-
#GridExtent(AbstractEnvelope, GridRoundingMode, int[], GridExtent, int[])
GridGeometry.getEnvelope(CoordinateReferenceSystem)
-
toEnvelope
Returns the coordinates of this grid extent in an envelope. The returned envelope has no CRS. -
toEnvelopes
final GeneralEnvelope[] toEnvelopes(org.opengis.referencing.operation.MathTransform cornerToCRS, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.geometry.Envelope fallback) throws org.opengis.referencing.operation.TransformException Transforms this grid extent to "real world" envelopes using the given transform. This method usually returns exactly one envelope, but may return more envelopes if the given transform contains at least oneWraparoundTransform
step.- Parameters:
cornerToCRS
- a transform from cell corners to real world coordinates.gridToCRS
- the transform specified by the user. May be the same ascornerToCRS
. If different, then this is assumed to map cell centers instead of cell corners.fallback
- bounds to use if some values are still NaN after conversion, ornull
if none.- Returns:
- this grid extent in real world coordinates.
- Throws:
org.opengis.referencing.operation.TransformException
- if the envelope cannot be computed with the given transform.- See Also:
-
#GridExtent(AbstractEnvelope, GridRoundingMode, int[], GridExtent, int[])
GridGeometry.getEnvelope(CoordinateReferenceSystem)
-
complete
private void complete(GeneralEnvelope envelope, org.opengis.referencing.operation.MathTransform gridToCRS, boolean isCenter, org.opengis.geometry.Envelope fallback) If the envelope contains some NaN values, tries to replace them by constant values inferred from the math transform. We must use theMathTransform
specified by the user (gridToCRS
), not necessarilycornerToCRS
, because inferring acornerToCRS
by translating acenterToCRS
by 0.5 cell increase the amount of NaN values in the matrix. For giving a chance toTransformSeparator
to perform its work, we need the minimal amount of NaN values.- Parameters:
envelope
- the envelope to complete if empty.gridToCRS
- the transform specified by user.isCenter
- whether the "grid to CRS" transform maps cell center instead of cell corners.fallback
- bounds to use if some values are still NaN after conversion, ornull
if none.
-
insertDimension
public GridExtent insertDimension(int offset, org.opengis.metadata.spatial.DimensionNameType axisType, long low, long high, boolean isHighIncluded) Returns a new grid extent with the specified dimension inserted at the given index in this grid extent. 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 extent with the specified dimension added.
- Throws:
IllegalArgumentException
- if the low coordinate value is greater than the high coordinate value.- Since:
- 1.1
- See Also:
-
selectDimensions
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 extent 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 cannot 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.3
- See Also:
-
reduceDimension
Deprecated.RenamedselectDimensions(int...)
for clarity.Returns a grid extent that encompass only some dimensions of this grid extent.- 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. - Since:
- 1.1
-
verifyDimensions
static int[] verifyDimensions(int[] dimensions, int limit) Verifies the validity of a givendimensions
argument.- Parameters:
dimensions
- the user supplied argument to validate.limit
- maximal number of dimensions, exclusive.- Returns:
- a clone of the given array, or
null
if the caller can returnthis
.
-
reorder
Changes axis order or reduces the number of dimensions. It is caller responsibility to ensure that the given dimensions are valid. -
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:
-
forChunkSize
Returns a grid extent expanded by the minimal amount of cells needed for covering an integer amount of chunks. The grid coordinates (0, 0, …) locate the corner of a chunk.Number of arguments
Thesizes
array length should be equal to the number of dimensions. If the array is shorter, missing values default to 1. If the array is longer, extraneous values are ignored.- Parameters:
sizes
- number of cells in all tiles or chunks.- Returns:
- a grid extent expanded for the given chunk size.
- 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:
-
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: If the "real world" envelope computed from grid extent needs to stay approximately the same, then the grid to CRS transform needs to compensate the subsampling with a pre-multiplication of each grid coordinates byThis method does not reduce the number of dimensions of the grid extent. For dimensionality reduction, seeperiods
. However, the envelope computed that way 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.selectDimensions(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
if subsampling results in the same extent. - Throws:
IllegalArgumentException
- if a period is not greater than zero.- See Also:
-
upsample
Creates a new grid extent upsampled by the given amount of cells along each grid dimensions. This method multiplies low and high coordinates by the given periods. This method does not change the number of dimensions of the grid extent.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 upsampling. Length shall be equal to the number of dimension and all values shall be greater than zero.- Returns:
- the upsampled extent, or
this
if upsampling results in the same extent. - Throws:
IllegalArgumentException
- if a period is not greater than zero.ArithmeticException
- if the upsampled extent overflows thelong
capacity.- Since:
- 1.3
- See Also:
-
sliceByRatio
final GridExtent sliceByRatio(org.opengis.geometry.DirectPosition slicePoint, double sliceRatio, int[] dimensionsToKeep) Returns a slice of this grid extent computed by a ratio between 0 and 1 inclusive. This is a helper method forGridDerivation.sliceByRatio(double, int...)
implementation.- Parameters:
slicePoint
- a pre-allocated direct position to be overwritten by this method.sliceRatio
- the ratio to apply on all grid dimensions except the ones to keep.dimensionsToKeep
- the grid dimension to keep unchanged.
-
slice
Creates a new grid extent which represent a slice of this grid at the given point. The given point may have less dimensions than this grid extent, in which case the dimensions must be specified in themodifiedDimensions
array. Coordinates in the given point will be rounded to nearest integer.This method does not reduce the number of dimensions of the grid extent. For dimensionality reduction, see
selectDimensions(int[])
.- Parameters:
slicePoint
- where to take a slice. NaN values are handled as if their dimensions were absent.modifiedDimensions
- mapping fromslicePoint
dimensions to thisGridExtent
dimensions, ornull
ifslicePoint
contains all grid dimensions in same order.- Returns:
- a grid extent for the specified slice.
- Throws:
PointOutsideCoverageException
- if the given point is outside the grid extent.
-
cornerToCRS
final MatrixSIS cornerToCRS(org.opengis.geometry.Envelope env, long flippedAxes, int[] sourceDimensions) Creates an affine transform from the coordinates of this grid to the coordinates of the given envelope. This method assumes that all axes are in the same order (no axis swapping) and there is no flipping of axis direction except for those specified in theflips
bitmask. The transform maps cell corners.- Parameters:
env
- the target envelope. Despite this method name, the envelope CRS is ignored.flippedAxes
- bitmask of target axes to flip (0 if none).sourceDimensions
- source dimension for each target dimension, ornull
if dimensions are the same.- Returns:
- an affine transform from this grid extent to the given envelope, expressed as a matrix.
-
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
-
intersect
Returns the intersection of this grid extent with the given grid extent. The given extent shall have the same number of dimensions than this extent. The axis types (vertical, temporal, …) must be the same in all dimensions, ignoring types that are absent.- Parameters:
other
- the grid to intersect with.- Returns:
- the intersection result. May be one of the existing instances.
- Throws:
org.opengis.geometry.MismatchedDimensionException
- if the two extents do not have the same number of dimensions.IllegalArgumentException
- if axis types are specified but inconsistent in at least one dimension.DisjointExtentException
- if the given extent does not intersect this extent.- Since:
- 1.3
-
union
Returns the union of this grid extent with the given grid extent. The given extent shall have the same number of dimensions than this extent. The axis types (vertical, temporal, …) must be the same in all dimensions, ignoring types that are absent.- Parameters:
other
- the grid to combine with.- Returns:
- the union result. May be one of the existing instances.
- Throws:
org.opengis.geometry.MismatchedDimensionException
- if the two extents do not have the same number of dimensions.IllegalArgumentException
- if axis types are specified but inconsistent in at least one dimension.- Since:
- 1.3
-
combine
Implementation ofunion(GridExtent)
andintersect(GridExtent)
- Parameters:
other
- the grid to combine with.- Returns:
- the union or intersection result, or
null
if the intersection gave an empty result. - Throws:
org.opengis.geometry.MismatchedDimensionException
- if the two extents do not have the same number of dimensions.IllegalArgumentException
- if axis types are specified but inconsistent in at least one dimension.
-
extremum
private static long extremum(long a, long b, boolean max) Returns the minimum or maximum value between the given pair of values. -
isSameSize
Returns whether this grid extent has the same size than the given extent. If the given extent isnull
or has a different number of dimensions, then this method returnsfalse
.This method is not public because we do not yet have a policy about whether we should verify if axis
types
match.- Parameters:
other
- the other extent to compare with this extent. Can benull
.- Returns:
- whether the two extents has the same size.
-
equals
Compares the specified object with this grid extent 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 extent for equality.- Returns:
true
if the given object is equal to this grid extent.- See Also:
-
equals
Compares the specified object with this grid extent 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 extent for equality.mode
- the strictness level of the comparison.- Returns:
true
if the given object is equal to this grid extent.- Since:
- 1.1
- See Also:
-
hashCode
public int hashCode()Returns a hash value for this grid extent. This value needs not to remain consistent between different implementations of the same class. -
toString
Returns a string representation of this grid extent. The returned string is implementation dependent and is provided for debugging purposes only. -
appendTo
Writes a string representation of this grid extent in the given buffer. This method is provided for allowing caller to recycle the same buffer.- Parameters:
out
- where to write the string representation.vocabulary
- resources for some words.- Throws:
IOException
-
toSizeString
Returns a string representation of the given size, assumed computed byhigh - low + 1
. A value of 0 means that there is an overflow and that the true value os 264.
-
getPointOfInterest(PixelInCell)
.