org.geotoolkit.geometry
Class GeneralEnvelope

Object
  AbstractEnvelope
      GeneralEnvelope

All Implemented Interfaces:

Serializable, Cloneable, Envelope

public class GeneralEnvelope
extends AbstractEnvelope
implements Cloneable, Serializable

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: Envelope uses an arbitrary Coordinate Reference System, which doesn't 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.

This particular implementation of 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:

• From a given number of dimension, with all ordinates initialized to 0.
• From two coordinate points.
• From a an other envelope (copy constructor).
• From a geographic bounding box or a Java2D rectangle.
• From a grid envelope together with a Grid to CRS transform.
• From a string representing a BBOX in Well Known Text format.

Since:

1.2

Version:

3.16

Author:

Martin Desruisseaux (IRD, Geomatys), Simone Giannecchini (Geosolutions)

See Also:

Envelope2D, jts.ReferencedEnvelope, DefaultGeographicBoundingBox, Serialized Form

Module:

referencing/geotk-referencing (download)

View source code for this class

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(int dimension)
Constructs an empty envelope of the specified dimension.

GeneralEnvelope(Rectangle2D rect)
Constructs two-dimensional envelope defined by a Rectangle2D.

GeneralEnvelope(String wkt)
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) 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 completely encloses the specified envelope.
boolean	equals(Object object) Compares the specified object with this envelope for equality.
CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the coordinate reference system in which the coordinates are given.
int	getDimension() Returns the number of dimensions.
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	reduceToDomain(boolean useDomainOfCRS) Restricts this envelope to the CS or CRS domain of validity.
void	roundIfAlmostInteger(double factor, int maxULP) Fixes rounding errors up to a given tolerance level.
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(Envelope envelope) Sets this envelope to the same coordinate values than the specified envelope.
void	setRange(int dimension, double minimum, double maximum) Sets the envelope range along the specified dimension.
void	setSubEnvelope(Envelope envelope, int offset) Sets a sub-domain of this envelope to the same coordinate values than the specified envelope.
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

equals, toPolygonString, toString, toString

Methods inherited from class Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

GeneralEnvelope

public GeneralEnvelope(int dimension)

Constructs an empty envelope of the specified dimension. All ordinates are initialized to 0 and the coordinate reference system is undefined.

Parameters:

dimension - The envelope dimension.

GeneralEnvelope

public GeneralEnvelope(double min,
                       double max)

Constructs one-dimensional envelope defined by a range of values.

Parameters:

min - The minimal value.

max - The maximal value.

GeneralEnvelope

public GeneralEnvelope(double[] minDP,
                       double[] maxDP)
                throws IllegalArgumentException

Constructs a envelope defined by two positions.

Parameters:

minDP - Minimum ordinate values.

maxDP - Maximum ordinate values.

Throws:

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.

GeneralEnvelope

public GeneralEnvelope(GeneralDirectPosition minDP,
                       GeneralDirectPosition maxDP)
                throws IllegalArgumentException

Constructs a envelope defined by two positions. The coordinate reference system is inferred from the supplied direct position.

Parameters:

minDP - Point containing minimum ordinate values.

maxDP - Point containing maximum ordinate values.

Throws:

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.

GeneralEnvelope

public GeneralEnvelope(CoordinateReferenceSystem crs)

Constructs an empty envelope with the specified coordinate reference system. All ordinates are initialized to 0.

Parameters:

crs - The coordinate reference system.

Since:

2.2

GeneralEnvelope

public GeneralEnvelope(Envelope envelope)

Constructs a new envelope with the same data than the specified envelope.

Parameters:

envelope - The envelope to copy.

GeneralEnvelope

public GeneralEnvelope(GeographicBoundingBox box)

Constructs a new envelope with the same data than the specified geographic bounding box. The coordinate reference system is set to WGS84.

Parameters:

box - The bounding box to copy.

Since:

2.4

GeneralEnvelope

public GeneralEnvelope(Rectangle2D rect)

Constructs two-dimensional envelope defined by a Rectangle2D. The coordinate reference system is initially undefined.

Parameters:

rect - The rectangle to copy.

GeneralEnvelope

public GeneralEnvelope(String wkt)
                throws NumberFormatException,
                       IllegalArgumentException

Constructs a new envelope initialized to the values parsed from the given string in 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 sequences complying to the rules of Java identifiers are skipped.
• Coordinates are separated by a coma (,) character.
• The ordinates in a coordinate are separated by a space.
• Ordinate numbers are assumed formatted in US locale.
• The coordinate having the highest dimension determines the dimension of this envelope.

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))

Parameters:

wkt - The BOX, POLYGON or other kind of element to parse.

Throws:

NumberFormatException - If a number can not be parsed.

IllegalArgumentException - If the parenthesis are not balanced.

Since:

3.09

See Also:

AbstractEnvelope.toString(Envelope), CoordinateFormat

Method Detail

getDimension

public final int getDimension()

Returns the number of dimensions.

Specified by:

getDimension in interface Envelope

getCoordinateReferenceSystem

public final CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the coordinate reference system in which the coordinates are given.

Specified by:

getCoordinateReferenceSystem in interface Envelope

Returns:

The coordinate reference system, or null.

setCoordinateReferenceSystem

public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
                                  throws MismatchedDimensionException

Sets the coordinate reference system in which the coordinate are given. This method does not reproject the envelope, and do not check if the envelope is contained in the new domain of validity. The later can be enforced by a call to reduceToDomain(boolean).

If the envelope coordinates need to be transformed to the new CRS, consider using CRS.transform(Envelope, CoordinateReferenceSystem) instead.

Parameters:

crs - The new coordinate reference system, or null.

Throws:

MismatchedDimensionException - if the specified CRS doesn't have the expected number of dimensions.

reduceToDomain

public boolean reduceToDomain(boolean useDomainOfCRS)

Restricts this envelope to the CS or CRS domain of validity. This method performs two steps:

1. 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 EXACT (typically latitudes ordinates), values greater than the maximum value are replaced by the maximum, and values smaller than the minimum value are replaced by the minimum.
   • If WRAPAROUND (typically longitudes ordinates), a multiple of the range (e.g. 360° for longitudes) is added or subtracted. If a value stay out of range after this correction, then the ordinates are set to the full [minimum … maximum] range. See the example below.

2. If crsDomain is true, then the envelope from the previous step is intersected with the CRS domain of validity, if any.

Example: A longitude range of [185° … 190°] is equivalent to [-175° … -170°]. But [175° … 185°] would be equivalent to [175° … -175°], which is likely to mislead Envelope users 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.

Parameters:

useDomainOfCRS - true if the envelope should be restricted to the CRS domain of validity in addition to the CS domain.

Returns:

true if this envelope has been modified, or false if no change was done.

Since:

3.11 (derived from 2.5)

roundIfAlmostInteger

public void roundIfAlmostInteger(double factor,
                                 int maxULP)

Fixes rounding errors up to a given tolerance level. For each value 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.

The code below illustrates the work done on every ordinate values, omitting (for simplicity) the fact that ordinate[i] is left unchanged if XMath.roundIfAlmostInteger didn't rounded the product.

ordinates[i] = XMath.roundIfAlmostInteger(ordinates[i]*factor, maxULP) / factor;

This method is useful after envelope calculations subject to rounding errors, like the #GeneralEnvelope(GridEnvelope, PixelInCell, MathTransform, CoordinateReferenceSystem) constructor.

Parameters:

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).

Since:

3.11

See Also:

XMath.roundIfAlmostInteger(double, int)

getLowerCorner

public DirectPosition getLowerCorner()

A coordinate position consisting of all the minimal ordinates for each dimension for all points within the Envelope.

Specified by:

getLowerCorner in interface Envelope

Overrides:

getLowerCorner in class AbstractEnvelope

Returns:

The lower corner.

getUpperCorner

public DirectPosition getUpperCorner()

A coordinate position consisting of all the maximal ordinates for each dimension for all points within the Envelope.

Specified by:

getUpperCorner in interface Envelope

Overrides:

getUpperCorner in class AbstractEnvelope

Returns:

The upper corner.

getMedian

public DirectPosition getMedian()

A coordinate position consisting of all the middle ordinates for each dimension for all points within the Envelope.

Returns:

The median coordinates.

Since:

2.5

getMinimum

public final double getMinimum(int dimension)
                        throws IndexOutOfBoundsException

Returns the minimal ordinate along the specified dimension.

Specified by:

getMinimum in interface Envelope

Parameters:

dimension - The dimension to query.

Returns:

The minimal ordinate value along the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is out of bounds.

getMaximum

public final double getMaximum(int dimension)
                        throws IndexOutOfBoundsException

Returns the maximal ordinate along the specified dimension.

Specified by:

getMaximum in interface Envelope

Parameters:

dimension - The dimension to query.

Returns:

The maximal ordinate value along the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is out of bounds.

getMedian

public final double getMedian(int dimension)
                       throws IndexOutOfBoundsException

Returns the median ordinate along the specified dimension. The result should be equals (minus rounding error) to (getMaximum(dimension) - getMinimum(dimension)) / 2.

Specified by:

getMedian in interface Envelope

Parameters:

dimension - The dimension to query.

Returns:

The mid ordinate value along the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is out of bounds.

getSpan

public final double getSpan(int dimension)
                     throws IndexOutOfBoundsException

Returns the envelope span (typically width or height) along the specified dimension. The result should be equals (minus rounding error) to getMaximum(dimension) - getMinimum(dimension).

Specified by:

getSpan in interface Envelope

Parameters:

dimension - The dimension to query.

Returns:

The difference along maximal and minimal ordinates in the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is out of bounds.

getSpan

public double getSpan(int dimension,
                      Unit<?> unit)
               throws IndexOutOfBoundsException,
                      ConversionException

Returns the envelope span along the specified dimension, in terms of the given units.

Parameters:

dimension - The dimension to query.

unit - The unit for the return value.

Returns:

The span in terms of the given unit.

Throws:

IndexOutOfBoundsException - If the given index is out of bounds.

ConversionException - if the length can't be converted to the specified units.

Since:

2.5

setRange

public void setRange(int dimension,
                     double minimum,
                     double maximum)
              throws IndexOutOfBoundsException

Sets the envelope range along the specified dimension.

Parameters:

dimension - The dimension to set.

minimum - The minimum value along the specified dimension.

maximum - The maximum value along the specified dimension.

Throws:

IndexOutOfBoundsException - If the given index is out of bounds.

setEnvelope

public void setEnvelope(double... ordinates)

Sets the envelope to the specified values, which must be the lower corner coordinates followed by upper corner coordinates. The number of arguments provided shall be twice this envelope dimension, and minimum shall not be greater than maximum.

Example: (x_min, y_min, z_min, x_max, y_max, z_max)

Parameters:

ordinates - The new ordinate values.

Since:

2.5

setEnvelope

public void setEnvelope(Envelope envelope)
                 throws MismatchedDimensionException

Sets this envelope to the same coordinate values than the specified envelope. If the given envelope has a non-null Coordinate Reference System (CRS), then the CRS of this envelope will be set to the CRS of the given envelope.

Parameters:

envelope - The envelope to copy coordinates from.

Throws:

MismatchedDimensionException - if the specified envelope doesn't have the expected number of dimensions.

Since:

2.2

setSubEnvelope

public void setSubEnvelope(Envelope envelope,
                           int offset)
                    throws IndexOutOfBoundsException

Sets a sub-domain of this envelope to the same coordinate values than the specified envelope. This method copies the ordinate values of all dimensions from the given envelope to some dimensions of this envelope. The target dimensions in this envelope range from lower inclusive to lower + getDimension() exclusive.

This method ignores the Coordinate Reference System of this and the given envelope.

Parameters:

envelope - The envelope to copy coordinates from.

offset - Index of the first dimension to write in this envelope.

Throws:

IndexOutOfBoundsException - If the given offset is negative, or is greater than getDimension() - envelope.getDimension().

Since:

3.16

getSubEnvelope

public GeneralEnvelope getSubEnvelope(int lower,
                                      int upper)
                               throws IndexOutOfBoundsException

Returns a new envelope that encompass only some dimensions of this envelope. This method copy this envelope ordinates into a new envelope, beginning at dimension lower and extending to dimension upper-1. Thus the dimension of the sub-envelope is upper-lower.

Parameters:

lower - The first dimension to copy, inclusive.

upper - The last dimension to copy, exclusive.

Returns:

The sub-envelope.

Throws:

IndexOutOfBoundsException - if an index is out of bounds.

getReducedEnvelope

public GeneralEnvelope getReducedEnvelope(int lower,
                                          int upper)
                                   throws IndexOutOfBoundsException

Returns a new envelope with the same values than this envelope minus the specified range of dimensions.

Parameters:

lower - The first dimension to omit, inclusive.

upper - The last dimension to omit, exclusive.

Returns:

The sub-envelope.

Throws:

IndexOutOfBoundsException - if an index is out of bounds.

setToInfinite

public void setToInfinite()

Sets the lower corner to negative infinity and the upper corner to positive infinity. The coordinate reference system (if any) stay unchanged.

Since:

2.2

isInfinite

public boolean isInfinite()

Returns true if at least one ordinate has an infinite value.

Returns:

true if this envelope has infinite value.

Since:

2.2

setToNull

public void setToNull()

Sets all ordinate values to NaN. The coordinate reference system (if any) stay unchanged.

Since:

2.2

isNull

public boolean isNull()

Returns 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:

• If isNull() == true, then isEmpty() == true
• If isEmpty() == false, then isNull() == false
• The converse of the above-cited rules are not always true.

Returns:

true if this envelope has NaN values.

Since:

2.2

isEmpty

public boolean isEmpty()

Determines whether or not this envelope is empty. An envelope is non-empty only if it has at least one dimension, and the span is greater than 0 along all dimensions. Note that a non-empty envelope is always non-null, but the converse is not always true.

Returns:

true if this envelope is empty.

add

public void add(DirectPosition position)
         throws MismatchedDimensionException

Adds a point to this envelope. The resulting envelope is the smallest envelope that contains both the original envelope and the specified point. After adding a point, a call to contains(org.opengis.geometry.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 have been ignored).

Note: This method assumes that the specified point uses the same CRS than this envelope. For performance reason, it will no be verified unless Java assertions are enabled.

Parameters:

position - The point to add.

Throws:

MismatchedDimensionException - if the specified point doesn't have the expected dimension.

add

public void add(Envelope envelope)
         throws MismatchedDimensionException

Adds an envelope object to this envelope. The resulting envelope is the union of the two Envelope objects.

Note: This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless Java assertions are enabled.

Parameters:

envelope - the Envelope to add to this envelope.

Throws:

MismatchedDimensionException - if the specified envelope doesn't have the expected dimension.

contains

public boolean contains(DirectPosition position)
                 throws MismatchedDimensionException

Tests if a specified coordinate is inside the boundary of this envelope. If it least one ordinate value in the given point is NaN, then this method returns false.

Note: This method assumes that the specified point uses the same CRS than this envelope. For performance reason, it will no be verified unless Java assertions are enabled.

Parameters:

position - The point to text.

Returns:

true if the specified coordinates are inside the boundary of this envelope; false otherwise.

Throws:

MismatchedDimensionException - if the specified point doesn't have the expected dimension.

contains

public boolean contains(Envelope envelope,
                        boolean edgesInclusive)
                 throws MismatchedDimensionException

Returns 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 reason, it will no be verified unless Java assertions are enabled.

Parameters:

envelope - The envelope to test for inclusion.

edgesInclusive - true if this envelope edges are inclusive.

Returns:

true if this envelope completely encloses the specified one.

Throws:

MismatchedDimensionException - if the specified envelope doesn't have the expected dimension.

Since:

2.2

See Also:

intersects(Envelope, boolean), AbstractEnvelope.equals(Envelope, double, boolean)

intersects

public boolean intersects(Envelope envelope,
                          boolean edgesInclusive)
                   throws MismatchedDimensionException

Returns 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 reason, it will no be verified unless Java assertions are enabled.

Parameters:

envelope - The envelope to test for intersection.

edgesInclusive - true if this envelope edges are inclusive.

Returns:

true if this envelope intersects the specified one.

Throws:

MismatchedDimensionException - if the specified envelope doesn't have the expected dimension.

Since:

2.2

See Also:

contains(Envelope, boolean), AbstractEnvelope.equals(Envelope, double, boolean)

intersect

public void intersect(Envelope envelope)
               throws MismatchedDimensionException

Sets this envelope to the intersection if this envelope with the specified one.

Note: This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless Java assertions are enabled.

Parameters:

envelope - the Envelope to intersect to this envelope.

Throws:

MismatchedDimensionException - if the specified envelope doesn't have the expected dimension.

toRectangle2D

public Rectangle2D toRectangle2D()
                          throws IllegalStateException

Returns a Rectangle2D with the same bounds as this Envelope. This envelope must be two-dimensional before this method is invoked. This is a convenience method for inter-operability with Java2D.

Returns:

This envelope as a two-dimensional rectangle.

Throws:

IllegalStateException - if this envelope is not two-dimensional.

hashCode

public int hashCode()

Returns a hash value for this envelope.

Overrides:

hashCode in class AbstractEnvelope

equals

public boolean equals(Object object)

Compares the specified object with this envelope for equality.

Overrides:

equals in class AbstractEnvelope

Parameters:

object - The object to compare with this envelope.

Returns:

true if the given object is equal to this envelope.

clone

public GeneralEnvelope clone()

Returns a deep copy of this envelope.

Overrides:

clone in class Object

Returns:

A clone of this envelope.