org.geotoolkit.geometry
Class Envelope2D

Object
  RectangularShape
      Rectangle2D
          Rectangle2D.Double
              Envelope2D

All Implemented Interfaces:

Shape, Serializable, Cloneable, Envelope

public class Envelope2D
extends Rectangle2D.Double
implements Envelope, Cloneable

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

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.

Spanning the anti-meridian of a Geographic CRS
The Web Coverage Service (WCS) specification authorizes (with special treatment) cases where upper < lower at least in the longitude case. They are envelopes spanning the anti-meridian, like the red box below (the green box is the usual case). For Envelope2D objects, they are rectangle with negative width or height field values. The default implementation of methods listed in the right column can handle such cases.

Supported methods: getMinimum(int) getMaximum(int) getSpan(int) getMedian(int) isEmpty() contains(double,double) contains(Rectangle2D) and its variant receiving double arguments intersects(Rectangle2D) and its variant receiving double arguments createIntersection(Rectangle2D) createUnion(Rectangle2D) add(Rectangle2D) add(double,double)

The getMinX(), getMinY(), getMaxX(), getMaxY(), getCenterX(), getCenterY(), getWidth() and getHeight() methods delegate to the above-cited methods.

Since:

2.1

Version:

3.20

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

GeneralEnvelope, org.geotoolkit.geometry.jts.ReferencedEnvelope, GeographicBoundingBox, Serialized Form

Module:

referencing/geotk-referencing (download)

View source code for this class

Nested Class Summary

Nested classes/interfaces inherited from class Rectangle2D

Rectangle2D.Double, Rectangle2D.Float

Field Summary

Fields inherited from class Rectangle2D.Double

height, width, x, y

Fields inherited from class Rectangle2D

OUT_BOTTOM, OUT_LEFT, OUT_RIGHT, OUT_TOP

Constructor Summary

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

Envelope2D(CoordinateReferenceSystem crs, double x, double y, double width, double height)
Constructs two-dimensional envelope defined by the specified coordinates.

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

Envelope2D(DirectPosition lower, DirectPosition upper)
Constructs two-dimensional envelope defined by the specified coordinates.

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

Envelope2D(GeographicBoundingBox box)
Constructs a new envelope with the same data than the specified geographic bounding box.

Method Summary

void	add(double px, double py) Adds a point to this rectangle.
void	add(Rectangle2D rect) Adds an other rectangle to this rectangle.
boolean	boundsEquals(Envelope that, int xDim, int yDim, double eps) Returns true if this envelope bounds is equal to that envelope bounds in two specified dimensions.
boolean	contains(double px, double py) Tests if a specified coordinate is inside the boundary of this envelope.
boolean	contains(double rx, double ry, double rw, double rh) Returns true if this envelope completely encloses the specified rectangle.
boolean	contains(Rectangle2D rect) Returns true if this envelope completely encloses the specified rectangle.
Envelope2D	createIntersection(Rectangle2D rect) Returns the intersection of this envelope with the specified rectangle.
Envelope2D	createUnion(Rectangle2D rect) Returns the union of this envelope with the specified rectangle.
boolean	equals(Object object) Compares the specified object with this envelope for equality.
double	getCenterX() Returns the median ordinate value for dimension 0.
double	getCenterY() Returns the median ordinate value for dimension 1.
CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the coordinate reference system in which the coordinates are given.
int	getDimension() Returns the number of dimensions, which is always 2.
double	getHeight() Returns the span for dimension 1.
DirectPosition2D	getLowerCorner() A coordinate position consisting of all the starting ordinates for each dimension for all points within the Envelope.
double	getMaximum(int dimension) Returns the maximal ordinate along the specified dimension.
double	getMaxX() Returns the maximal ordinate value for dimension 0.
double	getMaxY() Returns the maximal ordinate value for dimension 1.
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	getMinX() Returns the minimal ordinate value for dimension 0.
double	getMinY() Returns the minimal ordinate value for dimension 1.
double	getSpan(int dimension) Returns the envelope span along the specified dimension.
DirectPosition2D	getUpperCorner() A coordinate position consisting of all the ending ordinates for each dimension for all points within the Envelope.
double	getWidth() Returns the span for dimension 0.
boolean	intersects(double rx, double ry, double rw, double rh) Returns true if this envelope intersects the specified envelope.
boolean	intersects(Rectangle2D rect) Returns true if this envelope intersects the specified envelope.
boolean	isEmpty() Determines whether the envelope is empty.
void	setCoordinateReferenceSystem(CoordinateReferenceSystem crs) Sets the coordinate reference system in which the coordinate are given.
void	setEnvelope(Envelope envelope) Sets this envelope to the same values than the given Envelope.
String	toString() Formats this envelope in the Well Known Text (WKT) format.

Methods inherited from class Rectangle2D.Double

getBounds2D, getX, getY, outcode, setRect, setRect

Methods inherited from class Rectangle2D

add, getPathIterator, getPathIterator, hashCode, intersect, intersectsLine, intersectsLine, outcode, setFrame, union

Methods inherited from class RectangularShape

clone, contains, getBounds, getFrame, setFrame, setFrame, setFrameFromCenter, setFrameFromCenter, setFrameFromDiagonal, setFrameFromDiagonal

Methods inherited from class Object

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

Methods inherited from interface Cloneable

clone

Constructor Detail

Envelope2D

public Envelope2D()

Constructs an initially empty envelope with no CRS.

Since:

2.5

Envelope2D

public Envelope2D(Envelope envelope)
           throws MismatchedDimensionException

Constructs two-dimensional envelope defined by an other Envelope.

Parameters:

envelope - The envelope to copy.

Throws:

MismatchedDimensionException - If the given envelope is not two-dimensional.

See Also:

GeneralEnvelope.GeneralEnvelope(Envelope)

Envelope2D

public Envelope2D(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:

3.11

See Also:

GeneralEnvelope.GeneralEnvelope(GeographicBoundingBox)

Envelope2D

public Envelope2D(CoordinateReferenceSystem crs,
                  Rectangle2D rect)

Constructs two-dimensional envelope defined by an other Rectangle2D. If the given rectangle has negative width or height, they will be interpreted as envelope spanning the anti-meridian.

Parameters:

crs - The coordinate reference system, or null.

rect - The rectangle to copy.

See Also:

GeneralEnvelope.GeneralEnvelope(Rectangle2D)

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. May be negative for envelope spanning the anti-meridian.

height - The envelope height. May be negative for envelope spanning the anti-meridian.

Envelope2D

public Envelope2D(DirectPosition lower,
                  DirectPosition upper)
           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.

Spanning the anti-meridian of a Geographic CRS
This minDP and maxDP arguments may not be really minimal or maximal values if the rectangle cross the anti-meridian. The given arguments are rather the values to be returned by getLowerCorner() and getUpperCorner() methods, which may have an extended interpretation. See the javadoc of above-cited methods for more details.

Parameters:

lower - The fist position.

upper - The second position.

Throws:

MismatchedReferenceSystemException - if the two positions don't use the same CRS.

Since:

2.4

See Also:

GeneralEnvelope.GeneralEnvelope(GeneralDirectPosition, GeneralDirectPosition)

Method Detail

setEnvelope

public void setEnvelope(Envelope envelope)
                 throws MismatchedDimensionException

Sets this envelope to the same values than the given Envelope.

Parameters:

envelope - The envelope to copy.

Throws:

MismatchedDimensionException - If the given envelope is not two-dimensional.

Since:

3.09

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)

Sets the coordinate reference system in which the coordinate are given. This method does not reproject the envelope. If the envelope coordinates need to be transformed to the new CRS, consider using Envelopes.transform(Envelope, CoordinateReferenceSystem) instead.

Parameters:

crs - The new coordinate reference system, or null.

getDimension

public final int getDimension()

Returns the number of dimensions, which is always 2.

Specified by:

getDimension in interface Envelope

getLowerCorner

public DirectPosition2D getLowerCorner()

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

Note: The Web Coverage Service (WCS) 1.1 specification uses an extended interpretation of the bounding box definition. In a WCS 1.1 data structure, the lower corner defines the edges region in the directions of decreasing coordinate values in the envelope CRS. This is usually the algebraic minimum coordinates, but not always. For example, an envelope spanning the anti-meridian could have a lower corner longitude greater than the upper corner longitude. Such extended interpretation applies mostly to axes having WRAPAROUND range meaning.

Specified by:

getLowerCorner in interface Envelope

Returns:

The lower corner, typically (but not necessarily) containing minimal ordinate values.

getUpperCorner

public DirectPosition2D getUpperCorner()

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

Note: The Web Coverage Service (WCS) 1.1 specification uses an extended interpretation of the bounding box definition. In a WCS 1.1 data structure, the upper corner defines the edges region in the directions of increasing coordinate values in the envelope CRS. This is usually the algebraic maximum coordinates, but not always. For example, an envelope spanning the anti-meridian could have an upper corner longitude less than the lower corner longitude. Such extended interpretation applies mostly to axes having WRAPAROUND range meaning.

Specified by:

getUpperCorner in interface Envelope

Returns:

The upper corner, typically (but not necessarily) containing maximal ordinate values.

getMinimum

public double getMinimum(int dimension)
                  throws IndexOutOfBoundsException

Returns the minimal ordinate along the specified dimension. This method handles anti-meridian spanning as documented in the AbstractEnvelope.getMinimum(int) method.

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 double getMaximum(int dimension)
                  throws IndexOutOfBoundsException

Returns the maximal ordinate along the specified dimension. This method handles anti-meridian spanning as documented in the AbstractEnvelope.getMaximum(int) method.

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 double getMedian(int dimension)
                 throws IndexOutOfBoundsException

Returns the median ordinate along the specified dimension. This method handles anti-meridian spanning as documented in the AbstractEnvelope.getMedian(int) method.

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 double getSpan(int dimension)
               throws IndexOutOfBoundsException

Returns the envelope span along the specified dimension. This method handles anti-meridian spanning as documented in the AbstractEnvelope.getSpan(int) method.

Specified by:

getSpan in interface Envelope

Parameters:

dimension - The dimension to query.

Returns:

The rectangle width or height, depending the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is out of bounds.

getMinX

public double getMinX()

Returns the minimal ordinate value for dimension 0.

Overrides:

getMinX in class RectangularShape

getMinY

public double getMinY()

Returns the minimal ordinate value for dimension 1.

Overrides:

getMinY in class RectangularShape

getMaxX

public double getMaxX()

Returns the maximal ordinate value for dimension 0.

Overrides:

getMaxX in class RectangularShape

getMaxY

public double getMaxY()

Returns the maximal ordinate value for dimension 1.

Overrides:

getMaxY in class RectangularShape

getCenterX

public double getCenterX()

Returns the median ordinate value for dimension 0.

Overrides:

getCenterX in class RectangularShape

getCenterY

public double getCenterY()

Returns the median ordinate value for dimension 1.

Overrides:

getCenterY in class RectangularShape

getWidth

public double getWidth()

Returns the span for dimension 0.

Overrides:

getWidth in class Rectangle2D.Double

getHeight

public double getHeight()

Returns the span for dimension 1.

Overrides:

getHeight in class Rectangle2D.Double

isEmpty

public boolean isEmpty()

Determines whether the envelope is empty. A negative Rectangle2D.Double.width or (@linkplain #height} is considered as a non-empty area if the corresponding axis has the wraparound range meaning.

Note that if the Rectangle2D.Double.width or Rectangle2D.Double.height value is NaN, then the envelope is considered empty. This is different than the default Rectangle2D.Double.isEmpty() implementation, which doesn't check for NaN values.

Overrides:

isEmpty in class Rectangle2D.Double

Since:

3.20

contains

public boolean contains(double px,
                        double py)

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

Spanning the anti-meridian of a Geographic CRS
This method supports anti-meridian spanning in the same way than AbstractEnvelope.contains(DirectPosition).

Specified by:

contains in interface Shape

Overrides:

contains in class Rectangle2D

Parameters:

px - The first ordinate value of the point to text.

py - The second ordinate value of the point to text.

Returns:

true if the specified coordinate is inside the boundary of this envelope; false otherwise.

Since:

3.20

contains

public boolean contains(Rectangle2D rect)

Returns true if this envelope completely encloses the specified rectangle. If this envelope or the given rectangle have at least one NaN value, then this method returns false.

Spanning the anti-meridian of a Geographic CRS
This method supports anti-meridian spanning in the same way than AbstractEnvelope.contains(Envelope, boolean).

Specified by:

contains in interface Shape

Overrides:

contains in class RectangularShape

Parameters:

rect - The rectangle to test for inclusion.

Returns:

true if this envelope completely encloses the specified rectangle.

Since:

3.20

contains

public boolean contains(double rx,
                        double ry,
                        double rw,
                        double rh)

Returns true if this envelope completely encloses the specified rectangle. If this envelope or the given rectangle have at least one NaN value, then this method returns false.

Spanning the anti-meridian of a Geographic CRS
This method supports anti-meridian spanning in the same way than AbstractEnvelope.contains(Envelope, boolean).

Specified by:

contains in interface Shape

Overrides:

contains in class Rectangle2D

Parameters:

rx - The x ordinate of the lower corner of the rectangle to test for inclusion.

ry - The y ordinate of the lower corner of the rectangle to test for inclusion.

rw - The width of the rectangle to test for inclusion. May be negative if the rectangle spans the anti-meridian.

rh - The height of the rectangle to test for inclusion. May be negative.

Returns:

true if this envelope completely encloses the specified one.

Since:

3.20

intersects

public boolean intersects(Rectangle2D rect)

Returns true if this envelope intersects the specified envelope. If this envelope or the given rectangle have at least one NaN value, then this method returns false.

Spanning the anti-meridian of a Geographic CRS
This method supports anti-meridian spanning in the same way than AbstractEnvelope.intersects(Envelope, boolean).

Specified by:

intersects in interface Shape

Overrides:

intersects in class RectangularShape

Parameters:

rect - The rectangle to test for intersection.

Returns:

true if this envelope intersects the specified rectangle.

Since:

3.20

intersects

public boolean intersects(double rx,
                          double ry,
                          double rw,
                          double rh)

Returns true if this envelope intersects the specified envelope. If this envelope or the given rectangle have at least one NaN value, then this method returns false.

Spanning the anti-meridian of a Geographic CRS
This method supports anti-meridian spanning in the same way than AbstractEnvelope.intersects(Envelope, boolean).

Specified by:

intersects in interface Shape

Overrides:

intersects in class Rectangle2D

Parameters:

rx - The x ordinate of the lower corner of the rectangle to test for intersection.

ry - The y ordinate of the lower corner of the rectangle to test for intersection.

rw - The width of the rectangle to test for inclusion. May be negative if the rectangle spans the anti-meridian.

rh - The height of the rectangle to test for inclusion. May be negative.

Returns:

true if this envelope intersects the specified rectangle.

Since:

3.20

createIntersection

public Envelope2D createIntersection(Rectangle2D rect)

Returns the intersection of this envelope with the specified rectangle. If this envelope or the given rectangle have at least one NaN values, then this method returns an empty envelope.

Spanning the anti-meridian of a Geographic CRS
This method supports anti-meridian spanning in the same way than GeneralEnvelope.intersect(Envelope).

Overrides:

createIntersection in class Rectangle2D.Double

Parameters:

rect - The rectangle to be intersected with this envelope.

Returns:

The intersection of the given rectangle with this envelope.

createUnion

public Envelope2D createUnion(Rectangle2D rect)

Returns the union of this envelope with the specified rectangle. The default implementation clones this envelope, then delegates to add(Rectangle2D).

Overrides:

createUnion in class Rectangle2D.Double

Parameters:

rect - The rectangle to add to this envelope.

Returns:

The union of the given rectangle with this envelope.

add

public void add(Rectangle2D rect)

Adds an other rectangle to this rectangle. The resulting rectangle is the union of the two Rectangle objects.

Spanning the anti-meridian of a Geographic CRS
This method supports anti-meridian spanning in the same way than GeneralEnvelope.add(Envelope), except if the result is a rectangle expanding to infinities. In the later case, the field values are set to NaN because infinite values are a little bit problematic in Rectangle2D objects.

Overrides:

add in class Rectangle2D

Parameters:

rect - The rectangle to add to this envelope.

add

public void add(double px,
                double py)

Adds a point to this rectangle. The resulting rectangle is the smallest rectangle that contains both the original rectangle and the specified point.

After adding a point, a call to contains(double, double) 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 has been ignored.

Spanning the anti-meridian of a Geographic CRS
This method supports anti-meridian spanning in the same way than GeneralEnvelope.add(DirectPosition).

Overrides:

add in class Rectangle2D

Parameters:

px - The first ordinate of the point to add.

py - The second ordinate of the point to add.

equals

public boolean equals(Object object)

Compares the specified object with this envelope for equality. If the given object is not an instance of Envelope2D, then the two objects are compared as plain rectangles, i.e. the coordinate reference system of this envelope is ignored.

Note on hashCode()
This class does not override the Rectangle2D.hashCode() method for consistency with the Rectangle2D.equals(Object) method, which compare arbitrary Rectangle2D implementations.

Overrides:

equals in class Rectangle2D

Parameters:

object - The object to compare with this envelope.

Returns:

true if the given object is equal to this envelope.

boundsEquals

public boolean boundsEquals(Envelope that,
                            int xDim,
                            int yDim,
                            double eps)

Returns true if this envelope bounds is equal 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 comparisons. 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 String toString()

Formats this envelope in the Well Known Text (WKT) format. The output is like below:

BOX2D(lower corner, upper corner)

Overrides:

toString in class Rectangle2D.Double

Since:

2.4

See Also:

Envelopes.toWKT(Envelope)