org.geotools.geometry.jts

Class ReferencedEnvelope

Object

Envelope

ReferencedEnvelope

All Implemented Interfaces:

Serializable, Comparable, BoundingBox, Envelope

Direct Known Subclasses:

ReferencedEnvelope3D

public class ReferencedEnvelope
extends Envelope
implements Envelope, BoundingBox

A JTS envelope associated with a coordinate reference system. In addition, this JTS envelope also implements the GeoAPI envelope interface for interoperability with GeoAPI.

Since:

2.2

Author:

Jody Garnett, Martin Desruisseaux, Simone Giannecchini

See Also:

Envelope2D, GeneralEnvelope, GeographicBoundingBox, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected CoordinateReferenceSystem	crs The coordinate reference system, or null.
static ReferencedEnvelope	EVERYTHING A ReferencedEnvelope containing "everything"

Constructor Summary

Constructors

Constructor and Description
ReferencedEnvelope() Creates a null envelope with a null coordinate reference system.
ReferencedEnvelope(BoundingBox bbox) Creates a new envelope from an existing bounding box.
ReferencedEnvelope(CoordinateReferenceSystem crs) Creates a null envelope with the specified coordinate reference system.
ReferencedEnvelope(double x1, double x2, double y1, double y2, CoordinateReferenceSystem crs) Creates an envelope for a region defined by maximum and minimum values.
ReferencedEnvelope(Envelope envelope) Creates a new envelope from an existing OGC envelope.
ReferencedEnvelope(Envelope envelope, CoordinateReferenceSystem crs) Creates a new envelope from an existing JTS envelope.
ReferencedEnvelope(Rectangle2D rectangle, CoordinateReferenceSystem crs) Creates an envelope for a Java2D rectangle.
ReferencedEnvelope(ReferencedEnvelope envelope) Creates a new envelope from an existing envelope.

Method Summary

Modifier and Type	Method and Description
boolean	boundsEquals2D(Envelope other, double eps) Compare the bounds of this envelope with those of another.
protected void	checkCoordinateReferenceSystemDimension() Convenience method for checking coordinate reference system validity.
boolean	contains(BoundingBox bbox) Returns true if the provided bounds are contained by this bounding box.
boolean	contains(DirectPosition pos) Returns true if the provided location is contained by this bounding box.
static ReferencedEnvelope	create(CoordinateReferenceSystem crs) Factory method to create the correct ReferencedEnvelope implementation for the provided CoordinateReferenceSystem.
static ReferencedEnvelope	create(Envelope env, CoordinateReferenceSystem crs) Utility method to create a ReferencedEnvelope from an opengis Envelope class, supporting 2d as well as 3d envelopes (returning the right class).
static ReferencedEnvelope	create(Envelope env, CoordinateReferenceSystem crs) Utility method to create a ReferencedEnvelope from an JTS Envelope class, supporting 2d as well as 3d envelopes (returning the right class).
static ReferencedEnvelope	create(Rectangle2D rectangle, CoordinateReferenceSystem crs) Utility method to create a ReferencedEnvelope from a Java2D Rectangle class, supporting empty rectangles.
static ReferencedEnvelope	create(ReferencedEnvelope original) Factory method to create the correct ReferencedEnvelope.
static ReferencedEnvelope	create(ReferencedEnvelope env, CoordinateReferenceSystem crs) Utility method to create a ReferencedEnvelope from an opengis Envelope class, supporting 2d as well as 3d envelopes (returning the right class).
protected void	ensureCompatibleReferenceSystem(BoundingBox bbox) Make sure that the specified bounding box uses the same CRS than this one.
protected void	ensureCompatibleReferenceSystem(DirectPosition location) Make sure that the specified location uses the same CRS as this one.
boolean	equals(Object object) Compares the specified object with this envelope for equality.
void	expandToInclude(DirectPosition pt) Expand to include the provided DirectPosition
void	expandToInclude(Envelope other) Include the provided envelope, expanding as necessary.
CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the coordinate reference system associated with this envelope.
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.
double	getMedian(int dimension) Returns the center ordinate along the specified dimension.
double	getMinimum(int dimension) Returns the minimal ordinate along the specified dimension.
double	getSpan(int dimension) Returns the envelope length along the specified dimension.
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	include(BoundingBox bbox) Include the provided bounding box, expanding as necessary.
void	include(double x, double y) Include the provided coordinates, expanding as necessary.
void	init(BoundingBox bounds) Sets this envelope to the specified bounding box.
ReferencedEnvelope	intersection(Envelope env) Check if this bounding box intersects the provided bounds.
boolean	intersects(BoundingBox bbox) Check if this bounding box intersects the provided bounds.
boolean	isEmpty() Returns true if lengths along all dimension are zero.
static ReferencedEnvelope	reference(Envelope e) Cast to a ReferencedEnvelope (used to ensure that an Envelope is a ReferencedEnvelope).
static ReferencedEnvelope	reference(Envelope env) Cast to a ReferencedEnvelope (used to ensure that an Envelope if a ReferencedEnvelope).
static ReferencedEnvelope	reference(ReferencedEnvelope e) Utility method to ensure that an BoundingBox in a ReferencedEnvelope.
void	setBounds(BoundingBox bbox) Initialize the bounding box with another bounding box.
BoundingBox	toBounds(CoordinateReferenceSystem targetCRS) Returns a new bounding box which contains the transformed shape of this bounding box.
String	toString() Returns a string representation of this envelope.
ReferencedEnvelope	transform(CoordinateReferenceSystem targetCRS, boolean lenient) Transforms the referenced envelope to the specified coordinate reference system.
ReferencedEnvelope	transform(CoordinateReferenceSystem targetCRS, boolean lenient, int numPointsForTransformation) Transforms the referenced envelope to the specified coordinate reference system using the specified amount of points.

Methods inherited from class Envelope

centre, compareTo, contains, contains, contains, copy, covers, covers, covers, disjoint, distance, expandBy, expandBy, expandToInclude, expandToInclude, getArea, getDiameter, getHeight, getMaxX, getMaxY, getMinX, getMinY, getWidth, init, init, init, init, init, intersects, intersects, intersects, intersects, intersects, intersects, isNull, maxExtent, minExtent, overlaps, overlaps, overlaps, setToNull, translate

Methods inherited from class Object

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

Methods inherited from interface BoundingBox

contains, getHeight, getMaxX, getMaxY, getMinX, getMinY, getWidth

Field Detail

EVERYTHING

public static ReferencedEnvelope EVERYTHING

A ReferencedEnvelope containing "everything"

crs

protected CoordinateReferenceSystem crs

The coordinate reference system, or null.

Constructor Detail

ReferencedEnvelope

public ReferencedEnvelope()

Creates a null envelope with a null coordinate reference system.

ReferencedEnvelope

public ReferencedEnvelope(CoordinateReferenceSystem crs)
                   throws MismatchedDimensionException

Creates a null envelope with the specified coordinate reference system.

Parameters:

crs - The coordinate reference system.

Throws:

MismatchedDimensionException - if the CRS dimension is not valid.

ReferencedEnvelope

public ReferencedEnvelope(double x1,
                          double x2,
                          double y1,
                          double y2,
                          CoordinateReferenceSystem crs)
                   throws MismatchedDimensionException

Creates an envelope for a region defined by maximum and minimum values.

Parameters:

x1 - The first x-value.

x2 - The second x-value.

y1 - The first y-value.

y2 - The second y-value.

crs - The coordinate reference system.

Throws:

MismatchedDimensionException - if the CRS dimension is not valid.

ReferencedEnvelope

public ReferencedEnvelope(Rectangle2D rectangle,
                          CoordinateReferenceSystem crs)
                   throws MismatchedDimensionException

Creates an envelope for a Java2D rectangle.

NOTE: if the rectangle is empty, the resulting ReferencedEnvelope will not be. In case this is needed use ReferencedEnvelope.create(rectangle, crs)

Parameters:

rectangle - The rectangle.

crs - The coordinate reference system.

Throws:

MismatchedDimensionException - if the CRS dimension is not valid.

Since:

2.4

ReferencedEnvelope

public ReferencedEnvelope(ReferencedEnvelope envelope)
                   throws MismatchedDimensionException

Creates a new envelope from an existing envelope.

Parameters:

envelope - The envelope to initialize from

Throws:

MismatchedDimensionException - if the CRS dimension is not valid.

Since:

2.3

ReferencedEnvelope

public ReferencedEnvelope(BoundingBox bbox)
                   throws MismatchedDimensionException

Creates a new envelope from an existing bounding box.

NOTE: if the bounding box is empty, the resulting ReferencedEnvelope will not be. In case this is needed use ReferencedEnvelope.create(bbox, bbox.getCoordinateReferenceSystem())

Parameters:

bbox - The bounding box to initialize from.

Throws:

MismatchedDimensionException - if the CRS dimension is not valid.

Since:

2.4

ReferencedEnvelope

public ReferencedEnvelope(Envelope envelope)
                   throws MismatchedDimensionException

Creates a new envelope from an existing OGC envelope.

NOTE: if the envelope is empty, the resulting ReferencedEnvelope will not be. In case this is needed use ReferencedEnvelope.create(envelope, envelope.getCoordinateReferenceSystem())

Parameters:

envelope - The envelope to initialize from.

Throws:

MismatchedDimensionException - if the CRS dimension is not valid.

Since:

2.4

ReferencedEnvelope

public ReferencedEnvelope(Envelope envelope,
                          CoordinateReferenceSystem crs)
                   throws MismatchedDimensionException

Creates a new envelope from an existing JTS envelope.

Parameters:

envelope - The envelope to initialize from.

crs - The coordinate reference system.

Throws:

MismatchedDimensionExceptionif - the CRS dimension is not valid.

MismatchedDimensionException

Method Detail

init

public void init(BoundingBox bounds)

Sets this envelope to the specified bounding box.

checkCoordinateReferenceSystemDimension

protected void checkCoordinateReferenceSystemDimension()
                                                throws MismatchedDimensionException

Convenience method for checking coordinate reference system validity.

Throws:

IllegalArgumentException - if the CRS dimension is not valid.

MismatchedDimensionException

ensureCompatibleReferenceSystem

protected void ensureCompatibleReferenceSystem(BoundingBox bbox)
                                        throws MismatchedReferenceSystemException

Make sure that the specified bounding box uses the same CRS than this one.

Parameters:

bbox - The other bounding box to test for compatibility.

Throws:

MismatchedReferenceSystemException - if the CRS are incompatible.

ensureCompatibleReferenceSystem

protected void ensureCompatibleReferenceSystem(DirectPosition location)

Make sure that the specified location uses the same CRS as this one.

Throws:

MismatchedReferenceSystemException - if the CRS are incompatible.

getCoordinateReferenceSystem

public CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the coordinate reference system associated with this envelope.

Specified by:

getCoordinateReferenceSystem in interface Envelope

Returns:

The envelope CRS, or null if unknown.

getDimension

public int getDimension()

Returns the number of dimensions.

Specified by:

getDimension in interface Envelope

Returns:

The dimensionality of this envelope.

getMinimum

public double getMinimum(int dimension)

Returns the minimal ordinate along the specified dimension.

Specified by:

getMinimum in interface Envelope

Parameters:

dimension - The dimension for which to obtain the ordinate value.

Returns:

The minimal ordinate at the given dimension.

See Also:

RectangularShape.getMinX(), RectangularShape.getMinY()

getMaximum

public double getMaximum(int dimension)

Returns the maximal ordinate along the specified dimension.

Specified by:

getMaximum in interface Envelope

Parameters:

dimension - The dimension for which to obtain the ordinate value.

Returns:

The maximal ordinate at the given dimension.

See Also:

RectangularShape.getMaxX(), RectangularShape.getMaxY()

getMedian

public double getMedian(int dimension)

Returns the center ordinate along the specified dimension.

Specified by:

getMedian in interface Envelope

Parameters:

dimension - The dimension for which to obtain the ordinate value.

Returns:

The median ordinate at the given dimension.

See Also:

RectangularShape.getCenterX(), RectangularShape.getCenterY()

getSpan

public double getSpan(int dimension)

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

Specified by:

getSpan in interface Envelope

Parameters:

dimension - The dimension for which to obtain the ordinate value.

Returns:

The span (typically width or height) at the given dimension.

See Also:

RectangularShape.getWidth(), RectangularShape.getHeight()

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

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

Returns:

The upper corner.

isEmpty

public boolean isEmpty()

Returns true if lengths along all dimension are zero.

Specified by:

isEmpty in interface BoundingBox

Returns:

true if this bounding box is empty.

Since:

2.4

contains

public boolean contains(DirectPosition pos)

Returns true if the provided location is contained by this bounding box.

Specified by:

contains in interface BoundingBox

Parameters:

pos - The direct position to test for inclusion.

Returns:

true if the given position is inside this bounds.

Since:

2.4

contains

public boolean contains(BoundingBox bbox)

Returns true if the provided bounds are contained by this bounding box.

Specified by:

contains in interface BoundingBox

Parameters:

bbox - The bounds to test for inclusion.

Returns:

true if the given bounds is inside this bounds.

Since:

2.4

intersects

public boolean intersects(BoundingBox bbox)

Check if this bounding box intersects the provided bounds.

Specified by:

intersects in interface BoundingBox

Parameters:

bbox - The bounds to test for intersection.

Returns:

true if the two bounds intersect.

Since:

2.4

intersection

public ReferencedEnvelope intersection(Envelope env)

Check if this bounding box intersects the provided bounds.

Overrides:

intersection in class Envelope

include

public void include(BoundingBox bbox)

Include the provided bounding box, expanding as necessary.

Specified by:

include in interface BoundingBox

Parameters:

bbox - The bounds to add to this geographic bounding box.

Since:

2.4

expandToInclude

public void expandToInclude(DirectPosition pt)

Expand to include the provided DirectPosition

expandToInclude

public void expandToInclude(Envelope other)

Include the provided envelope, expanding as necessary.

Overrides:

expandToInclude in class Envelope

include

public void include(double x,
                    double y)

Include the provided coordinates, expanding as necessary.

Specified by:

include in interface BoundingBox

Parameters:

x - The first ordinate value.

y - The second ordinate value.

Since:

2.4

setBounds

public void setBounds(BoundingBox bbox)

Initialize the bounding box with another bounding box.

Specified by:

setBounds in interface BoundingBox

Parameters:

bbox - The new bounds.

Since:

2.4

toBounds

public BoundingBox toBounds(CoordinateReferenceSystem targetCRS)
                     throws TransformException

Returns a new bounding box which contains the transformed shape of this bounding box. This is a convenience method that delegate its work to the transform method.

Specified by:

toBounds in interface BoundingBox

Parameters:

targetCRS - The target CRS for the bounding box to be returned.

Returns:

A new bounding box wich includes the shape of this box transformed to the specified target CRS.

Throws:

TransformException - if no transformation path has been found from this box CRS to the specified target CRS, or if the transformation failed for an other reason.

Since:

2.4

transform

public ReferencedEnvelope transform(CoordinateReferenceSystem targetCRS,
                                    boolean lenient)
                             throws TransformException,
                                    FactoryException

Transforms the referenced envelope to the specified coordinate reference system.

This method can handle the case where the envelope contains the North or South pole, or when it cross the ±180� longitude.

Parameters:

targetCRS - The target coordinate reference system.

lenient - true if datum shift should be applied even if there is insuffisient information. Otherwise (if false), an exception is thrown in such case.

Returns:

The transformed envelope.

Throws:

FactoryException - if the math transform can't be determined.

TransformException - if at least one coordinate can't be transformed.

See Also:

CRS.transform(CoordinateOperation, org.opengis.geometry.Envelope)

transform

public ReferencedEnvelope transform(CoordinateReferenceSystem targetCRS,
                                    boolean lenient,
                                    int numPointsForTransformation)
                             throws TransformException,
                                    FactoryException

Transforms the referenced envelope to the specified coordinate reference system using the specified amount of points.

This method can handle the case where the envelope contains the North or South pole, or when it cross the ±180� longitude.

Parameters:

targetCRS - The target coordinate reference system.

lenient - true if datum shift should be applied even if there is insuffisient information. Otherwise (if false), an exception is thrown in such case.

numPointsForTransformation - The number of points to use for sampling the envelope.

Returns:

The transformed envelope.

Throws:

FactoryException - if the math transform can't be determined.

TransformException - if at least one coordinate can't be transformed.

Since:

2.3

See Also:

CRS.transform(CoordinateOperation, org.opengis.geometry.Envelope)

hashCode

public int hashCode()

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

Overrides:

hashCode in class Envelope

equals

public boolean equals(Object object)

Compares the specified object with this envelope for equality.

Overrides:

equals in class Envelope

boundsEquals2D

public boolean boundsEquals2D(Envelope other,
                              double eps)

Compare the bounds of this envelope with those of another.

Note: in this test:

• the coordinate reference systems of the envelopes are not examined
• only the first two dimensions of the envelopes are compared
• it is assumed that each dimension equates to the same axis for both envelopes

Parameters:

other - other envelope

eps - a small tolerance factor (e.g. 1.0e-6d) which will be scaled relative to this envlope's width and height

Returns:

true if all bounding coordinates are equal within the set tolerance; false otherwise

toString

public String toString()

Returns a string representation of this envelope. The default implementation is okay for occasional formatting (for example for debugging purpose).

Overrides:

toString in class Envelope

create

public static ReferencedEnvelope create(ReferencedEnvelope original)

Factory method to create the correct ReferencedEnvelope.

Parameters:

original - ReferencedEnvelope being duplicated

Returns:

ReferencedEnvelope, ReferencedEnvelope3D if it is 3d

create

public static ReferencedEnvelope create(CoordinateReferenceSystem crs)

Factory method to create the correct ReferencedEnvelope implementation for the provided CoordinateReferenceSystem.

Parameters:

crs - CoordinateReferenceSystem used to select ReferencedEnvelope implementation

Returns:

ReferencedEnvelope, ReferencedEnvelope3D if it is 3d

create

public static ReferencedEnvelope create(Envelope env,
                                        CoordinateReferenceSystem crs)

Utility method to create a ReferencedEnvelope from an opengis Envelope class, supporting 2d as well as 3d envelopes (returning the right class).

Parameters:

env - The opgenis Envelope object

Returns:

ReferencedEnvelope, ReferencedEnvelope3D if it is 3d,
results in a null/an empty envelope, if input envelope was a null/an empty envelope

See Also:

#reference(org.opengis.geometry.Envelope)}

create

public static ReferencedEnvelope create(ReferencedEnvelope env,
                                        CoordinateReferenceSystem crs)

Utility method to create a ReferencedEnvelope from an opengis Envelope class, supporting 2d as well as 3d envelopes (returning the right class).

Parameters:

env - The opgenis Envelope object

Returns:

ReferencedEnvelope, ReferencedEnvelope3D if it is 3d

create

public static ReferencedEnvelope create(Envelope env,
                                        CoordinateReferenceSystem crs)

Utility method to create a ReferencedEnvelope from an JTS Envelope class, supporting 2d as well as 3d envelopes (returning the right class).

Parameters:

env - The JTS Envelope object

Returns:

ReferencedEnvelope, ReferencedEnvelope3D if it is 3d,
results in a null/an empty envelope, if input envelope was a null/an empty envelope

reference

public static ReferencedEnvelope reference(Envelope e)

Cast to a ReferencedEnvelope (used to ensure that an Envelope is a ReferencedEnvelope).

This method first checks if e is an instanceof ReferencedEnvelope, if it is, itself is returned. If not new ReferencedEnvelpe(e,null) is returned.

If e is null, null is returned.

Parameters:

e - The envelope. Can be null.

Returns:

A ReferencedEnvelope using the specified envelope, or null if the envelope was null.

reference

public static ReferencedEnvelope reference(ReferencedEnvelope e)

Utility method to ensure that an BoundingBox in a ReferencedEnvelope.

This method first checks if e is an instanceof ReferencedEnvelope, if it is, itself is returned. If not new ReferencedEnvelpe(e) is returned.

Parameters:

e - The envelope.

reference

public static ReferencedEnvelope reference(Envelope env)

Cast to a ReferencedEnvelope (used to ensure that an Envelope if a ReferencedEnvelope). Supporting 2d as well as 3d envelopes (returning the right class).

Parameters:

env - The opgenis Envelope object

Returns:

ReferencedEnvelope, ReferencedEnvelope3D if it is 3d,
results in a null/an empty envelope, if input envelope was a null/an empty envelope (by JTS Envelope definition: getMaximum(0) < getMinimum(0))

create

public static ReferencedEnvelope create(Rectangle2D rectangle,
                                        CoordinateReferenceSystem crs)

Utility method to create a ReferencedEnvelope from a Java2D Rectangle class, supporting empty rectangles.

Parameters:

rectangle - The Java2D Rectangle object

Returns:

ReferencedEnvelope,
results in a null/an empty envelope, if input rectangle was empty