|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
ObjectAbstractEnvelope
AbstractEnvelope
GeneralEnvelope
GeneralEnvelope.
@Deprecated 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.
Note:This particular implementation ofEnvelopeuses an arbitrary Coordinate Reference System, which doesn't need to be geographic. This is different than theGeographicBoundingBoxclass 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 dimension. This is in contrast with Envelope2D,
which can use only two-dimensional coordinates.
A GeneralEnvelope can be created in various ways:
BBOX in
Well Known Text format.
Spanning the anti-meridian of a Geographic CRS
The Web Coverage Service (WCS) specification authorizes (with special treatment)
cases where upper < lower at least in the longitude case. They are
envelopes crossing the anti-meridian, like the red box below (the green box is the usual case).
The default implementation of methods listed in the right column can handle such cases.
|
Supported methods:
|
Envelope2D,
org.geotoolkit.geometry.jts.ReferencedEnvelope,
DefaultGeographicBoundingBox,
Serialized Form
| referencing/geotk-referencing (download) | View source code for this class |
| Constructor Summary | |
|---|---|
GeneralEnvelope(CoordinateReferenceSystem crs)
Deprecated. Constructs an empty envelope with the specified coordinate reference system. |
|
GeneralEnvelope(double[] minDP,
double[] maxDP)
Deprecated. Constructs a envelope defined by two positions. |
|
GeneralEnvelope(double min,
double max)
Deprecated. Constructs one-dimensional envelope defined by a range of values. |
|
GeneralEnvelope(Envelope envelope)
Deprecated. Constructs a new envelope with the same data than the specified envelope. |
|
GeneralEnvelope(GeneralDirectPosition lower,
GeneralDirectPosition upper)
Deprecated. Constructs a envelope defined by two positions. |
|
GeneralEnvelope(GeographicBoundingBox box)
Deprecated. Constructs a new envelope with the same data than the specified geographic bounding box. |
|
GeneralEnvelope(GridEnvelope gridEnvelope,
PixelInCell anchor,
MathTransform gridToCRS,
CoordinateReferenceSystem crs)
Deprecated. Constructs a georeferenced envelope from a grid envelope transformed using the specified math transform. |
|
GeneralEnvelope(int dimension)
Deprecated. Constructs an empty envelope of the specified dimension. |
|
GeneralEnvelope(Rectangle2D rect)
Deprecated. Constructs two-dimensional envelope defined by a Rectangle2D. |
|
GeneralEnvelope(String wkt)
Deprecated. Constructs a new envelope initialized to the values parsed from the given string in Well Known Text (WKT) format. |
|
| Method Summary | |
|---|---|
void |
add(DirectPosition position)
Deprecated. Adds a point to this envelope. |
void |
add(Envelope envelope)
Deprecated. Adds an envelope object to this envelope. |
static GeneralEnvelope |
castOrCopy(Envelope envelope)
Deprecated. Returns the given envelope as a GeneralEnvelope instance. |
GeneralEnvelope |
clone()
Deprecated. Returns a deep copy of this envelope. |
boolean |
equals(Object object)
Compares the specified object with this envelope for equality. |
CoordinateReferenceSystem |
getCoordinateReferenceSystem()
Deprecated. Returns the envelope coordinate reference system, or null if unknown. |
int |
getDimension()
Deprecated. Returns the length of coordinate sequence (the number of entries) in this envelope. |
double |
getLower(int dimension)
|
DirectPosition |
getLowerCorner()
|
double |
getMaximum(int dimension)
|
double |
getMedian(int dimension)
|
double |
getMinimum(int dimension)
|
double |
getSpan(int dimension)
|
GeneralEnvelope |
getSubEnvelope(int lower,
int upper)
Deprecated. Returns an envelope that encompass only some dimensions of this envelope. |
double |
getUpper(int dimension)
|
DirectPosition |
getUpperCorner()
|
int |
hashCode()
Returns a hash value for this envelope. |
void |
intersect(Envelope envelope)
Deprecated. Sets this envelope to the intersection if this envelope with the specified one. |
boolean |
isAllNaN()
|
boolean |
isEmpty()
|
boolean |
isInfinite()
Deprecated. Returns true if at least one ordinate has an
infinite value. |
boolean |
reduceToDomain(boolean useDomainOfCRS)
Deprecated. Restricts this envelope to the CS or CRS domain of validity. |
boolean |
reorderCorners()
Deprecated. Ensures that lower <= upper for every dimensions. |
void |
roundIfAlmostInteger(double factor,
int maxULP)
Deprecated. Fixes rounding errors up to a given tolerance level. |
void |
setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
Deprecated. Sets the coordinate reference system in which the coordinate are given. |
void |
setEnvelope(double... ordinates)
Deprecated. Sets the envelope to the specified values, which must be the lower corner coordinates followed by upper corner coordinates. |
void |
setEnvelope(Envelope envelope)
Deprecated. Sets this envelope to the same coordinate values than the specified envelope. |
void |
setRange(int dimension,
double minimum,
double maximum)
Deprecated. Sets the envelope range along the specified dimension. |
void |
setSubEnvelope(Envelope envelope,
int offset)
Deprecated. Sets a sub-domain of this envelope to the same coordinate values than the specified envelope. |
void |
setToInfinite()
Deprecated. Sets the lower corner to negative infinity and the upper corner to positive infinity. |
void |
setToNull()
Deprecated. Sets all ordinate values to NaN. |
| Methods inherited from class AbstractEnvelope |
|---|
isNull, toRectangle2D |
| Methods inherited from class AbstractEnvelope |
|---|
contains, contains, equals, getMedian, getSpan, intersects, 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 lower value.max - The upper value.
public GeneralEnvelope(double[] minDP,
double[] maxDP)
minDP - Lower ordinate values.maxDP - Upper ordinate values.
MismatchedDimensionException - if the two positions don't have the same dimension.
public GeneralEnvelope(GeneralDirectPosition lower,
GeneralDirectPosition upper)
throws MismatchedReferenceSystemException
lower - Point containing the starting ordinate values.upper - Point containing the ending ordinate values.
MismatchedDimensionException - if the two positions don't have the same dimension.
MismatchedReferenceSystemException - if the two positions don't use the same CRS.Envelope2D.Envelope2D(DirectPosition, DirectPosition)public GeneralEnvelope(CoordinateReferenceSystem crs)
crs - The coordinate reference system.public GeneralEnvelope(Envelope envelope)
envelope - The envelope to copy.Envelope2D.Envelope2D(Envelope)public GeneralEnvelope(GeographicBoundingBox box)
box - The bounding box to copy.Envelope2D.Envelope2D(GeographicBoundingBox)public GeneralEnvelope(Rectangle2D rect)
Rectangle2D.
The coordinate reference system is initially undefined.
rect - The rectangle to copy.Envelope2D.Envelope2D(CoordinateReferenceSystem, Rectangle2D)
public GeneralEnvelope(GridEnvelope gridEnvelope,
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 detailed PixelOrientation, because the later is restricted to the
two-dimensional case while the former can be used for any number of dimensions.
gridEnvelope - The grid envelope in integer coordinates.anchor - Whatever grid coordinates map to pixel center or pixel corner.gridToCRS - The transform (usually affine) from grid envelope to the CRS.crs - The CRS for the envelope to be created, or null if unknown.
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 raisons,
including failure to use the provided math transform.GridToEnvelopeMapper,
GeneralGridEnvelope.GeneralGridEnvelope(Envelope,PixelInCell,boolean)
public GeneralEnvelope(String wkt)
throws NumberFormatException,
IllegalArgumentException
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.
This constructor does not check the consistency of the provided WKT. For example it doesn't
check that every points in a 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 standard
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.
NumberFormatException - If a number can not be parsed.
IllegalArgumentException - If the parenthesis are not balanced.Envelopes.parseWKT(String),
Envelopes.toWKT(Envelope)| Method Detail |
|---|
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)public final int getDimension()
getDimension in interface Envelopepublic final CoordinateReferenceSystem getCoordinateReferenceSystem()
null if unknown.
If non-null, it shall be the same as lower corner
and upper corner CRS.
getCoordinateReferenceSystem in interface Envelopenull if unknown.
public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
throws MismatchedDimensionException
reduceToDomain(boolean).
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 boolean reduceToDomain(boolean useDomainOfCRS)
First, ensure that the envelope is contained in the coordinate system domain. If some ordinates are out of range, then there is a choice depending on the range meaning:
If RangeMeaning.EXACT (typically latitudes ordinates), then values
greater than the maximum value are
replaced by the maximum, and values smaller than the
minimum value are replaced by the minimum.
If RangeMeaning.WRAPAROUND (typically longitudes ordinates),
then a multiple of the range (e.g. 360° for longitudes) is added or subtracted.
Example:
If crsDomain is true, then the envelope from the previous step
is intersected with the CRS domain of validity, if any.
Spanning the anti-meridian of a Geographic CRS
Note that if the envelope is spanning the anti-meridian, then some lower ordinate values may become greater than the upper ordinate
values even if it was not the case before this method call. If this is not acceptable, consider
invoking reorderCorners() after this method call.
Choosing the range of longitude values
Geographic CRS typically have longitude values in the [-180 … +180]° range,
but the [0 … 360]° range is also occasionally used. Callers need to ensure
that this envelope CRS is associated to axes having the desired
minimum and
maximum value.
The AxisRangeType enumeration can be used
for shifting a geographic CRS to the desired range.
Usage
This method is sometime useful before to compute the union
or intersection of envelopes, in order to ensure that
both envelopes are defined in the same domain. This method may also be invoked before
to project an envelope, since some projections produce Double.NaN numbers when
given an ordinate value out of bounds.
useDomainOfCRS - true if the envelope should be restricted to
the CRS domain of validity in addition to the CS domain.
true if this envelope has been modified as a result of this method call,
or false if no change was done.ReferenceSystem.getDomainOfValidity(),
AxisRangeType
public boolean reorderCorners()
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.This method is useful when the envelope needs to be used with library that doesn't support envelopes spanning the anti-meridian.
true if this envelope has been modified as a result of this method call,
or false if no change was done.
IllegalStateException - If a upper ordinate value is less than a lower ordinate
value on an axis which doesn't have the WRAPAROUND range meaning.
public void roundIfAlmostInteger(double factor,
int maxULP)
ordinates[i]
at dimension i, this method multiplies the ordinate value by the given factor,
then round the result only if the product is close to an integer value. The threshold is
defined by the maxULP argument in ULP units (Unit in the Last Place).
If and only if the product has been rounded, it is divided by the factor and stored in this
envelope in place of the original ordinate.
This method is useful after envelope calculations subject to rounding errors, like the
GeneralEnvelope(GridEnvelope, PixelInCell, MathTransform, CoordinateReferenceSystem)
constructor.
factor - The factor by which to multiply ordinates before rounding
and divide after rounding. A recommended value is 360.maxULP - The maximal change allowed in ULPs (Unit in the Last Place).
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(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 setSubEnvelope(Envelope envelope,
int offset)
throws IndexOutOfBoundsException
offset
inclusive to lower + Envelope.getDimension() exclusive.
This method ignores the Coordinate Reference System of this and the given envelope.
envelope - The envelope to copy coordinates from.offset - Index of the first dimension to write in this envelope.
IndexOutOfBoundsException - If the given offset is negative, or is greater than
getDimension() - envelope.getDimension().
public GeneralEnvelope getSubEnvelope(int lower,
int upper)
throws IndexOutOfBoundsException
If the given lower and upper arguments are equal to 0 and this
envelope dimension respectively, then this method returns
this. Note that in such case, the CRS
(if non-null) is still valid.
Otherwise, this method copies the ordinate values from this envelope into a new
envelope, beginning at dimension lower and extending to dimension upper-1.
The CRS of the new envelope is initialized
to null. This method does not compute a new CRS because it may not be needed,
or the new CRS may be already known by the caller.
lower - The first dimension to copy, inclusive.upper - The last dimension to copy, exclusive.
upper-lower, which may be this.
IndexOutOfBoundsException - if an index is out of bounds.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()
isAllNaN()
public void add(DirectPosition position)
throws MismatchedDimensionException,
AssertionError
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.
Spanning the anti-meridian of a Geographic CRS
This method supports envelopes spanning the anti-meridian. In such cases it is possible to
move both envelope borders in order to encompass the given point, as illustrated below (the
new point is represented by the + 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,
AssertionError
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.
Spanning the anti-meridian of a Geographic CRS
This method supports envelopes spanning the anti-meridian. If one or both envelopes span
the anti-meridian, then the result of the 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,
AssertionError
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.
Spanning the anti-meridian of a Geographic CRS
This method supports envelopes spanning the anti-meridian.
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 GeneralEnvelope clone()
clone in class ObjectObject.clone()public DirectPosition getLowerCorner()
getLowerCorner in interface EnvelopegetLowerCorner in class AbstractEnvelopepublic DirectPosition getUpperCorner()
getUpperCorner in interface EnvelopegetUpperCorner in class AbstractEnvelope
public double getLower(int dimension)
throws IndexOutOfBoundsException
getLower in class AbstractEnvelopeIndexOutOfBoundsException
public double getUpper(int dimension)
throws IndexOutOfBoundsException
getUpper in class AbstractEnvelopeIndexOutOfBoundsException
public double getMinimum(int dimension)
throws IndexOutOfBoundsException
getMinimum in interface EnvelopegetMinimum in class AbstractEnvelopeIndexOutOfBoundsException
public double getMaximum(int dimension)
throws IndexOutOfBoundsException
getMaximum in interface EnvelopegetMaximum in class AbstractEnvelopeIndexOutOfBoundsException
public double getMedian(int dimension)
throws IndexOutOfBoundsException
getMedian in interface EnvelopegetMedian in class AbstractEnvelopeIndexOutOfBoundsException
public double getSpan(int dimension)
throws IndexOutOfBoundsException
getSpan in interface EnvelopegetSpan in class AbstractEnvelopeIndexOutOfBoundsExceptionpublic boolean isEmpty()
isEmpty in class AbstractEnvelopepublic boolean isAllNaN()
isAllNaN in class AbstractEnvelopepublic int hashCode()
hashCode in class AbstractEnvelopepublic boolean equals(Object object)
equals in class AbstractEnvelope
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||