org.geotools.geometry
Class GeneralEnvelope

java.lang.Object
  org.geotools.geometry.GeneralEnvelope

All Implemented Interfaces:

java.lang.Cloneable, org.opengis.util.Cloneable, org.opengis.spatialschema.geometry.Envelope, java.io.Serializable

public class GeneralEnvelope

extends java.lang.Object

implements org.opengis.spatialschema.geometry.Envelope, org.opengis.util.Cloneable, java.io.Serializable

A minimum bounding box or rectangle. Regardless of dimension, an can be represented without ambiguity as two direct positions (coordinate points). To encode an , it is sufficient to encode these two points.

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

Since:

2.0

Version:

$Id: GeneralEnvelope.java 18374 2006-03-01 23:12:02Z desruisseaux $

Author:

Martin Desruisseaux

See Also:

Envelope2D, ReferencedEnvelope, GeographicBoundingBox, Serialized Form

Constructor Summary

GeneralEnvelope(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
Constructs an empty envelope with the specified coordinate reference system.

GeneralEnvelope(double[] minCP, double[] maxCP)
Constructs a envelope defined by two positions.

GeneralEnvelope(double min, double max)
Constructs one-dimensional envelope defined by a range of values.

GeneralEnvelope(org.opengis.spatialschema.geometry.Envelope envelope)
Constructs a new envelope with the same data than the specified envelope.

GeneralEnvelope(GeneralDirectPosition minCP, GeneralDirectPosition maxCP)
Constructs a envelope defined by two positions.

GeneralEnvelope(int dimension)
Constructs an empty envelope of the specified dimension.

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

Method Summary

void	add(org.opengis.spatialschema.geometry.DirectPosition position) Adds a point to this envelope.
void	add(org.opengis.spatialschema.geometry.Envelope envelope) Adds an envelope object to this envelope.
java.lang.Object	clone() Returns a deep copy of this envelope.
boolean	contains(org.opengis.spatialschema.geometry.DirectPosition position) Tests if a specified coordinate is inside the boundary of this envelope.
boolean	contains(org.opengis.spatialschema.geometry.Envelope envelope, boolean edgesInclusive) Returns if this envelope completly encloses the specified envelope.
boolean	equals(org.opengis.spatialschema.geometry.Envelope envelope, double eps) Compares to the specified envelope for equality with the specified tolerance value.
boolean	equals(java.lang.Object object) Compares the specified object with this envelope for equality.
org.opengis.spatialschema.geometry.DirectPosition	getCenter() A coordinate position consisting of all the middle ordinates for each dimension for all points within the .
double	getCenter(int dimension) Returns the center ordinate along the specified dimension.
org.opengis.referencing.crs.CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the coordinate reference system in which the coordinates are given.
int	getDimension() Returns the number of dimensions.
double	getLength(int dimension) Returns the envelope length along the specified dimension.
double	getLength(int dimension, javax.units.Unit unit) Returns the envelope length along the specified dimension, in terms of the given units.
org.opengis.spatialschema.geometry.DirectPosition	getLowerCorner() A coordinate position consisting of all the minimal ordinates for each dimension for all points within the .
double	getMaximum(int dimension) Returns the maximal 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.
GeneralEnvelope	getSubEnvelope(int lower, int upper) Returns a new envelope that encompass only some dimensions of this envelope.
org.opengis.spatialschema.geometry.DirectPosition	getUpperCorner() A coordinate position consisting of all the maximal ordinates for each dimension for all points within the .
int	hashCode() Returns a hash value for this envelope.
void	intersect(org.opengis.spatialschema.geometry.Envelope envelope) Sets this envelope to the intersection if this envelope with the specified one.
boolean	intersects(org.opengis.spatialschema.geometry.Envelope envelope, boolean edgesInclusive) Returns if this envelope intersects the specified envelope.
boolean	isEmpty() Determines whether or not this envelope is empty.
boolean	isInfinite() Returns if at least one ordinate has an infinite value.
boolean	isNull() Returns if at least one ordinate value is not NaN.
void	setCoordinateReferenceSystem(org.opengis.referencing.crs.CoordinateReferenceSystem crs) Set the coordinate reference system in which the coordinate are given.
void	setEnvelope(GeneralEnvelope envelope) Set this envelope to the same coordinate values than the specified envelope.
void	setRange(int dimension, double minimum, double maximum) Set 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.
java.awt.geom.Rectangle2D	toRectangle2D() Returns a Rectangle2D with the same bounds as this .
java.lang.String	toString() Returns a string representation of this envelope.

Methods inherited from class java.lang.Object

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

Constructor Detail

GeneralEnvelope

public GeneralEnvelope(org.opengis.spatialschema.geometry.Envelope envelope)

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

GeneralEnvelope

public GeneralEnvelope(org.opengis.referencing.crs.CoordinateReferenceSystem crs)

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

Since:

2.2

GeneralEnvelope

public GeneralEnvelope(int dimension)

Constructs an empty envelope of the specified dimension. All ordinates are initialized to 0.

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[] minCP,
                       double[] maxCP)
                throws org.opengis.spatialschema.geometry.MismatchedDimensionException

Constructs a envelope defined by two positions.

Parameters:

minCP - Minimum ordinate values.

maxCP - Maximum ordinate values.

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the two positions don't have the same dimension.

java.lang.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 minCP,
                       GeneralDirectPosition maxCP)
                throws org.opengis.spatialschema.geometry.MismatchedDimensionException

Constructs a envelope defined by two positions.

Parameters:

minCP - Point containing minimum ordinate values.

maxCP - Point containing maximum ordinate values.

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the two positions don't have the same dimension.

java.lang.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(java.awt.geom.Rectangle2D rect)

Constructs two-dimensional envelope defined by a Rectangle2D.

Method Detail

getCoordinateReferenceSystem

public final org.opengis.referencing.crs.CoordinateReferenceSystem getCoordinateReferenceSystem()

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

Returns:

The coordinate reference system, or .

setCoordinateReferenceSystem

public void setCoordinateReferenceSystem(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
                                  throws org.opengis.spatialschema.geometry.MismatchedDimensionException

Set the coordinate reference system in which the coordinate are given. Note: this method do not reproject the envelope.

Parameters:

crs - The new coordinate reference system, or .

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the specified CRS doesn't have the expected number of dimensions.

getDimension

public final int getDimension()

Returns the number of dimensions.

Specified by:

getDimension in interface org.opengis.spatialschema.geometry.Envelope

getLowerCorner

public org.opengis.spatialschema.geometry.DirectPosition getLowerCorner()

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

Specified by:

getLowerCorner in interface org.opengis.spatialschema.geometry.Envelope

Returns:

The lower corner.

getUpperCorner

public org.opengis.spatialschema.geometry.DirectPosition getUpperCorner()

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

Specified by:

getUpperCorner in interface org.opengis.spatialschema.geometry.Envelope

Returns:

The upper corner.

getCenter

public org.opengis.spatialschema.geometry.DirectPosition getCenter()

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

Since:

2.3

getMinimum

public final double getMinimum(int dimension)

Returns the minimal ordinate along the specified dimension.

Specified by:

getMinimum in interface org.opengis.spatialschema.geometry.Envelope

getMaximum

public final double getMaximum(int dimension)

Returns the maximal ordinate along the specified dimension.

Specified by:

getMaximum in interface org.opengis.spatialschema.geometry.Envelope

getCenter

public final double getCenter(int dimension)

Returns the center ordinate along the specified dimension.

Specified by:

getCenter in interface org.opengis.spatialschema.geometry.Envelope

getLength

public final double getLength(int dimension)

Returns the envelope length along the specified dimension. This length is equals to the maximum ordinate minus the minimal ordinate.

Specified by:

getLength in interface org.opengis.spatialschema.geometry.Envelope

getLength

public double getLength(int dimension,
                        javax.units.Unit unit)
                 throws javax.units.ConversionException

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

Parameters:

unit - The unit for the return value.

Returns:

The length in terms of the given unit.

Throws:

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

Since:

2.2

setRange

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

Set the envelope's 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.

setEnvelope

public void setEnvelope(GeneralEnvelope envelope)
                 throws org.opengis.spatialschema.geometry.MismatchedDimensionException

Set this envelope to the same coordinate values than the specified envelope.

Parameters:

envelope - The new envelope to copy coordinates from.

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the specified envelope doesn't have the expected number of dimensions.

Since:

2.2

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 if at least one ordinate has an 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 if at least one ordinate value is not NaN. The check is a little bit different than isEmpty() since it returns for a partially initialized envelope, while returns 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.

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 length is greater than 0 along all dimensions. Note that an empty envelope is always null, but the converse is not always true.

add

public void add(org.opengis.spatialschema.geometry.DirectPosition position)
         throws org.opengis.spatialschema.geometry.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.spatialschema.geometry.DirectPosition) with the added point as an argument will return , 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.

Parameters:

position - The point to add.

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the specified point doesn't have the expected dimension.

add

public void add(org.opengis.spatialschema.geometry.Envelope envelope)
         throws org.opengis.spatialschema.geometry.MismatchedDimensionException

Adds an envelope object to this envelope. The resulting envelope is the union of the two 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.

Parameters:

envelope - the to add to this envelope.

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the specified envelope doesn't have the expected dimension.

contains

public boolean contains(org.opengis.spatialschema.geometry.DirectPosition position)
                 throws org.opengis.spatialschema.geometry.MismatchedDimensionException

Tests if a specified coordinate is inside the boundary of this envelope.

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.

Parameters:

position - The point to text.

Returns:

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

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the specified point doesn't have the expected dimension.

contains

public boolean contains(org.opengis.spatialschema.geometry.Envelope envelope,
                        boolean edgesInclusive)
                 throws org.opengis.spatialschema.geometry.MismatchedDimensionException

Returns 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 only if is .

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.

Parameters:

envelope - The envelope to test for inclusion.

edgesInclusive - if this envelope edges are inclusive.

Returns:

if this envelope completly encloses the specified one.

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the specified envelope doesn't have the expected dimension.

Since:

2.2

See Also:

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

intersects

public boolean intersects(org.opengis.spatialschema.geometry.Envelope envelope,
                          boolean edgesInclusive)
                   throws org.opengis.spatialschema.geometry.MismatchedDimensionException

Returns 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 only if is .

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.

Parameters:

envelope - The envelope to test for intersection.

edgesInclusive - if this envelope edges are inclusive.

Returns:

if this envelope intersects the specified one.

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the specified envelope doesn't have the expected dimension.

Since:

2.2

See Also:

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

intersect

public void intersect(org.opengis.spatialschema.geometry.Envelope envelope)
               throws org.opengis.spatialschema.geometry.MismatchedDimensionException

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

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.

Parameters:

envelope - the to intersect to this envelope.

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the specified envelope doesn't have the expected dimension.

getSubEnvelope

public GeneralEnvelope getSubEnvelope(int lower,
                                      int upper)
                               throws java.lang.IndexOutOfBoundsException

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

Parameters:

lower - The first dimension to copy, inclusive.

upper - The last dimension to copy, exclusive.

Returns:

The subenvelope.

Throws:

java.lang.IndexOutOfBoundsException - if an index is out of bounds.

getReducedEnvelope

public GeneralEnvelope getReducedEnvelope(int lower,
                                          int upper)
                                   throws java.lang.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 subenvelope.

Throws:

java.lang.IndexOutOfBoundsException - if an index is out of bounds.

toRectangle2D

public java.awt.geom.Rectangle2D toRectangle2D()
                                        throws java.lang.IllegalStateException

Returns a Rectangle2D with the same bounds as this . This is a convenience method for interoperability with Java2D.

Throws:

java.lang.IllegalStateException - if this envelope is not two-dimensional.

toString

public java.lang.String toString()

Returns a string representation of this envelope. The default implementation formats the lower and upper corners using a shared instance of CoordinateFormat. This is okay for occasional formatting (for example for debugging purpose). But if there is a lot of positions to format, users will get better performance and more control by using their own instance of CoordinateFormat.

hashCode

public int hashCode()

Returns a hash value for this envelope. This value need not remain consistent between different implementations of the same class.

equals

public boolean equals(java.lang.Object object)

Compares the specified object with this envelope for equality.

equals

public boolean equals(org.opengis.spatialschema.geometry.Envelope envelope,
                      double eps)

Compares to the specified envelope for equality with the specified tolerance value. The tolerance value should be a small positive number. Its value is CRS dependent. For example should 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.

Since:

2.3

See Also:

contains(Envelope, boolean), intersects(Envelope, boolean)

clone

public java.lang.Object clone()

Returns a deep copy of this envelope.

Specified by:

clone in interface org.opengis.util.Cloneable