
 All Known Subinterfaces:
BoundingBox
@Classifier(DATATYPE) @UML(identifier="GM_Envelope", specification=ISO_19107) public interface Envelope
A minimum bounding box or rectangle. Regardless of dimension, anEnvelope
can be represented without ambiguity as two direct positions (coordinate points). To encode anEnvelope
, 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 antimeridian 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 antimeridian could have an upper corner longitude less than the lower corner longitude. Whether an envelope supports the extended bounding box interpretation or not is implementationdependent. If supported, the extended interpretation is applicable only to axes having aWRAPAROUND
range meaning, which is usually the longitude axis. Since:
 1.0
 See Also:
GridEnvelope
Departure from OGC/ISO specification:
The ISO specification defines this interface in thecoordinate
subpackage. GeoAPI moved this interface into theorg.opengis.geometry
root package for convenience, because it is extensively used.


Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description CoordinateReferenceSystem
getCoordinateReferenceSystem()
Returns the envelope coordinate reference system, ornull
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 limits in the direction of increasing ordinate values for each dimension.



Method Detail

getCoordinateReferenceSystem
CoordinateReferenceSystem getCoordinateReferenceSystem()
Returns the envelope coordinate reference system, ornull
if unknown. If nonnull, 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 cornerDirectPosition
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 cornerDirectPosition
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 theEnvelope
.Spanning the antimeridian 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 antimeridian could have a lower corner longitude greater than the upper corner longitude. Whether this envelope supports the extended bounding box interpretation or not is implementationdependent. If supported, the extended interpretation is applicable only to axes having aWRAPAROUND
range meaning  usually the longitude axis. On typical map representations, thegetLowerCorner()
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 limits 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 theEnvelope
.Spanning the antimeridian 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 antimeridian could have an upper corner longitude less than the lower corner longitude. Whether this envelope supports the extended bounding box interpretation or not is implementationdependent. If supported, the extended interpretation is applicable only to axes having aWRAPAROUND
range meaning  usually the longitude axis. On typical map representations, thegetUpperCorner()
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 nonempty envelopes not spanning the antimeridian, this method is a shortcut for the following code without the cost of creating a temporaryDirectPosition
object:minimum = getLowerCorner().getOrdinate(dimension);
Spanning the antimeridian of a geographic CRS
If the axis range meaning isWRAPAROUND
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 theEnvelope
itself rather than in a containedDirectPosition
corner.

getMaximum
double getMaximum(int dimension) throws IndexOutOfBoundsException
Returns the maximal ordinate value for the specified dimension. In the typical case of nonempty envelopes not spanning the antimeridian, this method is a shortcut for the following code without the cost of creating a temporaryDirectPosition
object:maximum = getUpperCorner().getOrdinate(dimension);
Spanning the antimeridian of a geographic CRS
If the axis range meaning isWRAPAROUND
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 theEnvelope
itself rather than in a containedDirectPosition
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 antimeridian of a geographic CRS
If this envelope supports the lower and upper corners extended interpretation, and if the axis range meaning isWRAPAROUND
, 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 theEnvelope
itself rather than in a containedDirectPosition
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 antimeridian of a geographic CRS
If this envelope supports the lower and upper corners extended interpretation, and if the axis range meaning isWRAPAROUND
, 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 theEnvelope
itself rather than calculating it from the corners.

