public class GeneralEnvelope extends AbstractEnvelope implements Cloneable, Serializable
Envelope
can
be represented without ambiguity as two direct positions
(coordinate points). To encode an Envelope
, it is sufficient to encode these
two points.
Envelope
uses an arbitrary Coordinate Reference System, which does not need to be geographic.
This is different than the GeographicBoundingBox
class provided in the metadata package, which can be used
as a kind of envelope restricted to a Geographic CRS having Greenwich prime meridian.Envelope
is said "General" because it uses
coordinates of an arbitrary number of dimensions. This is in contrast with
Envelope2D
, which can use only two-dimensional coordinates.
A GeneralEnvelope
can be created in various ways:
BBOX
or a Well Known Text (WKT) format.
![]() | Supported methods: |
this.getDimension()
.getLower(i) > getUpper(i)
is allowed
only if the coordinate
system axis range meaning is WRAPAROUND
.add(…)
, intersect(…)
, contains(…)
and similar methods.
This in contrast with the lower > upper
case, which cause the above-cited methods to behave in
an unexpected way if the axis does not have wraparound range meaning.Envelope2D
,
DefaultGeographicBoundingBox
,
Serialized FormDefined in the sis-referencing
module
Constructor and Description |
---|
GeneralEnvelope(CharSequence wkt)
Constructs a new envelope initialized to the values parsed from the given string in
BOX or Well Known Text (WKT) format. |
GeneralEnvelope(CoordinateReferenceSystem crs)
Constructs an empty envelope with the specified coordinate reference system.
|
GeneralEnvelope(DirectPosition lowerCorner,
DirectPosition upperCorner)
Constructs an envelope defined by two corners given as direct positions.
|
GeneralEnvelope(double[] lowerCorner,
double[] upperCorner)
Constructs an envelope defined by two corners given as sequences of ordinate values.
|
GeneralEnvelope(Envelope envelope)
Constructs a new envelope with the same data than the specified envelope.
|
GeneralEnvelope(GeographicBoundingBox box)
Constructs a new envelope with the same data than the specified geographic bounding box.
|
GeneralEnvelope(int dimension)
Constructs an empty envelope of the specified dimension.
|
Modifier and Type | Method and Description |
---|---|
void |
add(DirectPosition position)
Adds a point to this envelope.
|
void |
add(Envelope envelope)
Adds an envelope object to this envelope.
|
static GeneralEnvelope |
castOrCopy(Envelope envelope)
Returns the given envelope as a
GeneralEnvelope instance. |
GeneralEnvelope |
clone()
Returns a deep copy of this envelope.
|
boolean |
equals(Object object)
Returns
true if the specified object is an envelope of the same class
with equals coordinates and CRS. |
CoordinateReferenceSystem |
getCoordinateReferenceSystem()
Returns the envelope coordinate reference system, or
null if unknown. |
int |
getDimension()
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 ordinate values in the specified dimension.
|
double |
getMaximum(int dimension)
Returns the maximal ordinate value for the specified dimension.
|
double |
getMedian(int dimension)
Returns the median ordinate along the specified dimension.
|
double |
getMinimum(int dimension)
Returns the minimal ordinate 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 ordinate values in the specified dimension.
|
int |
hashCode()
Returns a hash value for this envelope.
|
void |
intersect(Envelope envelope)
Sets this envelope to the intersection if this envelope with the specified one.
|
boolean |
isAllNaN()
Returns
false if at least one ordinate value is not NaN. |
boolean |
isEmpty()
Determines whether or not this envelope is empty.
|
boolean |
normalize()
Ensures that the envelope is contained in the coordinate system domain.
|
void |
setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
Sets the coordinate reference system in which the coordinate are given.
|
void |
setEnvelope(double... corners)
Sets the envelope to the specified values, which must be the lower corner coordinates
followed by upper corner coordinates.
|
void |
setEnvelope(Envelope envelope)
Sets this envelope to the same coordinate values than the specified envelope.
|
void |
setRange(int dimension,
double lower,
double upper)
Sets the envelope range along the specified dimension.
|
void |
setToInfinite()
Sets the lower corner to negative infinity
and the upper corner to positive infinity.
|
void |
setToNaN()
Sets all ordinate values to NaN.
|
boolean |
simplify()
Ensures that lower <= upper for every dimensions.
|
GeneralEnvelope |
subEnvelope(int beginIndex,
int endIndex)
Returns a view over this envelope that encompass only some dimensions.
|
String |
toString()
Formats this envelope as a "
BOX " element. |
contains, contains, contains, equals, getLowerCorner, getMedian, getSpan, getUpperCorner, intersects, intersects, toSimpleEnvelopes
public GeneralEnvelope(DirectPosition lowerCorner, DirectPosition upperCorner) throws MismatchedDimensionException, MismatchedReferenceSystemException
lowerCorner
- The limits in the direction of decreasing ordinate values for each dimension.upperCorner
- The limits in the direction of increasing ordinate values for each dimension.MismatchedDimensionException
- If the two positions do not have the same dimension.MismatchedReferenceSystemException
- If the CRS of the two position are not equal.public GeneralEnvelope(double[] lowerCorner, double[] upperCorner) throws MismatchedDimensionException
null
.lowerCorner
- The limits in the direction of decreasing ordinate values for each dimension.upperCorner
- The limits in the direction of increasing ordinate values for each dimension.MismatchedDimensionException
- If the two sequences do not have the same length.public GeneralEnvelope(int dimension)
dimension
- The envelope dimension.public GeneralEnvelope(CoordinateReferenceSystem crs)
crs
- The coordinate reference system.public GeneralEnvelope(Envelope envelope)
envelope
- The envelope to copy.castOrCopy(Envelope)
public GeneralEnvelope(GeographicBoundingBox box)
box
- The bounding box to copy.public GeneralEnvelope(CharSequence wkt) throws IllegalArgumentException
BOX
or Well Known Text (WKT) format. The given string is typically
a BOX
element like below:
However this constructor is lenient to other geometry types likeBOX(-180 -90, 180 90)
POLYGON
.
Actually this constructor ignores the geometry type and just applies the following
simple rules:
,
) character.LINESTRING
have the same dimension. However this
constructor ensures that the parenthesis are balanced, in order to catch some malformed WKT.
BOX
element.
This constructor creates the bounding box of those geometries:
POINT(6 10)
MULTIPOLYGON(((1 1, 5 1, 1 5, 1 1),(2 2, 3 2, 3 3, 2 2)))
GEOMETRYCOLLECTION(POINT(4 6),LINESTRING(3 8,7 10))
wkt
- The BOX
, POLYGON
or other kind of element to parse.IllegalArgumentException
- If the given string can not be parsed.Envelopes.fromWKT(CharSequence)
,
Envelopes.toString(Envelope)
public static GeneralEnvelope castOrCopy(Envelope envelope)
GeneralEnvelope
instance. If the given envelope
is already an instance of GeneralEnvelope
, then it is returned unchanged.
Otherwise the coordinate values and the CRS of the given envelope are
copied in a new GeneralEnvelope
.envelope
- The envelope to cast, or null
.GeneralEnvelope
instance.AbstractEnvelope.castOrCopy(Envelope)
,
ImmutableEnvelope.castOrCopy(Envelope)
public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs) throws MismatchedDimensionException
If the envelope coordinates need to be transformed to the new CRS, consider
using Envelopes#transform(Envelope, CoordinateReferenceSystem)
instead.
crs
- The new coordinate reference system, or null
.MismatchedDimensionException
- if the specified CRS doesn't have the expected number of dimensions.IllegalStateException
- if a range of ordinate values in this envelope is compatible with the given CRS.
See Envelope validation in class javadoc for more details.public void setRange(int dimension, double lower, double upper) throws IndexOutOfBoundsException
dimension
- The dimension to set.lower
- The limit in the direction of decreasing ordinate values.upper
- The limit in the direction of increasing ordinate values.IndexOutOfBoundsException
- If the given index is out of bounds.IllegalArgumentException
- If lower > upper
and the axis range meaning at the given dimension
is not "wraparound". See Envelope validation in class javadoc for more details.public void setEnvelope(double... corners)
corners
- Ordinates of the new lower corner followed by the new upper corner.public void setEnvelope(Envelope envelope) throws MismatchedDimensionException
envelope
- The envelope to copy coordinates from.MismatchedDimensionException
- if the specified envelope doesn't have
the expected number of dimensions.public void setToInfinite()
public void setToNaN()
isAllNaN()
public void add(DirectPosition position) throws MismatchedDimensionException
After adding a point, a call to contains(DirectPosition)
with the added point as an argument will return true
, except if one of the point
ordinates was Double.NaN
in which case the corresponding ordinate has been ignored.
+
symbol):
The default implementation moves only the border which is closest to the given point.─────┐ + ┌───── ─────┘ └─────
position
- The point to add.MismatchedDimensionException
- if the specified point doesn't have the expected dimension.AssertionError
- If assertions are enabled and the envelopes have mismatched CRS.public void add(Envelope envelope) throws MismatchedDimensionException
Envelope
objects.
add
operation may be an envelope expanding
to infinities. In such case, the ordinate range will be either [-∞…∞] or [0…-0] depending on
whatever the original range span the anti-meridian or not.envelope
- the Envelope
to add to this envelope.MismatchedDimensionException
- if the specified envelope doesn't
have the expected dimension.AssertionError
- If assertions are enabled and the envelopes have mismatched CRS.public void intersect(Envelope envelope) throws MismatchedDimensionException
envelope
- the Envelope
to intersect to this envelope.MismatchedDimensionException
- if the specified envelope doesn't
have the expected dimension.AssertionError
- If assertions are enabled and the envelopes have mismatched CRS.public boolean normalize()
RangeMeaning.EXACT
(typically latitudes ordinates), then values
greater than the axis maximal value
are replaced by the axis maximum, and values smaller than the
axis minimal value
are replaced by the axis minimum.RangeMeaning.WRAPAROUND
(typically longitudes ordinates), then
a multiple of the axis range (e.g. 360° for longitudes) is added or subtracted.
Example:
simplify()
as below:
if (envelope.normalize()) { envelope.simplify(); }
Double.NaN
numbers when
given an ordinate value out of bounds.true
if this envelope has been modified as a result of this method call,
or false
if no change has been done.AbstractDirectPosition.normalize()
public boolean simplify() throws IllegalStateException
RangeMeaning.WRAPAROUND
, then:IllegalStateException
is thrown.true
if this envelope has been modified as a result of this method call,
or false
if no change has been done.IllegalStateException
- If a upper ordinate value is less than a lower ordinate
value on an axis which does not have the WRAPAROUND
range meaning.AbstractEnvelope.toSimpleEnvelopes()
public GeneralEnvelope subEnvelope(int beginIndex, int endIndex) throws IndexOutOfBoundsException
This method is useful for querying and updating only some dimensions. For example in order to expand only the horizontal component of a four dimensional (x,y,z,t) envelope, one can use:
If the sub-envelope needs to be independent from the original envelope, use the following idiom:envelope.subEnvelope(0, 2).add(myPosition2D);
The sub-envelope is initialized with aGeneralEnvelope copy = envelope.subEnvelope(0, 2).clone();
null
CRS.
This method does not compute a sub-CRS because it may not be needed, or the sub-CRS may be already
known by the caller.beginIndex
- The index of the first valid ordinate value of the corners.endIndex
- The index after the last valid ordinate value of the corners.endIndex - beginIndex
.IndexOutOfBoundsException
- If an index is out of bounds.public GeneralEnvelope clone()
public int getDimension()
getDimension
in interface Envelope
public CoordinateReferenceSystem getCoordinateReferenceSystem()
null
if unknown.
If non-null, it shall be the same as lower corner
and upper corner CRS.getCoordinateReferenceSystem
in interface Envelope
null
if unknown.public double getLower(int dimension) throws IndexOutOfBoundsException
getLower
in class AbstractEnvelope
dimension
- The dimension for which to obtain the ordinate value.IndexOutOfBoundsException
- If the given index is negative or is equals or greater
than the envelope dimension.public double getUpper(int dimension) throws IndexOutOfBoundsException
getUpper
in class AbstractEnvelope
dimension
- The dimension for which to obtain the ordinate value.IndexOutOfBoundsException
- If the given index is negative or is equals or greater
than the envelope dimension.public double getMinimum(int dimension) throws IndexOutOfBoundsException
AbstractEnvelope.getLower(int)
value verbatim. In the case of envelope spanning the anti-meridian,
this method returns the axis minimum value.getMinimum
in interface Envelope
getMinimum
in class AbstractEnvelope
dimension
- The dimension for which to obtain the ordinate value.IndexOutOfBoundsException
- If the given index is negative or is equals or greater
than the envelope dimension.public double getMaximum(int dimension) throws IndexOutOfBoundsException
AbstractEnvelope.getUpper(int)
value verbatim. In the case of envelope spanning the anti-meridian,
this method returns the axis maximum value.getMaximum
in interface Envelope
getMaximum
in class AbstractEnvelope
dimension
- The dimension for which to obtain the ordinate value.IndexOutOfBoundsException
- If the given index is negative or is equals or greater
than the envelope dimension.public double getMedian(int dimension) throws IndexOutOfBoundsException
median = (getUpper(dimension) + getLower(dimension)) / 2;
WRAPAROUND
, then this method returns
NaN
.getMedian
in interface Envelope
getMedian
in class AbstractEnvelope
dimension
- The dimension for which to obtain the ordinate value.Double.NaN
.IndexOutOfBoundsException
- If the given index is negative or is equals or greater
than the envelope dimension.public double getSpan(int dimension) throws IndexOutOfBoundsException
span = getUpper(dimension) - getLower(dimension);
NaN
.getSpan
in interface Envelope
getSpan
in class AbstractEnvelope
dimension
- The dimension for which to obtain the span.Double.NaN
.IndexOutOfBoundsException
- If the given index is negative or is equals or greater
than the envelope dimension.public boolean isEmpty()
NaN
.
NaN
or if the envelope contains
both 0 and infinite spans (since 0⋅∞ = NaN
). In such cases, this method arbitrarily
ignores the infinite values and returns true
.isEmpty()
returns false
, then AbstractEnvelope.isAllNaN()
is guaranteed to
also return false
. However the converse is not always true.isEmpty
in interface Emptiable
isEmpty
in class AbstractEnvelope
true
if this envelope is empty.DefaultGeographicBoundingBox.isEmpty()
,
RectangularShape.isEmpty()
public boolean isAllNaN()
false
if at least one ordinate value is not NaN.
This isAllNaN()
check is different than the AbstractEnvelope.isEmpty()
check since it
returns false
for a partially initialized envelope, while isEmpty()
returns false
only after all dimensions have been initialized.
More specifically, the following rules apply:
isAllNaN() == true
, then isEmpty() == true
isEmpty() == false
, then isAllNaN() == false
isAllNaN
in class AbstractEnvelope
true
if this envelope has NaN values.setToNaN()
,
DefaultGeographicBoundingBox.isEmpty()
public int hashCode()
hashCode
in class AbstractEnvelope
public boolean equals(Object object)
true
if the specified object is an envelope of the same class
with equals coordinates and CRS.
object
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.equals
in class AbstractEnvelope
object
- The object to compare with this envelope.true
if the given object is equal to this envelope.public String toString()
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.
BOX(-90 -180, 90 180)
BOX3D(-90 -180 0, 90 180 1)
BOX
element is not part of the standard Well Known Text (WKT) format.
However it is understood by many softwares, for example GDAL and PostGIS.GeneralEnvelope
constructor.toString
in class AbstractEnvelope
BOX
or BOX3D
(most typical dimensions) element.Copyright © 2010–2014 The Apache Software Foundation. All rights reserved.