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.
Note:This particular implementation ofEnvelope
uses an arbitrary Coordinate Reference System, which doesn't need to be geographic. This is different than theGeographicBoundingBox
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: |
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, equals, getLowerCorner, getMedian, getSpan, getUpperCorner, intersects
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)
"CRS:84"
.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.
The following examples can be parsed by this constructor in addition of the usual
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.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.public void setEnvelope(double... corners)
Example:
(xmin, ymin, zmin, xmax, ymax, zmax)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.
Note: This method assumes that the specified point uses the same CRS than this envelope. For performance raisons, it will no be verified unless Java assertions are enabled.
+
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.
Note: This method assumes that the specified envelope uses the same CRS than this envelope. For performance raisons, it will no be verified unless Java assertions are enabled.
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
Note: This method assumes that the specified envelope uses the same CRS than this envelope. For performance raisons, it will no be verified unless Java assertions are enabled.
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.public boolean simplify() throws IllegalStateException
RangeMeaning.WRAPAROUND
, then the lower ordinate value is
set to the axis minimum value
and the upper ordinate value is set to the
axis maimum value.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.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()
AbstractEnvelope.isAllNaN()
always returns
false
for a non-empty envelope, but the converse is not always true.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 a little bit 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.
Note:
This implementation requires that the provided 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.
Example:
BOX(-90 -180, 90 180) BOX3D(-90 -180 0, 90 180 1)
Note:
The 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.
The string returned by this method can be parsed
by the GeneralEnvelope
constructor.toString
in class AbstractEnvelope
BOX
or BOX3D
(most typical dimensions) element.Copyright © 2010–2013 The Apache Software Foundation. All rights reserved.