Module org.opengis.geoapi
Package org.opengis.geometry

Interface Envelope

All Known Implementing Classes:
SimpleEnvelope
@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 a WRAPAROUND range meaning, which is usually the longitude axis.
Since:
1.0
See Also:
  • GridEnvelope
Departure from OGC/ISO abstract specification:
Extension for convenience without introduction of new functionality 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

    Modifier and Type
    Method
    Description
    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 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.
    DirectPosition
    getUpperCorner()
    The limits in the direction of increasing coordinate values for each dimension.

  • Method Details

    • 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.
      Departure from OGC/ISO abstract specification:
      Extension for convenience without introduction of new functionality 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.
      Departure from OGC/ISO abstract specification:
      Extension for convenience without introduction of new functionality 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 coordinate values for each dimension. This is typically a coordinate position consisting of all the minimal coordinates for each dimension for all points within the Envelope.

      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 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 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 the Envelope.

      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 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 coordinate values.

    • getMinimum

      double getMinimum(int dimension) throws IndexOutOfBoundsException
      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 temporary DirectPosition object:
      minimum = getLowerCorner().getOrdinate(dimension);

      Crossing 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 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:
      Departure from OGC/ISO abstract specification:
      Extension for convenience without introduction of new functionality 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 the Envelope itself rather than in a contained DirectPosition corner.

    • getMaximum

      double getMaximum(int dimension) throws IndexOutOfBoundsException
      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 temporary DirectPosition object:
      maximum = getUpperCorner().getOrdinate(dimension);

      Crossing 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 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:
      Departure from OGC/ISO abstract specification:
      Extension for convenience without introduction of new functionality 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 the Envelope itself rather than in a contained DirectPosition corner.

    • getMedian

      double getMedian(int dimension) throws IndexOutOfBoundsException
      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 is WRAPAROUND, 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:
      Departure from OGC/ISO abstract specification:
      Extension for convenience without introduction of new functionality 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 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 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 is WRAPAROUND, 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:
      Departure from OGC/ISO abstract specification:
      Extension for convenience without introduction of new functionality 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.