|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
ObjectAbstractEnvelope
GeneralEnvelope
public class GeneralEnvelope
A minimum bounding box or rectangle. 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.
This particular implementation of Envelope
is said "General" because it
uses coordinates of an arbitrary dimension.
Tip: The metadata package provides a
GeographicBoundingBox
, which can be used as
a kind of envelope with a coordinate reference system fixed to WGS 84 (EPSG:4326).
Envelope2D
,
ReferencedEnvelope
,
GeographicBoundingBox
,
Serialized Form
modules/library/referencing (gt-referencing.jar)
Constructor Summary | |
---|---|
GeneralEnvelope(CoordinateReferenceSystem crs)
Constructs an empty envelope with the specified coordinate reference system. |
|
GeneralEnvelope(double[] minDP,
double[] maxDP)
Constructs a envelope defined by two positions. |
|
GeneralEnvelope(double min,
double max)
Constructs one-dimensional envelope defined by a range of values. |
|
GeneralEnvelope(Envelope envelope)
Constructs a new envelope with the same data than the specified envelope. |
|
GeneralEnvelope(GeneralDirectPosition minDP,
GeneralDirectPosition maxDP)
Constructs a envelope defined by two positions. |
|
GeneralEnvelope(GeographicBoundingBox box)
Constructs a new envelope with the same data than the specified geographic bounding box. |
|
GeneralEnvelope(GridEnvelope gridRange,
PixelInCell anchor,
MathTransform gridToCRS,
CoordinateReferenceSystem crs)
Creates an envelope for a grid range transformed to an envelope using the specified math transform. |
|
GeneralEnvelope(int dimension)
Constructs an empty envelope of the specified dimension. |
|
GeneralEnvelope(Rectangle2D rect)
Constructs two-dimensional envelope defined by a Rectangle2D . |
Method Summary | |
---|---|
void |
add(DirectPosition position)
Adds a point to this envelope. |
void |
add(Envelope envelope)
Adds an envelope object to this envelope. |
GeneralEnvelope |
clone()
Returns a deep copy of this envelope. |
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 completly encloses the specified envelope. |
boolean |
equals(Envelope envelope,
double eps,
boolean epsIsRelative)
Compares to the specified envelope for equality up to the specified tolerance value. |
boolean |
equals(Object object)
Compares the specified object with this envelope for equality. |
DirectPosition |
getCenter()
Deprecated. Renamed as #getMedian( . |
double |
getCenter(int dimension)
Deprecated. Renamed as getMedian(int) . |
CoordinateReferenceSystem |
getCoordinateReferenceSystem()
Returns the coordinate reference system in which the coordinates are given. |
int |
getDimension()
Returns the number of dimensions. |
double |
getLength(int dimension)
Deprecated. Renamed as getSpan(int) . |
double |
getLength(int dimension,
Unit<?> unit)
Deprecated. Renamed as getSpan(int,Unit) . |
DirectPosition |
getLowerCorner()
A coordinate position consisting of all the minimal ordinates for each dimension for all points within the Envelope . |
double |
getMaximum(int dimension)
Returns the maximal ordinate along the specified dimension. |
DirectPosition |
getMedian()
A coordinate position consisting of all the middle ordinates for each dimension for all points within the Envelope . |
double |
getMedian(int dimension)
Returns the median ordinate along the specified dimension. |
double |
getMinimum(int dimension)
Returns the minimal ordinate along the specified dimension. |
GeneralEnvelope |
getReducedEnvelope(int lower,
int upper)
Returns a new envelope with the same values than this envelope minus the specified range of dimensions. |
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. |
GeneralEnvelope |
getSubEnvelope(int lower,
int upper)
Returns a new envelope that encompass only some dimensions of this envelope. |
DirectPosition |
getUpperCorner()
A coordinate position consisting of all the maximal ordinates for each dimension for all points within the Envelope . |
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 |
intersects(Envelope envelope,
boolean edgesInclusive)
Returns true if this envelope intersects the specified envelope. |
boolean |
isEmpty()
Determines whether or not this envelope is empty. |
boolean |
isInfinite()
Returns true if at least one ordinate has an
infinite value. |
boolean |
isNull()
Returns false if at least one ordinate value is not NaN. |
boolean |
normalize(boolean crsDomain)
Restricts this envelope to the CS or CRS domain of validity. |
void |
setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
Sets the coordinate reference system in which the coordinate are given. |
void |
setEnvelope(double... ordinates)
Sets the envelope to the specified values, which must be the lower corner coordinates followed by upper corner coordinates. |
void |
setEnvelope(GeneralEnvelope envelope)
Sets this envelope to the same coordinate values than the specified envelope. |
void |
setRange(int dimension,
double minimum,
double maximum)
Sets the envelope's range along the specified dimension. |
void |
setToInfinite()
Sets the lower corner to negative infinity and the upper corner to positive infinity. |
void |
setToNull()
Sets all ordinate values to NaN. |
Rectangle2D |
toRectangle2D()
Returns a Rectangle2D with the same bounds as this Envelope . |
Methods inherited from class AbstractEnvelope |
---|
toString |
Methods inherited from class Object |
---|
finalize, getClass, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
public GeneralEnvelope(int dimension)
dimension
- The envelope dimension.public GeneralEnvelope(double min, double max)
min
- The minimal value.max
- The maximal value.public GeneralEnvelope(double[] minDP, double[] maxDP) throws IllegalArgumentException
minDP
- Minimum ordinate values.maxDP
- Maximum ordinate values.
MismatchedDimensionException
- if the two positions don't have the same dimension.
IllegalArgumentException
- if an ordinate value in the minimum point is not
less than or equal to the corresponding ordinate value in the maximum point.public GeneralEnvelope(GeneralDirectPosition minDP, GeneralDirectPosition maxDP) throws MismatchedReferenceSystemException, IllegalArgumentException
minDP
- Point containing minimum ordinate values.maxDP
- Point containing maximum ordinate values.
MismatchedDimensionException
- if the two positions don't have the same dimension.
MismatchedReferenceSystemException
- if the two positions don't use the same CRS.
IllegalArgumentException
- if an ordinate value in the minimum point is not
less than or equal to the corresponding ordinate value in the maximum point.public GeneralEnvelope(CoordinateReferenceSystem crs)
crs
- The coordinate reference system.public GeneralEnvelope(Envelope envelope)
envelope
- The envelope to copy.public GeneralEnvelope(GeographicBoundingBox box)
box
- The bounding box to copy.public GeneralEnvelope(Rectangle2D rect)
Rectangle2D
.
The coordinate reference system is initially undefined.
rect
- The rectangle to copy.public GeneralEnvelope(GridEnvelope gridRange, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs) throws IllegalArgumentException
anchor
value. This constructor creates an envelope
containing entirely all pixels on a best effort basis - usually
accurate for affine transforms.
Note: The convention is specified as a PixelInCell
code instead than the
more detailled PixelOrientation
, because the later
is restricted to the two-dimensional case while the former can be used for any number of
dimensions.
gridRange
- The grid range.anchor
- Whatever grid range coordinates map to pixel center or pixel corner.gridToCRS
- The transform (usually affine) from grid range to the envelope CRS.crs
- The envelope CRS, or null
if unknow.
MismatchedDimensionException
- If one of the supplied object doesn't have
a dimension compatible with the other objects.
IllegalArgumentException
- if an argument is illegal for some other reason,
including failure to use the provided math transform.GeneralGridEnvelope.GeneralGridEnvelope(Envelope,PixelInCell,boolean)
Method Detail |
---|
public final CoordinateReferenceSystem getCoordinateReferenceSystem()
getCoordinateReferenceSystem
in interface Envelope
null
.public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs) throws MismatchedDimensionException
normalize(boolean)
.
crs
- The new coordinate reference system, or null
.
MismatchedDimensionException
- if the specified CRS doesn't have the expected
number of dimensions.public boolean normalize(boolean crsDomain)
First, it ensures that the envelope is contained in the coordinate system domain. Out of range ordinates are validated in a way that depends on the range meaning:
Example: [185° ... 190°] of longitude is equivalent to [-175° ... -170°]. But
[175° ... 185°] would be equivalent to [175° ... -175°], which is likely to mislead
most users of Envelope
since the lower bounds is numerically greater than the
upper bounds. Reordering as [-175° ... 175°] would interchange the meaning of what is
"inside" and "outside" the envelope. So this implementation conservatively expands the
range to [-180° ... 180°] in order to ensure that the validated envelope fully contains
the original envelope.
Second and only if crsDomain
is true
, the envelope normalized in
the previous step is intersected with the CRS
domain of validity, if any.
crsDomain
- true
if the envelope should be restricted to the CRS domain in
addition of the CS domain.
true
if this envelope has been modified, or false
if no change
was done.public final int getDimension()
getDimension
in interface Envelope
public DirectPosition getLowerCorner()
Envelope
.
getLowerCorner
in interface Envelope
getLowerCorner
in class AbstractEnvelope
public DirectPosition getUpperCorner()
Envelope
.
getUpperCorner
in interface Envelope
getUpperCorner
in class AbstractEnvelope
@Deprecated public DirectPosition getCenter()
#getMedian(
.
Envelope
.
public DirectPosition getMedian()
Envelope
.
public final double getMinimum(int dimension) throws IndexOutOfBoundsException
getMinimum
in interface Envelope
dimension
- The dimension to query.
IndexOutOfBoundsException
- If the given index is out of bounds.public final double getMaximum(int dimension) throws IndexOutOfBoundsException
getMaximum
in interface Envelope
dimension
- The dimension to query.
IndexOutOfBoundsException
- If the given index is out of bounds.@Deprecated public final double getCenter(int dimension)
getMedian(int)
.
getCenter
in interface Envelope
dimension
- The dimension to query.
public final double getMedian(int dimension) throws IndexOutOfBoundsException
(getMaximum(dimension) -
getMinimum(dimension)) / 2
.
getMedian
in interface Envelope
dimension
- The dimension to query.
IndexOutOfBoundsException
- If the given index is out of bounds.@Deprecated public final double getLength(int dimension)
getSpan(int)
.
getLength
in interface Envelope
dimension
- The dimension to query.
public final double getSpan(int dimension) throws IndexOutOfBoundsException
getMaximum(dimension) - getMinimum(dimension)
.
getSpan
in interface Envelope
dimension
- The dimension to query.
IndexOutOfBoundsException
- If the given index is out of bounds.@Deprecated public double getLength(int dimension, Unit<?> unit) throws ConversionException
getSpan(int,Unit)
.
dimension
- The dimension to query.unit
- The unit for the return value.
ConversionException
- if the length can't be converted to the specified units.public double getSpan(int dimension, Unit<?> unit) throws IndexOutOfBoundsException, ConversionException
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 void setRange(int dimension, double minimum, double maximum) throws IndexOutOfBoundsException
dimension
- The dimension to set.minimum
- The minimum value along the specified dimension.maximum
- The maximum value along the specified dimension.
IndexOutOfBoundsException
- If the given index is out of bounds.public void setEnvelope(double... ordinates)
Example: (xmin, ymin, zmin, xmax, ymax, zmax)
ordinates
- The new ordinate values.public void setEnvelope(GeneralEnvelope envelope) throws MismatchedDimensionException
envelope
- The new envelope to copy coordinates from.
MismatchedDimensionException
- if the specified envelope doesn't have the expected
number of dimensions.public void setToInfinite()
public boolean isInfinite()
true
if at least one ordinate has an
infinite value.
true
if this envelope has infinite value.public void setToNull()
public boolean isNull()
false
if at least one ordinate value is not NaN. The
isNull()
check is a little bit different than isEmpty()
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:
isNull() == true
, then isEmpty() == true
isEmpty() == false
, then isNull() == false
true
if this envelope has NaN values.public boolean isEmpty()
true
if this envelope is empty.public void add(DirectPosition position) throws MismatchedDimensionException
contains(org.opengis.geometry.DirectPosition)
with the added point as an argument will return true
,
except if one of the point's ordinates was Double.NaN
(in which case the
corresponding ordinate have been ignored).
This method assumes that the specified point uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
position
- The point to add.
MismatchedDimensionException
- if the specified point doesn't have
the expected dimension.public void add(Envelope envelope) throws MismatchedDimensionException
Envelope
objects.
This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
envelope
- the Envelope
to add to this envelope.
MismatchedDimensionException
- if the specified envelope doesn't
have the expected dimension.public boolean contains(DirectPosition position) throws MismatchedDimensionException
This method assumes that the specified point uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
position
- The point to text.
true
if the specified coordinates are inside the boundary
of this envelope; false
otherwise.
MismatchedDimensionException
- if the specified point doesn't have
the expected dimension.public boolean contains(Envelope envelope, boolean edgesInclusive) throws MismatchedDimensionException
true
if this envelope completly 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
.
This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
envelope
- The envelope to test for inclusion.edgesInclusive
- true
if this envelope edges are inclusive.
true
if this envelope completly encloses the specified one.
MismatchedDimensionException
- if the specified envelope doesn't have
the expected dimension.intersects(Envelope, boolean)
,
#equals(Envelope, double)
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
.
This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE 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.contains(Envelope, boolean)
,
#equals(Envelope, double)
public void intersect(Envelope envelope) throws MismatchedDimensionException
This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
envelope
- the Envelope
to intersect to this envelope.
MismatchedDimensionException
- if the specified envelope doesn't
have the expected dimension.public GeneralEnvelope getSubEnvelope(int lower, int upper) throws IndexOutOfBoundsException
lower
and extending to dimension upper-1
.
Thus the dimension of the subenvelope is upper-lower
.
lower
- The first dimension to copy, inclusive.upper
- The last dimension to copy, exclusive.
IndexOutOfBoundsException
- if an index is out of bounds.public GeneralEnvelope getReducedEnvelope(int lower, int upper) throws IndexOutOfBoundsException
lower
- The first dimension to omit, inclusive.upper
- The last dimension to omit, exclusive.
IndexOutOfBoundsException
- if an index is out of bounds.public Rectangle2D toRectangle2D() throws IllegalStateException
Rectangle2D
with the same bounds as this Envelope
.
This is a convenience method for interoperability with Java2D.
IllegalStateException
- if this envelope is not two-dimensional.public int hashCode()
hashCode
in class AbstractEnvelope
public boolean equals(Object object)
equals
in class AbstractEnvelope
object
- The object to compare with this envelope.
true
if the given object is equals to this envelope.public boolean equals(Envelope envelope, double eps, boolean epsIsRelative)
eps
can be either relative to the envelope length along each dimension or can be an absolute value (as for example some
ground resolution of a grid coverage).
If relativeToLength
is set to true
, the actual tolerance value for a given
dimension i is eps
×length
where length
is the
maximum of this envelope length and the specified envelope length
along dimension i.
If relativeToLength
is set to false
, the actual tolerance value for a
given dimension i is eps
.
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 range of -180 to 180° while the later can have a range of thousands of meters.
This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
envelope
- The envelope to compare with.eps
- The tolerance value to use for numerical comparaisons.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 equals to this envelope up to the given
tolerance value.contains(Envelope, boolean)
,
intersects(Envelope, boolean)
public GeneralEnvelope clone()
clone
in class Object
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |