Class ImmutableEnvelope

  • All Implemented Interfaces:
    Serializable, Emptiable, Envelope

    public final class ImmutableEnvelope
    extends AbstractEnvelope
    implements Serializable
    An immutable Envelope (a minimum bounding box or rectangle) of arbitrary dimension. This class is final in order to ensure that the immutability contract can not be broken (assuming not using Java Native Interface or reflections).
    Immutability and thread safety
    This final class is immutable and thus inherently thread-safe if the Coordinate­Reference­System instance given to the constructor is immutable. This is usually the case in Apache SIS.
    Since:
    0.3
    See Also:
    Serialized Form

    Defined in the sis-referencing module

    • Constructor Detail

      • ImmutableEnvelope

        public ImmutableEnvelope​(double[] lowerCorner,
                                 double[] upperCorner,
                                 CoordinateReferenceSystem crs)
                          throws MismatchedDimensionException
        Constructs an envelope defined by two corners given as sequences of coordinate values.
        Parameters:
        lower­Corner - the limits in the direction of decreasing coordinate values for each dimension.
        upper­Corner - the limits in the direction of increasing coordinate values for each dimension.
        crs - the CRS to assign to this envelope, or null.
        Throws:
        Mismatched­Dimension­Exception - if the two sequences do not have the same length, or if the dimension of the given CRS is not equals to the dimension of the given corners.
      • ImmutableEnvelope

        public ImmutableEnvelope​(GeographicBoundingBox box)
        Constructs a new envelope with the same data than the specified geographic bounding box. The coordinate reference system is set to the default geographic CRS. Axis order is (longitude, latitude).
        Parameters:
        box - the bounding box to copy.
      • ImmutableEnvelope

        public ImmutableEnvelope​(Envelope envelope)
        Creates an immutable envelope with the values of the given envelope. This constructor can be used when the given envelope is known to not be an instance of Immutable­Envelope. In case of doubt, consider using cast­Or­Copy(Envelope) instead.
        Parameters:
        envelope - the envelope to copy.
        See Also:
        cast­Or­Copy(Envelope)
      • ImmutableEnvelope

        public ImmutableEnvelope​(CoordinateReferenceSystem crs,
                                 Envelope envelope)
                          throws MismatchedDimensionException
        Creates an immutable envelope with the coordinate values of the given envelope but a different CRS. This method does not reproject the given envelope. It just assign the given CRS to this envelope without any check, except for the CRS dimension.

        The main purpose of this method is to assign a non-null CRS when the envelope to copy has a null CRS.

        Parameters:
        crs - the CRS to assign to this envelope, or null.
        envelope - the envelope from which to copy coordinate values.
        Throws:
        Mismatched­Dimension­Exception - if the dimension of the given CRS is not equals to the dimension of the given envelope.
      • ImmutableEnvelope

        public ImmutableEnvelope​(CoordinateReferenceSystem crs,
                                 CharSequence wkt)
                          throws IllegalArgumentException,
                                 MismatchedDimensionException
        Constructs a new envelope initialized to the values parsed from the given string in BOX or Well Known Text (WKT) format. The given string is typically a BOX element like below:
        BOX(-180 -90, 180 90)
        However this constructor is lenient to other geometry types like POLYGON. See the javadoc of the General­Envelope constructor for more information.
        Parameters:
        crs - the coordinate reference system, or null if none.
        wkt - the BOX, POLYGON or other kind of element to parse.
        Throws:
        Illegal­Argument­Exception - if the given string can not be parsed.
        Mismatched­Dimension­Exception - if the dimension of the given CRS is not equals to the dimension of the parsed envelope.
    • Method Detail

      • getDimension

        public int getDimension()
        Returns the length of coordinate sequence (the number of entries) in this envelope. This information is available even when the coordinate reference system is unknown.
        Specified by:
        get­Dimension in interface Envelope
        Returns:
        the dimensionality of this envelope.
      • getLower

        public double getLower​(int dimension)
                        throws IndexOutOfBoundsException
        Returns the limit in the direction of decreasing coordinate values in the specified dimension. This is usually the algebraic minimum, except if this envelope spans the anti-meridian.
        Specified by:
        get­Lower in class Abstract­Envelope
        Parameters:
        dimension - the dimension for which to obtain the coordinate value.
        Returns:
        the starting coordinate value at the given dimension.
        Throws:
        Index­Out­Of­Bounds­Exception - if the given index is negative or is equals or greater than the envelope dimension.
      • getUpper

        public double getUpper​(int dimension)
                        throws IndexOutOfBoundsException
        Returns the limit in the direction of increasing coordinate values in the specified dimension. This is usually the algebraic maximum, except if this envelope spans the anti-meridian.
        Specified by:
        get­Upper in class Abstract­Envelope
        Parameters:
        dimension - the dimension for which to obtain the coordinate value.
        Returns:
        the starting coordinate value at the given dimension.
        Throws:
        Index­Out­Of­Bounds­Exception - if the given index is negative or is equals or greater than the envelope dimension.
      • getMedian

        public 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 = (getUpper(dimension) + getLower(dimension)) / 2;
        Spanning the anti-meridian of a Geographic CRS
        If upper < lower and the range meaning for the requested dimension is wraparound, then the median calculated above is actually in the middle of the space outside the envelope. In such cases, this method shifts the median value by half of the periodicity (180° in the longitude case) in order to switch from outer space to inner space. If the axis range meaning is not WRAPAROUND, then this method returns Na­N.
        Specified by:
        get­Median in interface Envelope
        Overrides:
        get­Median in class Abstract­Envelope
        Parameters:
        dimension - the dimension for which to obtain the coordinate value.
        Returns:
        the median coordinate at the given dimension, or Double​.Na­N.
        Throws:
        Index­Out­Of­Bounds­Exception - if the given index is negative or is equals or greater than the envelope dimension.
      • getSpan

        public 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 = getUpper(dimension) - getLower(dimension);
        Spanning the anti-meridian of a Geographic CRS
        If upper < lower and the range meaning for the requested dimension is wraparound, then the span calculated above is negative. In such cases, this method adds the periodicity (typically 360° of longitude) to the span. If the result is a positive number, it is returned. Otherwise this method returns Na­N.
        Specified by:
        get­Span in interface Envelope
        Overrides:
        get­Span in class Abstract­Envelope
        Parameters:
        dimension - the dimension for which to obtain the span.
        Returns:
        the span (typically width or height) at the given dimension, or Double​.Na­N.
        Throws:
        Index­Out­Of­Bounds­Exception - if the given index is negative or is equals or greater than the envelope dimension.
      • equals

        public boolean equals​(Object object)
        Returns true if the specified object is an envelope of the same class with equals coordinates and CRS.
        Implementation note: This implementation requires that the provided object argument is of the same class than this envelope. We do not relax this rule since not every implementations in the SIS code base follow the same contract.
        Overrides:
        equals in class Abstract­Envelope
        Parameters:
        object - the object to compare with this envelope.
        Returns:
        true if the given object is equal to this envelope.
      • toString

        public String toString()
        Formats this envelope as a "BOX" element. The output is of the form "BOXnD(lower corner,upper corner)" where n is the number of dimensions. The number of dimension is written only if different than 2.
        Example:
        • BOX(-90 -180, 90 180)
        • BOX3D(-90 -180 0, 90 180 1)
        Note: The BOX element is not part of the standard Well Known Text (WKT) format. However it is understood by many software libraries, for example GDAL and PostGIS.
        This method formats the numbers as with Double​.to­String(double) (i.e. without fixed number of fraction digits). The string returned by this method can be parsed by the General­Envelope constructor.
        Overrides:
        to­String in class Abstract­Envelope
        Returns:
        this envelope as a BOX or BOX3D (most typical dimensions) element.