Package org.opengis.geometry

Interface Envelope

  • @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.
    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. 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 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

      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 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.
        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.
        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 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.
        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. 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.
        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. 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 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 coordinate value.
        Returns:
        the minimal coordinate at the given dimension.
        Throws:
        IndexOutOfBoundsException - if the given index is negative or is equals or greater than the envelope dimension.
        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 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 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 coordinate value.
        Returns:
        the maximal coordinate at the given dimension.
        Throws:
        IndexOutOfBoundsException - if the given index is negative or is equals or greater than the envelope dimension.
        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 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 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 coordinate 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 coordinate value.
        Returns:
        the median coordinate at the given dimension.
        Throws:
        IndexOutOfBoundsException - if the given index is negative or is equals or greater than the envelope dimension.
        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 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 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 coordinate 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.
        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.