public abstract class AbstractEnvelope extends Object implements Envelope
Envelope
implementations.
This base class does not hold any state and does not implement the Serializable
or Cloneable
interfaces. The internal representation, and the choice to be cloneable or
serializable, is left to subclasses.
Implementors needs to define at least the following methods:
All other methods, including toString()
, equals(Object)
and hashCode()
,
are implemented on top of the above four methods.
![]() | Supported methods: |
Defined in the sis-referencing module
Modifier | Constructor and Description |
---|---|
protected |
AbstractEnvelope()
Constructs an envelope.
|
Modifier and Type | Method and Description |
---|---|
static AbstractEnvelope |
castOrCopy(Envelope envelope)
Returns the given envelope as an
AbstractEnvelope instance. |
boolean |
contains(DirectPosition position)
Tests if a specified coordinate is inside the boundary of this envelope.
|
boolean |
contains(Envelope envelope,
boolean edgesInclusive)
Returns
true if this envelope completely encloses the specified envelope. |
boolean |
equals(Envelope other,
double eps,
boolean epsIsRelative)
Compares to the specified envelope for equality up to the specified tolerance value.
|
boolean |
equals(Object object)
Returns
true if the specified object is an envelope of the same class
with equals coordinates and CRS. |
abstract double |
getLower(int dimension)
Returns the limit in the direction of decreasing ordinate values in the specified dimension.
|
DirectPosition |
getLowerCorner()
A coordinate position consisting of all the lower ordinate values.
|
double |
getMaximum(int dimension)
Returns the maximal ordinate value for the specified dimension.
|
DirectPosition |
getMedian()
A coordinate position consisting of all the median ordinate values.
|
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 |
getSpan(int dimension,
Unit<?> unit)
Returns the envelope span along the specified dimension, in terms of the given units.
|
abstract double |
getUpper(int dimension)
Returns the limit in the direction of increasing ordinate values in the specified dimension.
|
DirectPosition |
getUpperCorner()
A coordinate position consisting of all the upper ordinate values.
|
int |
hashCode()
Returns a hash value for this envelope.
|
boolean |
intersects(Envelope envelope,
boolean edgesInclusive)
Returns
true if this envelope intersects the specified envelope. |
boolean |
isAllNaN()
Returns
false if at least one ordinate value is not NaN. |
boolean |
isEmpty()
Determines whether or not this envelope is empty.
|
String |
toString()
Formats this envelope as a "
BOX " element. |
getCoordinateReferenceSystem, getDimension
public static AbstractEnvelope castOrCopy(Envelope envelope)
AbstractEnvelope
instance.
If the given envelope is already an instance of AbstractEnvelope
,
then it is returned unchanged. Otherwise the coordinate values and the CRS
of the given envelope are copied in a new envelope.envelope
- The envelope to cast, or null
.AbstractEnvelope
instance.GeneralEnvelope.castOrCopy(Envelope)
,
ImmutableEnvelope.castOrCopy(Envelope)
public DirectPosition getLowerCorner()
getLower(int)
method,
so changes in this envelope will be immediately reflected in the returned direct position.
If the particular case of the GeneralEnvelope
subclass, the returned position
supports also write operations,
so changes in the position are reflected back in the envelope.
Note:
The Web Coverage Service (WCS) 1.1 specification uses an extended
interpretation of the bounding box definition. In a WCS 1.1 data structure, the lower
corner defines the edges region in the directions of decreasing coordinate
values in the envelope CRS. This is usually the algebraic minimum coordinates, but not
always. For example, an envelope crossing the anti-meridian could have a lower corner
longitude greater than the upper corner longitude. Such extended interpretation applies
mostly to axes having WRAPAROUND
range meaning.
getLowerCorner
in interface Envelope
public DirectPosition getUpperCorner()
getUpper(int)
method,
so changes in this envelope will be immediately reflected in the returned direct position.
If the particular case of the GeneralEnvelope
subclass, the returned position
supports also write operations,
so changes in the position are reflected back in the envelope.
Note:
The Web Coverage Service (WCS) 1.1 specification uses an extended
interpretation of the bounding box definition. In a WCS 1.1 data structure, the upper
corner defines the edges region in the directions of increasing coordinate
values in the envelope CRS. This is usually the algebraic maximum coordinates, but not
always. For example, an envelope crossing the anti-meridian could have an upper corner
longitude less than the lower corner longitude. Such extended interpretation applies
mostly to axes having WRAPAROUND
range meaning.
getUpperCorner
in interface Envelope
public DirectPosition getMedian()
getMedian(int)
method,
so changes in this envelope will be immediately reflected in the returned direct position.public abstract double getLower(int dimension) throws IndexOutOfBoundsException
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 abstract double getUpper(int dimension) throws IndexOutOfBoundsException
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
getLower(int)
value verbatim. In the case of envelope spanning the anti-meridian,
this method returns the axis minimum value.getMinimum
in interface Envelope
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
getUpper(int)
value verbatim. In the case of envelope spanning the anti-meridian,
this method returns the axis maximum value.getMaximum
in interface Envelope
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
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)
span = getUpper(dimension) - getLower(dimension);
NaN
.getSpan
in interface Envelope
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 double getSpan(int dimension, Unit<?> unit) throws IndexOutOfBoundsException, ConversionException
getSpan(int)
and converts the result.dimension
- The dimension to query.unit
- The unit for the return value.IndexOutOfBoundsException
- If the given index is out of bounds.ConversionException
- if the length can't be converted to the specified units.public boolean isEmpty()
isAllNaN()
always returns
false
for a non-empty envelope, but the converse is not always true.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 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
true
if this envelope has NaN values.GeneralEnvelope.setToNaN()
,
DefaultGeographicBoundingBox.isEmpty()
public boolean contains(DirectPosition position) throws MismatchedDimensionException
NaN
,
then this method returns false
.
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.
position
- The point to text.true
if the specified coordinate is inside the boundary of this envelope; false
otherwise.MismatchedDimensionException
- if the specified point doesn't have the expected dimension.AssertionError
- If assertions are enabled and the envelopes have mismatched CRS.public boolean contains(Envelope envelope, boolean edgesInclusive) throws MismatchedDimensionException
true
if this envelope completely encloses the specified envelope.
If one or more edges from the specified envelope coincide with an edge from this
envelope, then this method returns true
only if edgesInclusive
is true
.
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 test for inclusion.edgesInclusive
- true
if this envelope edges are inclusive.true
if this envelope completely encloses the specified one.MismatchedDimensionException
- if the specified envelope doesn't have
the expected dimension.AssertionError
- If assertions are enabled and the envelopes have mismatched CRS.intersects(Envelope, boolean)
,
equals(Envelope, double, boolean)
public boolean intersects(Envelope envelope, boolean edgesInclusive) throws MismatchedDimensionException
true
if this envelope intersects the specified envelope.
If one or more edges from the specified envelope coincide with an edge from this envelope,
then this method returns true
only if edgesInclusive
is true
.
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 test for intersection.edgesInclusive
- true
if this envelope edges are inclusive.true
if this envelope intersects the specified one.MismatchedDimensionException
- if the specified envelope doesn't have the expected dimension.AssertionError
- If assertions are enabled and the envelopes have mismatched CRS.contains(Envelope, boolean)
,
equals(Envelope, double, boolean)
public boolean equals(Envelope other, double eps, boolean epsIsRelative)
eps
can be either relative to the envelope span along each dimension or can be an absolute value (as for example some
ground resolution of a grid coverage).
epsIsRelative
is set to true
, the actual tolerance value for a
given dimension i is eps
× span
where span
is the maximum of this envelope span and the specified
envelope span along dimension i.epsIsRelative
is set to false
, the actual tolerance value for a
given dimension i is eps
.Note: Relative tolerance value (as opposed to absolute tolerance value) help to workaround the fact that tolerance value are CRS dependent. For example the tolerance value need to be smaller for geographic CRS than for UTM projections, because the former typically has a [-180…180]° range while the later can have a range of thousands of meters.
other
- The envelope to compare with.eps
- The tolerance value to use for numerical comparisons.epsIsRelative
- true
if the tolerance value should be relative to
axis length, or false
if it is an absolute value.true
if the given object is equal to this envelope up to the given tolerance value.contains(Envelope, boolean)
,
intersects(Envelope, boolean)
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.
public int hashCode()
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.Copyright © 2010–2013 The Apache Software Foundation. All rights reserved.