org.opengis.geometry
Interface Envelope

Show UML class diagram

All Known Subinterfaces:

BoundingBox

@UML(identifier="GM_Envelope",
     specification=ISO_19107)
public interface Envelope

A minimum bounding box or rectangle. Regardless of dimension, an Envelope can be represented without ambiguity as two direct positions (coordinate points). To encode an Envelope, it is sufficient to encode these two points. This is consistent with all of the data types in this specification, their state is represented by their publicly accessible attributes.

Spanning the anti-meridian of a geographic CRS
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, while the lower corner defines the edges region in the direction of decreasing coordinate values. They are usually the algebraic maximum and minimum coordinates respectively, but not always. For example, an envelope crossing the anti-meridian could have an upper corner longitude less than the lower corner longitude.

Whatever an envelope supports the extended bounding box interpretation or not is implementation-dependent. If supported, the extended interpretation is applicable only to axes having a WRAPAROUND range meaning - usually the longitude axis.

Since:

1.0

See Also:

GridEnvelope

Departure from OGC/ISO specification:
The ISO specification defines this interface in the coordinate sub-package. GeoAPI moved this interface into the org.opengis.geometry root package for convenience, because it is extensively used.

Method Summary

CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the envelope coordinate reference system, or null if unknown.
int	getDimension() The length of coordinate sequence (the number of entries) in this envelope.
DirectPosition	getLowerCorner() The limits in the direction of decreasing ordinate values for each dimension.
double	getMaximum(int dimension) Returns the maximal ordinate value for the specified dimension.
double	getMedian(int dimension) Returns the median ordinate along the specified dimension.
double	getMinimum(int dimension) Returns the minimal ordinate value for the specified dimension.
double	getSpan(int dimension) Returns the envelope span (typically width or height) along the specified dimension.
DirectPosition	getUpperCorner() The limit in the direction of increasing ordinate values for each dimension.

Method Detail

getCoordinateReferenceSystem

CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the envelope coordinate reference system, or null if unknown. If non-null, it shall be the same as lower corner and upper corner CRS.

Returns:

The envelope CRS, or null if unknown.

Since:

2.1

Departure from OGC/ISO specification:
ISO does not define this method - the CRS or the dimension can be obtained only through one of the corner DirectPosition objects. GeoAPI adds this method for convenience as a more direct way of obtaining the information and to free the user from the need to choose an arbitrary corner (very defensive code might feel the need to get the value from both corners to check they were the same).

getDimension

int getDimension()

The length of coordinate sequence (the number of entries) in this envelope. Mandatory even when the coordinate reference system is unknown.

Returns:

The dimensionality of this envelope.

Since:

2.0

Departure from OGC/ISO specification:
ISO does not define this method - the CRS or the dimension can be obtained only through one of the corner DirectPosition objects. GeoAPI adds this method for convenience as a more direct way of obtaining the information and to free the user from the need to choose an arbitrary corner (very defensive code might feel the need to get the value from both corners to check they were the same).

getLowerCorner

@UML(identifier="lowerCorner",
     obligation=MANDATORY,
     specification=ISO_19107)
DirectPosition getLowerCorner()

The limits in the direction of decreasing ordinate values for each dimension. This is typically a coordinate position consisting of all the minimal ordinates for each dimension for all points within the Envelope.

Spanning the anti-meridian of a geographic CRS
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 crossing the anti-meridian could have a lower corner longitude greater than the upper corner longitude.

Whatever this envelope supports the extended bounding box interpretation or not is implementation-dependent. If supported, the extended interpretation is applicable only to axes having a WRAPAROUND range meaning - usually the longitude axis. On typical map representations, the getLowerCorner() method name still "visually" appropriate since the lower corner still toward the bottom of the map even if the left corner became the right corner.

Returns:

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

getUpperCorner

@UML(identifier="upperCorner",
     obligation=MANDATORY,
     specification=ISO_19107)
DirectPosition getUpperCorner()

The limit in the direction of increasing ordinate values for each dimension. This is typically a coordinate position consisting of all the maximal ordinates for each dimension for all points within the Envelope.

Spanning the anti-meridian of a geographic CRS
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 crossing the anti-meridian could have an upper corner longitude less than the lower corner longitude.

Whatever this envelope supports the extended bounding box interpretation or not is implementation-dependent. If supported, the extended interpretation is applicable only to axes having a WRAPAROUND range meaning - usually the longitude axis. On typical map representations, the getUpperCorner() method name still "visually" appropriate since the upper corner still toward the top of the map even if the right corner became the left corner.

Returns:

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

getMinimum

double getMinimum(int dimension)
                  throws IndexOutOfBoundsException

Returns the minimal ordinate value for the specified dimension. In the typical case of envelopes not spanning the anti-meridian, this method is a shortcut for the following code without the cost of creating a temporary DirectPosition object:

minimum = getLowerCorner().getOrdinate(dimension);

Spanning the anti-meridian of a geographic CRS
If the axis range meaning is WRAPAROUND and this envelope supports the lower and upper corners extended interpretation, then lower may possibly be greater than upper. In such case, implementations shall select some value such that minimum < maximum (ignoring NaN). It may be the axis minimum value, negative infinity, NaN or other value, at implementor choice.

Parameters:

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

Returns:

The minimal ordinate at the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is negative or is equals or greater than the envelope dimension.

Since:

2.0

See Also:

RectangularShape.getMinX(), RectangularShape.getMinY()

Departure from OGC/ISO specification:
This method is not part of ISO specification. GeoAPI adds this method for convenience and efficiency, since some implementations might store the minimum and maximum ordinate values directly in the Envelope itself rather than in a contained DirectPosition corner.

getMaximum

double getMaximum(int dimension)
                  throws IndexOutOfBoundsException

Returns the maximal ordinate value for the specified dimension. In the typical case of envelopes not spanning the anti-meridian, this method is a shortcut for the following code without the cost of creating a temporary DirectPosition object:

maximum = getUpperCorner().getOrdinate(dimension);

Spanning the anti-meridian of a geographic CRS
If the axis range meaning is WRAPAROUND and this envelope supports the lower and upper corners extended interpretation, then upper may possibly be less than lower. In such case, implementations shall select some value such that maximum > minimum (ignoring NaN). It may be the axis maximum value, positive infinity, NaN or other value, at implementor choice.

Parameters:

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

Returns:

The maximal ordinate at the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is negative or is equals or greater than the envelope dimension.

Since:

2.0

See Also:

RectangularShape.getMaxX(), RectangularShape.getMaxY()

Departure from OGC/ISO specification:
This method is not part of ISO specification. GeoAPI adds this method for convenience and efficiency, since some implementations might store the minimum and maximum ordinate values directly in the Envelope itself rather than in a contained DirectPosition corner.

getMedian

double getMedian(int dimension)
                 throws IndexOutOfBoundsException

Returns the median ordinate along the specified dimension. In most cases, the result is equals (minus rounding error) to:

median = (getMinimum(dimension) + getMaximum(dimension)) / 2;

Spanning the anti-meridian of a geographic CRS
If this envelope supports the lower and upper corners extended interpretation, and if the axis range meaning is WRAPAROUND, then a special cases occurs when upper < lower. In such cases, the ordinate values from the lower and upper corner may be used instead than the minimum and maximum values, with the periodicity (360° for longitudes) added to the upper value before to perform the median calculation.

Implementations are free to use variants of the above algorithm. For example some libraries may add different multiples of the periodicity in order to ensure that the median value is inside the axis range.

Parameters:

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

Returns:

The median ordinate at the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is negative or is equals or greater than the envelope dimension.

Since:

2.2

See Also:

RectangularShape.getCenterX(), RectangularShape.getCenterY()

Departure from OGC/ISO specification:
This method is not part of ISO specification. GeoAPI adds this method for convenience and efficiency, since some implementations might store the minimum and maximum ordinate values directly in the Envelope itself rather than in a contained DirectPosition corner.

getSpan

double getSpan(int dimension)
               throws IndexOutOfBoundsException

Returns the envelope span (typically width or height) along the specified dimension. In most cases, the result is equals (minus rounding error) to:

span = getMaximum(dimension) - getMinimum(dimension);

Spanning the anti-meridian of a geographic CRS
If this envelope supports the lower and upper corners extended interpretation, and if the axis range meaning is WRAPAROUND, then a special cases occurs when upper < lower. In such cases, the ordinate values from the lower and upper corner may be used instead than the minimum and maximum values, with the periodicity (360° for longitudes) added to the upper value before to perform the span calculation.

Implementations are free to use variants of the above algorithm. For example some libraries may add different multiples of the periodicity.

Parameters:

dimension - The dimension for which to obtain the span.

Returns:

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

Throws:

IndexOutOfBoundsException - If the given index is negative or is equals or greater than the envelope dimension.

Since:

2.2

See Also:

RectangularShape.getWidth(), RectangularShape.getHeight()

Departure from OGC/ISO specification:
This method is not part of ISO specification. GeoAPI adds this method for convenience and efficiency, since some implementations might store the span values directly in the Envelope itself rather than calculating it from the corners.