Package org.apache.sis.geometry
Class ArrayEnvelope
java.lang.Object
org.apache.sis.io.wkt.FormattableObject
org.apache.sis.geometry.AbstractEnvelope
org.apache.sis.geometry.ArrayEnvelope
- All Implemented Interfaces:
Serializable
,Emptiable
,org.opengis.geometry.Envelope
- Direct Known Subclasses:
GeneralEnvelope
,ImmutableEnvelope
Base class of envelopes backed by an array. The coordinate values are stored in the
coordinates
array.
The coordinate values of the lower corner are stored in the array portion from index beginIndex()
inclusive to index endIndex()
exclusive. The coordinate values of the upper corner are stored in
the array portion from index beginIndex() + d
inclusive to index endIndex() + d
exclusive
where d = coordinates.length >>> 1
.
Unless otherwise indicated by a "// Must be overridden in SubEnvelope
" comment, every methods
in ArrayEnvelope
and subclasses must take in account the beginIndex
and endIndex
bounds. A few methods ignore the bounds for performance reason, so they need a dedicated implementation
in SubEnvelope
.
- Since:
- 0.3
- Version:
- 1.0
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) final double[]
Coordinate values of lower and upper corners.(package private) org.opengis.referencing.crs.CoordinateReferenceSystem
The coordinate reference system, ornull
.private static final long
Serial number for inter-operability with different versions. -
Constructor Summary
ConstructorsConstructorDescriptionArrayEnvelope
(double[] coordinates) Creates a new envelope using the given array of coordinate values.ArrayEnvelope
(double[] lowerCorner, double[] upperCorner) Constructs an envelope defined by two corners given as sequences of coordinate values.ArrayEnvelope
(int dimension) Constructs an empty envelope of the specified dimension.Constructs a new envelope initialized to the values parsed from the given string inBOX
or Well Known Text (WKT) format.ArrayEnvelope
(org.opengis.geometry.DirectPosition lowerCorner, org.opengis.geometry.DirectPosition upperCorner) Constructs an envelope defined by two corners given as direct positions.ArrayEnvelope
(org.opengis.geometry.Envelope envelope) Constructs a new envelope with the same data than the specified envelope.ArrayEnvelope
(org.opengis.metadata.extent.GeographicBoundingBox box) Constructs a new envelope with the same data than the specified geographic bounding box.ArrayEnvelope
(org.opengis.referencing.crs.CoordinateReferenceSystem crs) Constructs an empty envelope with the specified coordinate reference system. -
Method Summary
Modifier and TypeMethodDescription(package private) int
Returns the index of the first valid coordinate value of the lower corner in thecoordinates
array.(package private) int
endIndex()
Returns the index after the last valid coordinate value of the lower corner in thecoordinates
array.(package private) static void
ensureSameDimension
(int dim1, int dim2) Makes sure the specified dimensions are identical.boolean
Returnstrue
if the specified object is an envelope of the same class with equals coordinates and CRS.(package private) final boolean
equalsByAPI
(Object object) Compares the given object for equality using the public API instead of direct access to thecoordinates
array.private static void
fail
(CharSequence wkt, char missing) Throws an exception for unmatched parenthesis during WKT parsing.org.opengis.referencing.crs.CoordinateReferenceSystem
Returns the envelope coordinate reference system, ornull
if unknown.int
Returns the length of coordinate sequence (the number of entries) in this envelope.double
getLower
(int dimension) Returns the limit in the direction of decreasing coordinate values in the specified dimension.double
getMaximum
(int dimension) Returns the maximal coordinate value for the specified dimension.double
getMedian
(int dimension) Returns the median coordinate along the specified dimension.double
getMinimum
(int dimension) Returns the minimal coordinate value for the specified dimension.double
getSpan
(int dimension) Returns the envelope span (typically width or height) along the specified dimension.double
getUpper
(int dimension) Returns the limit in the direction of increasing coordinate values in the specified dimension.int
hashCode()
Returns a hash value for this envelope.(package private) final int
Computes the hash code value using the public API instead of direct access to thecoordinates
array.(package private) static String
illegalRange
(org.opengis.referencing.crs.CoordinateReferenceSystem crs, int dimension, double lower, double upper) Creates an error message for an illegal coordinates range at the given dimension.boolean
isAllNaN()
Returnsfalse
if at least one coordinate value is not NaN.boolean
isEmpty()
Determines whether or not this envelope is empty.toString()
Formats this envelope as a "BOX
" element.(package private) static void
verifyRanges
(org.opengis.referencing.crs.CoordinateReferenceSystem crs, double[] coordinates) Verifies the validity of the range of coordinates values in the given array.Methods inherited from class org.apache.sis.geometry.AbstractEnvelope
assertEquals, castOrCopy, contains, contains, contains, equals, fixMedian, fixSpan, formatTo, getAxis, getCommonCRS, getCycle, getLowerCorner, getMedian, getSpan, getTimeRange, getUpperCorner, hasNaN, hasNaN, intersects, intersects, isNegativeUnsafe, isWrapAround, isWrapAround, setRange, toSimpleEnvelopes, toString
Methods inherited from class org.apache.sis.io.wkt.FormattableObject
print, toString, toWKT
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
coordinates
final double[] coordinatesCoordinate values of lower and upper corners. Except forSubEnvelope
, the length of this array is twice the number of dimensions. The first half contains the lower corner, while the second half contains the upper corner. -
crs
org.opengis.referencing.crs.CoordinateReferenceSystem crsThe coordinate reference system, ornull
.
-
-
Constructor Details
-
ArrayEnvelope
ArrayEnvelope(double[] coordinates) Creates a new envelope using the given array of coordinate values. This constructor stores the given reference directly; it does not clone the given array. This is the desired behavior for proper working ofSubEnvelope
.- Parameters:
coordinates
- the array of coordinate values to store directly (not cloned).
-
ArrayEnvelope
public ArrayEnvelope(org.opengis.geometry.DirectPosition lowerCorner, org.opengis.geometry.DirectPosition upperCorner) throws org.opengis.geometry.MismatchedDimensionException, MismatchedReferenceSystemException Constructs an envelope defined by two corners given as direct positions. If at least one corner is associated to a CRS, then the new envelope will also be associated to that CRS.- Parameters:
lowerCorner
- the limits in the direction of decreasing coordinate values for each dimension.upperCorner
- the limits in the direction of increasing coordinate values for each dimension.- Throws:
org.opengis.geometry.MismatchedDimensionException
- if the two positions do not have the same dimension.MismatchedReferenceSystemException
- if the CRS of the two position are not equal.
-
ArrayEnvelope
public ArrayEnvelope(double[] lowerCorner, double[] upperCorner) throws org.opengis.geometry.MismatchedDimensionException Constructs an envelope defined by two corners given as sequences of coordinate values. The Coordinate Reference System is initiallynull
.- Parameters:
lowerCorner
- the limits in the direction of decreasing coordinate values for each dimension.upperCorner
- the limits in the direction of increasing coordinate values for each dimension.- Throws:
org.opengis.geometry.MismatchedDimensionException
- if the two sequences do not have the same length.
-
ArrayEnvelope
public ArrayEnvelope(int dimension) Constructs an empty envelope of the specified dimension. All coordinates are initialized to 0 and the coordinate reference system is undefined.- Parameters:
dimension
- the envelope dimension.
-
ArrayEnvelope
public ArrayEnvelope(org.opengis.referencing.crs.CoordinateReferenceSystem crs) Constructs an empty envelope with the specified coordinate reference system. All coordinate values are initialized to 0.- Parameters:
crs
- the coordinate reference system.
-
ArrayEnvelope
public ArrayEnvelope(org.opengis.geometry.Envelope envelope) Constructs a new envelope with the same data than the specified envelope.- Parameters:
envelope
- the envelope to copy.
-
ArrayEnvelope
public ArrayEnvelope(org.opengis.metadata.extent.GeographicBoundingBox box) Constructs a new envelope with the same data than the specified geographic bounding box. The coordinate reference system is set to the default geographic CRS. Axis order is (longitude, latitude).- Parameters:
box
- the bounding box to copy.
-
ArrayEnvelope
Constructs a new envelope initialized to the values parsed from the given string inBOX
or Well Known Text (WKT) format. The given string is typically aBOX
element like below: However, this constructor is lenient to other geometry types likePOLYGON
. See the javadoc of theGeneralEnvelope
constructor for more information.- Parameters:
wkt
- theBOX
,POLYGON
or other kind of element to parse.- Throws:
IllegalArgumentException
- if the given string cannot be parsed.
-
-
Method Details
-
fail
Throws an exception for unmatched parenthesis during WKT parsing. -
ensureSameDimension
static void ensureSameDimension(int dim1, int dim2) throws org.opengis.geometry.MismatchedDimensionException Makes sure the specified dimensions are identical.- Throws:
org.opengis.geometry.MismatchedDimensionException
-
verifyRanges
static void verifyRanges(org.opengis.referencing.crs.CoordinateReferenceSystem crs, double[] coordinates) Verifies the validity of the range of coordinates values in the given array. If the given CRS is null, then this method conservatively does nothing. Otherwise this method performs the following verifications:lower > upper
is allowed only for axes havingRangeMeaning.WRAPAROUND
.
add(…)
,intersect(…)
,contains(…)
and similar methods. This in contrast with the checks listed above, where failure to met those conditions will cause the methods to behave in an unexpected way.Implementation consistency
The checks performed by this method shall be consistent with the checks performed by the following methods:- Parameters:
crs
- the coordinate reference system, ornull
.coordinates
- the array of coordinate values to verify.
-
illegalRange
static String illegalRange(org.opengis.referencing.crs.CoordinateReferenceSystem crs, int dimension, double lower, double upper) Creates an error message for an illegal coordinates range at the given dimension. This is used for formatting the exception message. -
beginIndex
int beginIndex()Returns the index of the first valid coordinate value of the lower corner in thecoordinates
array. This is always 0, unless this envelope is aSubEnvelope
.See
endIndex()
for the list of methods that need to be also overridden if thisbeginIndex()
method is overridden. -
endIndex
int endIndex()Returns the index after the last valid coordinate value of the lower corner in thecoordinates
array. This is alwayscoordinates.length >>> 1
, unless this envelope is aSubEnvelope
.Unless otherwise indicated by a "
// Must be overridden in SubEnvelope
" comment, every methods inArrayEnvelope
and subclasses must take in account thebeginIndex
andendIndex
bounds. The methods listed below ignore the bounds for performance reason, so they need to be overridden inSubEnvelope
: -
getDimension
public int getDimension()Returns the length of coordinate sequence (the number of entries) in this envelope. This information is available even when the coordinate reference system is unknown.- Specified by:
getDimension
in interfaceorg.opengis.geometry.Envelope
- Returns:
- the dimensionality of this envelope.
-
getCoordinateReferenceSystem
public org.opengis.referencing.crs.CoordinateReferenceSystem getCoordinateReferenceSystem()Returns the envelope coordinate reference system, ornull
if unknown. If non-null, it shall be the same as lower corner and upper corner CRS.- Specified by:
getCoordinateReferenceSystem
in interfaceorg.opengis.geometry.Envelope
- Returns:
- the envelope CRS, or
null
if unknown.
-
getLower
Returns the limit in the direction of decreasing coordinate values in the specified dimension. This is usually the algebraic minimum, except if this envelope spans the anti-meridian.- Specified by:
getLower
in classAbstractEnvelope
- Parameters:
dimension
- the dimension for which to obtain the coordinate value.- Returns:
- the starting coordinate value at the given dimension.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equal or greater than the envelope dimension.- See Also:
-
getUpper
Returns the limit in the direction of increasing coordinate values in the specified dimension. This is usually the algebraic maximum, except if this envelope spans the anti-meridian.- Specified by:
getUpper
in classAbstractEnvelope
- Parameters:
dimension
- the dimension for which to obtain the coordinate value.- Returns:
- the starting coordinate value at the given dimension.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equal or greater than the envelope dimension.- See Also:
-
getMinimum
Returns the minimal coordinate value for the specified dimension. In the typical case of non-empty envelopes not crossing the anti-meridian, this method returns theAbstractEnvelope.getLower(int)
value verbatim. In the case of envelope crossing the anti-meridian, this method returns the axis minimum value. If the range in the given dimension is invalid, then this method returnsNaN
.- Specified by:
getMinimum
in interfaceorg.opengis.geometry.Envelope
- Overrides:
getMinimum
in classAbstractEnvelope
- Parameters:
dimension
- the dimension for which to obtain the coordinate value.- Returns:
- the minimal coordinate value at the given dimension.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equal or greater than the envelope dimension.
-
getMaximum
Returns the maximal coordinate value for the specified dimension. In the typical case of non-empty envelopes not crossing the anti-meridian, this method returns theAbstractEnvelope.getUpper(int)
value verbatim. In the case of envelope crossing the anti-meridian, this method returns the axis maximum value. If the range in the given dimension is invalid, then this method returnsNaN
.- Specified by:
getMaximum
in interfaceorg.opengis.geometry.Envelope
- Overrides:
getMaximum
in classAbstractEnvelope
- Parameters:
dimension
- the dimension for which to obtain the coordinate value.- Returns:
- the maximal coordinate value at the given dimension.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equal or greater than the envelope dimension.
-
getMedian
Returns the median coordinate along the specified dimension. In most cases, the result is equal (minus rounding error) to:Crossing the anti-meridian of a Geographic CRS
If upper < lower and the range meaning for the requested dimension is wraparound, then the median calculated above is actually in the middle of the space outside the envelope. In such cases, this method shifts the median value by half of the periodicity (180° in the longitude case) in order to switch from outer space to inner space. If the axis range meaning is notWRAPAROUND
, then this method returnsNaN
.- Specified by:
getMedian
in interfaceorg.opengis.geometry.Envelope
- Overrides:
getMedian
in classAbstractEnvelope
- Parameters:
dimension
- the dimension for which to obtain the coordinate value.- Returns:
- the median coordinate at the given dimension, or
Double.NaN
. - Throws:
IndexOutOfBoundsException
- if the given index is negative or is equal or greater than the envelope dimension.- See Also:
-
getSpan
Returns the envelope span (typically width or height) along the specified dimension. In most cases, the result is equal (minus rounding error) to:Crossing the anti-meridian of a Geographic CRS
If upper < lower and the range meaning for the requested dimension is wraparound, then the span calculated above is negative. In such cases, this method adds the periodicity (typically 360° of longitude) to the span. If the result is a positive number, it is returned. Otherwise this method returnsNaN
.- Specified by:
getSpan
in interfaceorg.opengis.geometry.Envelope
- Overrides:
getSpan
in classAbstractEnvelope
- Parameters:
dimension
- the dimension for which to obtain the span.- Returns:
- the span (typically width or height) at the given dimension, or
Double.NaN
. - Throws:
IndexOutOfBoundsException
- if the given index is negative or is equal or greater than the envelope dimension.
-
isEmpty
public boolean isEmpty()Determines whether or not this envelope is empty. An envelope is empty if it has zero dimension, or if the span of at least one axis is negative, 0 orNaN
.Note: Strictly speaking, there is an ambiguity if a span isIfNaN
or if the envelope contains both 0 and infinite spans (since 0⋅∞ =NaN
). In such cases, this method arbitrarily ignores the infinite values and returnstrue
.isEmpty()
returnsfalse
, thenAbstractEnvelope.isAllNaN()
is guaranteed to also returnfalse
. However, the converse is not always true.- Specified by:
isEmpty
in interfaceEmptiable
- Overrides:
isEmpty
in classAbstractEnvelope
- Returns:
true
if this envelope is empty.- See Also:
-
isAllNaN
public boolean isAllNaN()Returnsfalse
if at least one coordinate value is not NaN. ThisisAllNaN()
check is different than theAbstractEnvelope.isEmpty()
check since it returnsfalse
for a partially initialized envelope, whileisEmpty()
returnsfalse
only after all dimensions have been initialized. More specifically, the following rules apply:- If
isAllNaN() == true
, thenisEmpty() == true
- If
isEmpty() == false
, thenisAllNaN() == false
- The converse of the above-cited rules are not always true.
- Overrides:
isAllNaN
in classAbstractEnvelope
- Returns:
true
if this envelope has NaN values.- See Also:
- If
-
hashCode
public int hashCode()Returns a hash value for this envelope.- Overrides:
hashCode
in classAbstractEnvelope
-
hashCodeByAPI
final int hashCodeByAPI()Computes the hash code value using the public API instead of direct access to thecoordinates
array. This method is invoked fromSubEnvelope
. -
equals
Returnstrue
if the specified object is an envelope of the same class with equals coordinates and CRS.Implementation note: This implementation requires that the providedobject
argument is of the same class than this envelope. We do not relax this rule since not every implementations in the SIS code base follow the same contract.- Overrides:
equals
in classAbstractEnvelope
- Parameters:
object
- the object to compare with this envelope.- Returns:
true
if the given object is equal to this envelope.
-
equalsByAPI
Compares the given object for equality using the public API instead of direct access to thecoordinates
array. This method is invoked fromSubEnvelope
. -
toString
Formats this envelope as a "BOX
" element. The output is of the form "BOX
nD(
lower corner,
upper corner)
" where n is the number of dimensions. The number of dimension is written only if different than 2.Example:BOX(-90 -180, 90 180)
BOX3D(-90 -180 0, 90 180 1)
Note: TheThis method formats the numbers as withBOX
element is not part of the standard Well Known Text (WKT) format. However, it is understood by many software libraries, for example GDAL and PostGIS.Double.toString(double)
(i.e. without fixed number of fraction digits). The string returned by this method can be parsed by theGeneralEnvelope
constructor.- Overrides:
toString
in classAbstractEnvelope
- Returns:
- this envelope as a
BOX
orBOX3D
(most typical dimensions) element.
-