org.geotools.geometry
Class Envelope2D

java.lang.Object
  extended by java.awt.geom.RectangularShape
      extended by java.awt.geom.Rectangle2D
          extended by java.awt.geom.Rectangle2D.Double
              extended by org.geotools.geometry.Envelope2D
All Implemented Interfaces:
java.awt.Shape, java.io.Serializable, java.lang.Cloneable, BoundingBox, Envelope

public class Envelope2D
extends java.awt.geom.Rectangle2D.Double
implements BoundingBox, Envelope, Cloneable

A two-dimensional envelope on top of Rectangle2D. This implementation is provided for interoperability between Java2D and GeoAPI.

Note: This class inherits x and y fields. But despite their names, they don't need to be oriented toward East and North respectively. The (x,y) axis can have any orientation and should be understood as "ordinate 0" and "ordinate 1" values instead. This is not specific to this implementation; in Java2D too, the visual axis orientation depend on the affine transform in the graphics context.

Since:
2.1
Version:
8.0, $Id$
Author:
Martin Desruisseaux (IRD)
See Also:
GeneralEnvelope, ReferencedEnvelope, GeographicBoundingBox, Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class java.awt.geom.Rectangle2D
java.awt.geom.Rectangle2D.Double, java.awt.geom.Rectangle2D.Float
 
Field Summary
 
Fields inherited from class java.awt.geom.Rectangle2D.Double
height, width, x, y
 
Fields inherited from class java.awt.geom.Rectangle2D
OUT_BOTTOM, OUT_LEFT, OUT_RIGHT, OUT_TOP
 
Constructor Summary
Envelope2D()
          Constructs an initially empty envelope with no CRS.
Envelope2D(CoordinateReferenceSystem crs)
          Constructs an initially empty envelope with the defined CRS.
Envelope2D(CoordinateReferenceSystem crs, double x, double y, double width, double height)
          Constructs two-dimensional envelope defined by the specified coordinates.
Envelope2D(CoordinateReferenceSystem crs, java.awt.geom.Rectangle2D rect)
          Constructs two-dimensional envelope defined by an other Rectangle2D.
Envelope2D(DirectPosition2D minDP, DirectPosition2D maxDP)
          Constructs two-dimensional envelope defined by the specified coordinates.
Envelope2D(Envelope envelope)
          Constructs two-dimensional envelope defined by an other Envelope.
 
Method Summary
 boolean boundsEquals(Envelope that, int xDim, int yDim, double eps)
          Returns true if this envelope bounds is equals to that envelope bounds in two specified dimensions.
 boolean contains(BoundingBox bounds)
          Returns true if the provided bounds are contained by this bounding box.
 boolean contains(DirectPosition location)
          Returns true if the provided location is contained by this bounding box.
 boolean equals(java.lang.Object object)
          Compares the specified object with this envelope for equality.
 double getCenter(int dimension)
          Deprecated. Renamed as getMedian(int).
 CoordinateReferenceSystem getCoordinateReferenceSystem()
          Returns the coordinate reference system in which the coordinates are given.
 int getDimension()
          Returns the number of dimensions.
 double getLength(int dimension)
          Deprecated. Renamed as 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 median ordinate along the specified dimension.
 double getMinimum(int dimension)
          Returns the minimal ordinate along the specified dimension.
 double getSpan(int dimension)
          Returns the envelope span (typically width or height) 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 bounds)
          Includes the provided bounding box, expanding as necesary.
 void include(double x, double y)
          Includes the provided coordinates, expanding as necessary.
 boolean intersects(BoundingBox bounds)
          Returns true if the interior of this bounds intersects the interior of the provided bounds.
 void setBounds(BoundingBox bounds)
          Sets this bounding box to be the same as the specified box.
 void setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
          Set the coordinate reference system in which the coordinate are given.
 BoundingBox toBounds(CoordinateReferenceSystem targetCRS)
          Transforms this box to the specified CRS and returns a new bounding box for the transformed shape.
 java.lang.String toString()
          Returns a string representation of this envelope.
 
Methods inherited from class java.awt.geom.Rectangle2D.Double
createIntersection, createUnion, getBounds2D, getHeight, getWidth, getX, getY, isEmpty, outcode, setRect, setRect
 
Methods inherited from class java.awt.geom.Rectangle2D
add, add, add, contains, contains, getPathIterator, getPathIterator, intersect, intersects, intersectsLine, intersectsLine, outcode, setFrame, union
 
Methods inherited from class java.awt.geom.RectangularShape
clone, contains, contains, getBounds, getCenterX, getCenterY, getFrame, getMaxX, getMaxY, getMinX, getMinY, intersects, setFrame, setFrame, setFrameFromCenter, setFrameFromCenter, setFrameFromDiagonal, setFrameFromDiagonal
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.opengis.geometry.BoundingBox
contains, getHeight, getMaxX, getMaxY, getMinX, getMinY, getWidth, isEmpty
 
Methods inherited from interface org.opengis.util.Cloneable
clone
 

Constructor Detail

Envelope2D

public Envelope2D()
Constructs an initially empty envelope with no CRS.

Unlike a normal Envelope2D we set the width and height to -1 so we can tell the difference between:

Since:
2.5

Envelope2D

public Envelope2D(CoordinateReferenceSystem crs)
Constructs an initially empty envelope with the defined CRS.

Parameters:
crs - The coordinate reference system, or null.

Envelope2D

public Envelope2D(Envelope envelope)
Constructs two-dimensional envelope defined by an other Envelope.

Parameters:
envelope - The envelope to copy.

Envelope2D

public Envelope2D(CoordinateReferenceSystem crs,
                  java.awt.geom.Rectangle2D rect)
Constructs two-dimensional envelope defined by an other Rectangle2D.

Parameters:
crs - The coordinate reference system, or null.
rect - The rectangle to copy.

Envelope2D

public Envelope2D(CoordinateReferenceSystem crs,
                  double x,
                  double y,
                  double width,
                  double height)
Constructs two-dimensional envelope defined by the specified coordinates. Despite their name, the (x,y) coordinates don't need to be oriented toward (East, North). Those parameter names simply match the x and y fields. The actual axis orientations are determined by the specified CRS. See the class javadoc for details.

Parameters:
crs - The coordinate reference system, or null.
x - The x minimal value.
y - The y minimal value.
width - The envelope width.
height - The envelope height.

Envelope2D

public Envelope2D(DirectPosition2D minDP,
                  DirectPosition2D maxDP)
           throws MismatchedReferenceSystemException
Constructs two-dimensional envelope defined by the specified coordinates. Despite their name, the (x,y) coordinates don't need to be oriented toward (East, North). Those parameter names simply match the x and y fields. The actual axis orientations are determined by the specified CRS. See the class javadoc for details.

The minDP and maxDP arguments usually contains the minimal and maximal ordinate values respectively, but this is not mandatory. The ordinates will be rearanged as needed.

Parameters:
minDP - The fist position.
maxDP - The second position.
Throws:
MismatchedReferenceSystemException - if the two positions don't use the same CRS.
Since:
2.4
Method Detail

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)
Set the coordinate reference system in which the coordinate are given.

Parameters:
crs - The new coordinate reference system, or null.

getDimension

public final int getDimension()
Returns the number of dimensions.

Specified by:
getDimension in interface Envelope
Returns:
The dimensionality of this envelope.

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.

getMinimum

public final double getMinimum(int dimension)
                        throws java.lang.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:
java.lang.IndexOutOfBoundsException - If the given index is out of bounds.
See Also:
RectangularShape.getMinX(), RectangularShape.getMinY()

getMaximum

public final double getMaximum(int dimension)
                        throws java.lang.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:
java.lang.IndexOutOfBoundsException - If the given index is out of bounds.
See Also:
RectangularShape.getMaxX(), RectangularShape.getMaxY()

getCenter

@Deprecated
public final double getCenter(int dimension)
Deprecated. Renamed as getMedian(int).

Returns the center ordinate along the specified dimension.

Parameters:
dimension - The dimension to query.
Returns:
The mid ordinate value along the given dimension.

getMedian

public final double getMedian(int dimension)
                       throws java.lang.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:
java.lang.IndexOutOfBoundsException - If the given index is out of bounds.
See Also:
RectangularShape.getCenterX(), RectangularShape.getCenterY()

getLength

@Deprecated
public final double getLength(int dimension)
Deprecated. Renamed as getSpan(int).

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

Parameters:
dimension - The dimension to query.
Returns:
The difference along maximal and minimal ordinates in the given dimension.

getSpan

public final double getSpan(int dimension)
                     throws java.lang.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:
java.lang.IndexOutOfBoundsException - If the given index is out of bounds.
See Also:
RectangularShape.getWidth(), RectangularShape.getHeight()

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 java.awt.geom.Rectangle2D

equals

public boolean equals(java.lang.Object object)
Compares the specified object with this envelope for equality.

Overrides:
equals in class java.awt.geom.Rectangle2D
Parameters:
object - The object to compare with this envelope.
Returns:
true if the given object is equals to this envelope.

boundsEquals

public boolean boundsEquals(Envelope that,
                            int xDim,
                            int yDim,
                            double eps)
Returns true if this envelope bounds is equals to that envelope bounds in two specified dimensions. The coordinate reference system is not compared, since it doesn't need to have the same number of dimensions.

Parameters:
that - The envelope to compare to.
xDim - The dimension of that envelope to compare to the x dimension of this envelope.
yDim - The dimension of that envelope to compare to the y dimension of this envelope.
eps - A small tolerance number for floating point number comparaisons. This value will be scaled according this envelope width and height.
Returns:
true if the envelope bounds are the same (up to the specified tolerance level) in the specified dimensions, or false otherwise.

toString

public java.lang.String toString()
Returns a string representation of this envelope. The default implementation is okay for occasional formatting (for example for debugging purpose). But if there is a lot of envelopes to format, users will get more control by using their own instance of CoordinateFormat.

Overrides:
toString in class java.awt.geom.Rectangle2D.Double
Since:
2.4

setBounds

public void setBounds(BoundingBox bounds)
Description copied from interface: BoundingBox
Sets this bounding box to be the same as the specified box.

Specified by:
setBounds in interface BoundingBox
Parameters:
bounds - The new bounds.

include

public void include(BoundingBox bounds)
Description copied from interface: BoundingBox
Includes the provided bounding box, expanding as necesary.

Specified by:
include in interface BoundingBox
Parameters:
bounds - The bounds to add to this geographic bounding box.

include

public void include(double x,
                    double y)
Description copied from interface: BoundingBox
Includes the provided coordinates, expanding as necessary. Note that there is no guarantee that the (x, x) values are oriented toward (East, North), since it depends on the envelope CRS.

Specified by:
include in interface BoundingBox
Parameters:
x - The first ordinate value.
y - The second ordinate value.

intersects

public boolean intersects(BoundingBox bounds)
Returns true if the interior of this bounds intersects the interior of the provided bounds.

Note this method conflicts with RectangularShape.intersects(Rectangle2D) so you may need to call it via envelope2d.intersects( (Envelope2D) bounds ) in order to correctly check that the coordinate reference systems match.

Specified by:
intersects in interface BoundingBox
Parameters:
bounds - The bounds to test for intersection.
Returns:
true if the two bounds intersect.

contains

public boolean contains(BoundingBox bounds)
Description copied from interface: BoundingBox
Returns true if the provided bounds are contained by this bounding box.

Specified by:
contains in interface BoundingBox
Parameters:
bounds - The bounds to test for inclusion.
Returns:
true if the given bounds is inside this bounds.

contains

public boolean contains(DirectPosition location)
Description copied from interface: BoundingBox
Returns true if the provided location is contained by this bounding box.

Specified by:
contains in interface BoundingBox
Parameters:
location - The direct position to test for inclusion.
Returns:
true if the given position is inside this bounds.

toBounds

public BoundingBox toBounds(CoordinateReferenceSystem targetCRS)
                     throws TransformException
Description copied from interface: BoundingBox
Transforms this box to the specified CRS and returns a new bounding box for the transformed shape. This method provides a convenient (while not always efficient) way to get minimum and maximum ordinate values toward some specific axis directions, typically East and North.

Example: if box is a bounding box using a geographic CRS with WGS84 datum, then one can write:

 GeographicCRS targetCRS   = crsAuthorityFactory.createGeographicCRS("EPSG:4326");
 BoundingBox   targetBox   = box.toBounds(targetCRS);
 double        minEasting  = targetBox.getMinY();
 double        minNorthing = targetBox.getMinX();
 
Be aware that "EPSG:4326" has (latitude, longitude) axis order, thus the inversion of X and Y in the above code.

Sophesticated applications will typically provide more efficient way to perform similar transformations in their context. For example Canvas store precomputed objective to display transforms.

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.


Copyright © 1996-2014 Geotools. All Rights Reserved.