@Classifier(DATATYPE)
@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.
Crossing 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. Whether an envelope supports the extended bounding box interpretation or not is implementation-dependent. If supported, the extended interpretation is applicable only to axes having aWRAPAROUND
range meaning, which is usually
the longitude axis.- Since:
- 1.0
Convenience extension to OGC/ISO standard
The ISO specification defines this interface in thecoordinate
sub-package.
GeoAPI moved this interface into the org.opengis.geometry
root package for
convenience, because it is extensively used.
-
Method Summary
Modifier and TypeMethodDescriptionReturns the envelope coordinate reference system, ornull
if unknown.int
The length of coordinate sequence (the number of entries) in this envelope.The limits in the direction of decreasing coordinate values for each dimension.double
getMaximum
(int dimension) Returns the maximal coordinate value for the specified dimension.double
getMedian
(int dimension) Returns the median coordinate along the specified dimension.double
getMinimum
(int dimension) Returns the minimal coordinate value for the specified dimension.double
getSpan
(int dimension) Returns the envelope span (typically width or height) along the specified dimension.The limits in the direction of increasing coordinate values for each dimension.
-
Method Details
-
getCoordinateReferenceSystem
Returns the envelope coordinate reference system, ornull
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.
Convenience extension to OGC/ISO standard
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.
Convenience extension to OGC/ISO standard
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 coordinate values for each dimension. This is typically a coordinate position consisting of all the minimal coordinates for each dimension for all points within theEnvelope
.Crossing 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. Whether this envelope supports the extended bounding box interpretation or not is implementation-dependent. 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 coordinate values.
-
getUpperCorner
@UML(identifier="upperCorner", obligation=MANDATORY, specification=ISO_19107) DirectPosition getUpperCorner()The limits in the direction of increasing coordinate values for each dimension. This is typically a coordinate position consisting of all the maximal coordinates for each dimension for all points within theEnvelope
.Crossing 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. Whether this envelope supports the extended bounding box interpretation or not is implementation-dependent. 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 coordinate values.
-
getMinimum
Returns the minimal coordinate value for the specified dimension. In the typical case of non-empty envelopes not crossing the anti-meridian, this method is a shortcut for the following code without the cost of creating a temporaryDirectPosition
object:minimum = getLowerCorner().getCoordinate(dimension);
Crossing the anti-meridian 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 implementer choice.- Parameters:
dimension
- the dimension for which to obtain the coordinate value.- Returns:
- the minimal coordinate at the given dimension.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equal or greater than the envelope dimension.- See Also:
Convenience extension to OGC/ISO standard
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 coordinate values directly in theEnvelope
itself rather than in a containedDirectPosition
corner. -
getMaximum
Returns the maximal coordinate value for the specified dimension. In the typical case of non-empty envelopes not crossing the anti-meridian, this method is a shortcut for the following code without the cost of creating a temporaryDirectPosition
object:maximum = getUpperCorner().getCoordinate(dimension);
Crossing the anti-meridian 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 implementer choice.- Parameters:
dimension
- the dimension for which to obtain the coordinate value.- Returns:
- the maximal coordinate at the given dimension.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equal or greater than the envelope dimension.- See Also:
Convenience extension to OGC/ISO standard
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 coordinate values directly in theEnvelope
itself rather than in a containedDirectPosition
corner. -
getMedian
Returns the median coordinate along the specified dimension. In most cases, the result is equal (minus rounding error) to:median = (getMinimum(dimension) + getMaximum(dimension)) / 2;
Crossing the anti-meridian 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 coordinate values from the lower and upper corner may be used instead of 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 coordinate value.- Returns:
- the median coordinate at the given dimension.
- Throws:
IndexOutOfBoundsException
- if the given index is negative or is equal or greater than the envelope dimension.- See Also:
Convenience extension to OGC/ISO standard
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 coordinate values directly in theEnvelope
itself rather than in a containedDirectPosition
corner. -
getSpan
Returns the envelope span (typically width or height) along the specified dimension. In most cases, the result is equal (minus rounding error) to:span = getMaximum(dimension) - getMinimum(dimension);
Crossing the anti-meridian 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 coordinate values from the lower and upper corner may be used instead of 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 equal or greater than the envelope dimension.- See Also:
Convenience extension to OGC/ISO standard
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.
-