Package org.apache.sis.geometry

Class GeneralEnvelope

    • Constructor Detail

      • GeneralEnvelope

        public GeneralEnvelope​(double[] lowerCorner,
                       double[] upperCorner)
                throws MismatchedDimensionException
        Constructs an envelope defined by two corners given as sequences of coordinate values. The Coordinate Reference System is initially null.
        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.
        Throws:
        Mismatched­Dimension­Exception - if the two sequences do not have the same length.

      • GeneralEnvelope

        public GeneralEnvelope​(int dimension)
        Constructs an empty envelope of the specified dimension. All coordinates are initialized to 0 and the coordinate reference system is undefined.
        Parameters:
        dimension - the envelope dimension.

      • GeneralEnvelope

        public GeneralEnvelope​(CoordinateReferenceSystem crs)
        Constructs an empty envelope with the specified coordinate reference system. All coordinate values are initialized to 0.
        Parameters:
        crs - the coordinate reference system.

      • GeneralEnvelope

        public GeneralEnvelope​(Envelope envelope)
        Constructs a new envelope with the same data than the specified envelope.
        Parameters:
        envelope - the envelope to copy.
        See Also:
        cast­Or­Copy(Envelope)

      • GeneralEnvelope

        public GeneralEnvelope​(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.

      • GeneralEnvelope

        public GeneralEnvelope​(CharSequence wkt)
                throws IllegalArgumentException
        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. Actually this constructor ignores the geometry type and just applies the following simple rules:
        • Character sequences complying to the rules of Java identifiers are skipped.
        • Coordinates are separated by a coma (,) character.
        • The coordinates in a coordinate tuple are separated by a space.
        • Coordinate numbers are assumed formatted in US locale.
        • The coordinate having the highest dimension determines the dimension of this envelope.
        This constructor does not check the consistency of the provided text. For example it does not check that every points in a LINESTRING have the same dimension. However this constructor ensures that the parenthesis are balanced, in order to catch some malformed WKT.
        Example: The following texts can be parsed by this constructor in addition of the usual BOX element. This constructor creates the bounding box of those geometries:
        • POINT(6 10)
        • MULTIPOLYGON(((1 1, 5 1, 1 5, 1 1),(2 2, 3 2, 3 3, 2 2)))
        • GEOMETRYCOLLECTION(POINT(4 6),LINESTRING(3 8,7 10))
        Parameters:
        wkt - the BOX, POLYGON or other kind of element to parse.
        Throws:
        Illegal­Argument­Exception - if the given string can not be parsed.
        See Also:
        Envelopes​.from­WKT(Char­Sequence), Envelopes​.to­String(Envelope)

    • Method Detail

      • setRange

        public void setRange​(int dimension,
                     double lower,
                     double upper)
              throws IndexOutOfBoundsException
        Sets the envelope range along the specified dimension.
        Parameters:
        dimension - the dimension to set.
        lower - the limit in the direction of decreasing coordinate values.
        upper - the limit in the direction of increasing coordinate values.
        Throws:
        Index­Out­Of­Bounds­Exception - if the given index is out of bounds.
        Illegal­Argument­Exception - if lower > upper and the axis range meaning at the given dimension is not "wraparound". See Envelope validation in class javadoc for more details.

      • setEnvelope

        public void setEnvelope​(double... corners)
        Sets the envelope to the specified values, which must be the lower corner coordinates followed by upper corner coordinates. The number of arguments provided shall be twice this envelope dimension, and minimum shall not be greater than maximum.
        Example: (xmin, ymin, zmin, xmax, ymax, zmax)
        Parameters:
        corners - coordinates of the new lower corner followed by the new upper corner.

      • setEnvelope

        public void setEnvelope​(Envelope envelope)
                 throws MismatchedDimensionException
        Sets this envelope to the same coordinate values than the specified envelope. If the given envelope has a non-null Coordinate Reference System (CRS), then the CRS of this envelope will be set to the CRS of the given envelope.
        Parameters:
        envelope - the envelope to copy coordinates from.
        Throws:
        Mismatched­Dimension­Exception - if the specified envelope doesn't have the expected number of dimensions.

      • setTimeRange

        public boolean setTimeRange​(Instant startTime,
                            Instant endTime)
        If this envelope has a temporal component, set this temporal dimension to the given range. Otherwise this method does nothing. This convenience method converts the given instants to floating point values using Default­Temporal­CRS, then delegates to set­Range(int, double, double).
        Parameters:
        start­Time - the lower temporal value, or null if unspecified.
        end­Time - the upper temporal value, or null if unspecified.
        Returns:
        whether the temporal component has been set.
        Since:
        1.0

      • translate

        public void translate​(double... vector)
        Translates the envelope by the given vector. For every dimension i, the lower and upper values are increased by vector[i].

        This method does not check if the translation result is inside the coordinate system domain (e.g. [-180 … +180]° of longitude). Callers can normalize the envelope when desired by call to the normalize() method.

        Parameters:
        vector - the translation vector. The length of this array shall be equal to this envelope dimension.
        Since:
        0.5

      • add

        public void add​(DirectPosition position)
         throws MismatchedDimensionException
        Adds a point to this envelope. The resulting envelope is the smallest envelope that contains both the original envelope and the specified point.

        After adding a point, a call to contains(Direct­Position) with the added point as an argument will return true, except if one of the point coordinates was Double​.Na­N in which case the corresponding coordinate has been ignored.

        Pre-conditions
        This method assumes that the specified point uses the same CRS than this envelope. For performance reasons, it will no be verified unless Java assertions are enabled.
        Spanning the anti-meridian of a Geographic CRS
        This method supports envelopes spanning the anti-meridian. In such cases it is possible to move both envelope borders in order to encompass the given point, as illustrated below (the new point is represented by the + symbol): 
        ─────┐   + ┌─────
─────┘     └─────
        The default implementation moves only the border which is closest to the given point.
        Parameters:
        position - the point to add.
        Throws:
        Mismatched­Dimension­Exception - if the given point does not have the expected number of dimensions.
        Assertion­Error - if assertions are enabled and the envelopes have mismatched CRS.

      • add

        public void add​(Envelope envelope)
         throws MismatchedDimensionException
        Adds an envelope object to this envelope. The resulting envelope is the union of the two Envelope objects.
        Pre-conditions
        This method assumes that the specified envelope uses the same CRS than this envelope. For performance reasons, it will no be verified unless Java assertions are enabled.
        Spanning the anti-meridian of a Geographic CRS
        This method supports envelopes spanning the anti-meridian. If one or both envelopes span the anti-meridian, then the result of the add operation may be an envelope expanding to infinities. In such case, the coordinate range will be either [−∞…∞] or [0…−0] depending on whatever the original range span the anti-meridian or not.
        Handling of NaN values
        Double​.Na­N values may be present in any dimension, in the lower coordinate, upper coordinate or both. The behavior of this method in such case depends where the Na­N values appear and whether an envelope spans the anti-meridian:
        • If this envelope or the given envelope spans anti-meridian in the dimension containing Na­N coordinates, then this method does not changes the coordinates in that dimension. The rational for such conservative approach is because union computation depends on whether the other envelope spans anti-meridian too, which is unknown because at least one envelope bounds is Na­N. Since anti-meridian spanning has been detected in an envelope, there is suspicion about whether the other envelope could span anti-meridian too.
        • Otherwise since the envelope containing real values does not span anti-meridian in that dimension, this method assumes that the envelope containing Na­N values does not span anti-meridian neither. This assumption is not guaranteed to be true, but cover common cases. With this assumption in mind:
          • All Na­N coordinates in the given envelope are ignored, i.e. this method does not replace finite coordinates in this envelope by Na­N values from the given envelope. Note that if only the lower or upper bound is Na­N, the other bound will still be used for computing union with the assumption described in above paragraph.
          • All Na­N coordinates in this envelope are left unchanged, i.e. the union will still contain all the Na­N values that this envelope had before add(Envelope) invocation. Note that if only the lower or upper bound is Na­N, the other bound will still be used for computing union with the assumption described in above paragraph.
        Parameters:
        envelope - the Envelope to add to this envelope.
        Throws:
        Mismatched­Dimension­Exception - if the given envelope does not have the expected number of dimensions.
        Assertion­Error - if assertions are enabled and the envelopes have mismatched CRS.
        See Also:
        Envelopes​.union(Envelope...), Default­Geographic­Bounding­Box​.add(Geographic­Bounding­Box)

      • intersect

        public void intersect​(Envelope envelope)
               throws MismatchedDimensionException
        Sets this envelope to the intersection of this envelope with the specified one.
        Pre-conditions
        This method assumes that the specified envelope uses the same CRS than this envelope. For performance reasons, it will no be verified unless Java assertions are enabled.
        Spanning the anti-meridian of a Geographic CRS
        This method supports envelopes spanning the anti-meridian.
        Handling of NaN values
        Double​.Na­N values may be present in any dimension, in the lower coordinate, upper coordinate or both. The behavior of this method in such case depends where the Na­N values appear and whether an envelope spans the anti-meridian:
        • If this envelope or the given envelope spans anti-meridian in the dimension containing Na­N coordinates, then this method does not changes the coordinates in that dimension. The rational for such conservative approach is because intersection computation depends on whether the other envelope spans anti-meridian too, which is unknown because at least one envelope bounds is Na­N. Since anti-meridian spanning has been detected in an envelope, there is suspicion about whether the other envelope could span anti-meridian too.
        • Otherwise since the envelope containing real values does not span anti-meridian in that dimension, this method assumes that the envelope containing Na­N values does not span anti-meridian neither. This assumption is not guaranteed to be true, but cover common cases. With this assumption in mind:
          • All Na­N coordinates in the given envelope are ignored, i.e. this method does not replace finite coordinates in this envelope by Na­N values from the given envelope. Note that if only the lower or upper bound is Na­N, the other bound will still be used for computing intersection with the assumption described in above paragraph.
          • All Na­N coordinates in this envelope are left unchanged, i.e. the intersection will still contain all the Na­N values that this envelope had before intersect(Envelope) invocation. Note that if only the lower or upper bound is Na­N, the other bound will still be used for computing intersection with the assumption described in above paragraph.
        Double​.Na­N coordinates may appear as a result of intersection, even if such values were not present in any source envelopes, if the two envelopes do not intersect in some dimensions.
        Parameters:
        envelope - the Envelope to intersect to this envelope.
        Throws:
        Mismatched­Dimension­Exception - if the given envelope does not have the expected number of dimensions.
        Assertion­Error - if assertions are enabled and the envelopes have mismatched CRS.
        See Also:
        Envelopes​.intersect(Envelope...), Default­Geographic­Bounding­Box​.intersect(Geographic­Bounding­Box)

      • normalize

        public boolean normalize()
        Ensures that the envelope is contained in the coordinate system domain. For each dimension, this method compares the coordinate values against the limits of the coordinate system axis for that dimension. If some coordinates are out of range, then there is a choice depending on the axis range meaning:
        • If Range­Meaning​.EXACT (typically latitudes coordinates), then values greater than the axis maximal value are replaced by the axis maximum, and values smaller than the axis minimal value are replaced by the axis minimum.
        • If Range­Meaning​.WRAPAROUND (typically longitudes coordinates), then a multiple of the axis range (e.g. 360° for longitudes) is added or subtracted. Example:
          • the [190 … 200]° longitude range is converted to [-170 … -160]°,
          • the [170 … 200]° longitude range is converted to [+170 … -160]°.
          See Spanning the anti-meridian of a Geographic CRS in the class javadoc for more information about the meaning of such range.
        Spanning the anti-meridian of a Geographic CRS
        If the envelope is spanning the anti-meridian, then some lower coordinate values may become greater than their upper counterpart as a result of this method call. If such effect is undesirable, then this method may be combined with simplify() as below: 
        if (envelope.normalize()) {
    envelope.simplify();
}
        Choosing the range of longitude values
        Geographic CRS typically have longitude values in the [-180 … +180]° range, but the [0 … 360]° range is also occasionally used. Callers need to ensure that this envelope CRS is associated to axes having the desired minimum and maximum value.
        Usage
        This method is sometime useful before to compute the union or intersection of envelopes, in order to ensure that both envelopes are defined in the same domain. This method may also be invoked before to project an envelope, since some projections produce Double​.Na­N numbers when given an coordinate value out of bounds.
        Returns:
        true if this envelope has been modified as a result of this method call, or false if no change has been done.
        See Also:
        Abstract­Direct­Position​.normalize()

      • subEnvelope

        public GeneralEnvelope subEnvelope​(int beginIndex,
                                   int endIndex)
                            throws IndexOutOfBoundsException
        Returns a view over this envelope that encompass only some dimensions. The returned object is "live": changes applied on the original envelope is reflected in the sub-envelope view, and conversely.

        This method is useful for querying and updating only some dimensions. For example in order to expand only the horizontal component of a four dimensional (x,y,z,t) envelope, one can use:

        envelope.subEnvelope(0, 2).add(myPosition2D);
        If the sub-envelope needs to be independent from the original envelope, use the following idiom: 
        GeneralEnvelope copy = envelope.subEnvelope(0, 2).clone();
        The sub-envelope is initialized with a null CRS. This method does not compute a sub-CRS because it may not be needed, or the sub-CRS may be already known by the caller.
        Parameters:
        begin­Index - the index of the first valid coordinate value of the corners.
        end­Index - the index after the last valid coordinate value of the corners.
        Returns:
        the sub-envelope of dimension end­Index - begin­Index.
        Throws:
        Index­Out­Of­Bounds­Exception - if an index is out of bounds.
        See Also:
        CRS​.get­Component­At(Coordinate­Reference­System, int, int)

      • clone

        public GeneralEnvelope clone()
        Returns a deep copy of this envelope.
        Overrides:
        clone in class Object
        Returns:
        a clone of this envelope.

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

      • isAllNaN

        public boolean isAllNaN()
        Returns false if at least one coordinate value is not NaN. This is­All­Na­N() check is different than the Abstract­Envelope​.is­Empty() check since it returns false for a partially initialized envelope, while is­Empty() returns false only after all dimensions have been initialized. More specifically, the following rules apply:
        • If is­All­Na­N() == true, then is­Empty() == true
        • If is­Empty() == false, then is­All­Na­N() == false
        • The converse of the above-cited rules are not always true.
        Note that an all-NaN envelope can still have a non-null coordinate reference system.
        Overrides:
        is­All­Na­N in class Abstract­Envelope
        Returns:
        true if this envelope has NaN values.
        See Also:
        set­To­Na­N(), Default­Geographic­Bounding­Box​.is­Empty()

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