org.geotools.geometry.jts
Class ReferencedEnvelope

Object
  extended by Envelope
      extended by ReferencedEnvelope
All Implemented Interfaces:
Serializable, 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
protected  CoordinateReferenceSystem crs
          The coordinate reference system, or null.
static ReferencedEnvelope EVERYTHING
          A ReferencedEnvelope containing "everything"
 
Constructor Summary
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
 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(ReferencedEnvelope origional)
          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).
 CoordinateReferenceSystem crs()
          Deprecated. Use getCoordinateReferenceSystem(), since it is the method inherited from the interface.
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.
 double getCenter(int dimension)
          Deprecated. Use getMedian(int).
 CoordinateReferenceSystem getCoordinateReferenceSystem()
          Returns the coordinate reference system associated with this envelope.
 int getDimension()
          Returns the number of dimensions.
 double getLength(int dimension)
          Deprecated. Use getSpan(int).
 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.
 Envelope 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.
 double maxX()
          Deprecated. Use Envelope.getMaxX().
 double maxY()
          Deprecated. Use Envelope.getMaxY().
 double minX()
          Deprecated. Use Envelope.getMinX().
 double minY()
          Deprecated. Use Envelope.getMinY().
static ReferencedEnvelope reference(BoundingBox e)
          Cast to a ReferencedEnvelope (used to ensure that an Envelope if a ReferencedEnvelope).
static ReferencedEnvelope reference(Envelope e)
          Cast to a ReferencedEnvelope (used to ensure that an Envelope if 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, contains, contains, contains, covers, covers, covers, distance, expandBy, expandBy, expandToInclude, expandToInclude, getArea, getHeight, getMaxX, getMaxY, getMinX, getMinY, getWidth, init, init, init, init, init, 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.

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.

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.

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.

Parameters:
location -
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.

crs

public CoordinateReferenceSystem crs()
Deprecated. Use getCoordinateReferenceSystem(), since it is the method inherited from the interface.


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

minX

public double minX()
Deprecated. Use Envelope.getMinX().


minY

public double minY()
Deprecated. Use Envelope.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()

maxX

public double maxX()
Deprecated. Use Envelope.getMaxX().


maxY

public double maxY()
Deprecated. Use Envelope.getMaxY().


getCenter

public double getCenter(int dimension)
Deprecated. Use getMedian(int).


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

getLength

public double getLength(int dimension)
Deprecated. Use getSpan(int).


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

Parameters:
pt -

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:

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 origional)
Factory method to create the correct ReferencedEnvelope.

Parameters:
origional - 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

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

reference

public static ReferencedEnvelope reference(Envelope e)
Cast to a ReferencedEnvelope (used to ensure that an Envelope if 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(BoundingBox e)
Cast to a ReferencedEnvelope (used to ensure that an Envelope if 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.
Returns:

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

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


Copyright © 1996-2014 Geotools. All Rights Reserved.