public class GeneralEnvelope extends AbstractEnvelope implements Cloneable, Serializable
Envelope
(a minimum bounding box or rectangle) of arbitrary dimension.
Regardless of dimension, an 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 twodimensional 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 abovecited methods to behave in
an unexpected way if the axis does not have wraparound range meaning.Envelope2D
,
DefaultGeographicBoundingBox
,
Serialized FormDefined in the sisreferencing
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. 
void 
translate(double... vector)
Translates the envelope by the given vector.

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:
BOX(180 90, 180 90)However this constructor is lenient to other geometry types like
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 translate(double... vector)
vector[i]
.
This method does not check if the translation result is inside the coordinate system domain
(e.g. [180 … +180]° of longitude). Callers can normalize the envelope when desired by call to
the normalize()
method.
vector
 the translation vector. The length of this array shall be equal to this envelope
dimension.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 given point does not have the expected number of dimensions.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 antimeridian or not.envelope
 the Envelope
to add to this envelope.MismatchedDimensionException
 if the given envelope does not have the expected number of dimensions.AssertionError
 if assertions are enabled and the envelopes have mismatched CRS.DefaultGeographicBoundingBox.add(GeographicBoundingBox)
public void intersect(Envelope envelope) throws MismatchedDimensionException
envelope
 the Envelope
to intersect to this envelope.MismatchedDimensionException
 if the given envelope does not have the expected number of dimensions.AssertionError
 if assertions are enabled and the envelopes have mismatched CRS.DefaultGeographicBoundingBox.intersect(GeographicBoundingBox)
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:
envelope.subEnvelope(0, 2).add(myPosition2D);If the subenvelope needs to be independent from the original envelope, use the following idiom:
GeneralEnvelope copy = envelope.subEnvelope(0, 2).clone();The subenvelope is initialized with a
null
CRS.
This method does not compute a subCRS because it may not be needed, or the subCRS 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.CRS.getComponentAt(CoordinateReferenceSystem, int, int)
public GeneralEnvelope clone()
public int getDimension()
getDimension
in interface Envelope
public CoordinateReferenceSystem getCoordinateReferenceSystem()
null
if unknown.
If nonnull, 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 antimeridian,
this method returns the axis minimum value.
If the range in the given dimension is invalid, then this method returns NaN
.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 antimeridian,
this method returns the axis maximum value.
If the range in the given dimension is invalid, then this method returns NaN
.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 software libraries, for example GDAL and PostGIS.GeneralEnvelope
constructor.toString
in class AbstractEnvelope
BOX
or BOX3D
(most typical dimensions) element.Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.