org.apache.sis.geometry

## Class Envelopes

- Object
- - Static
  - - Envelopes

-     public final class Envelopes
      extends Static

  Transforms envelopes to new Coordinate Reference Systems, and miscellaneous utilities.
  Envelope transformations
  All `transform(…)` methods in this class take in account the curvature of the transformed shape. For example the shape of a geographic envelope (figure below on the left side) is not rectangular in a conic projection (figure below on the right side). In order to get the envelope represented by the red rectangle, projecting the four corners of the geographic envelope is not sufficient since we would miss the southerner part.

  Example of curvature induced by a map projection
  Envelope before map projection | Shape of the projected envelope
  --- | ---

  Apache SIS tries to detect the curvature by transforming intermediate points in addition to the corners. While optional, it is strongly recommended that all `MathTransform` implementations involved in the operation (directly or indirectly) support derivative, for more accurate calculation of curve extremum. This is the case of most Apache SIS implementations.

  The `transform(…)` methods in this class expect an arbitrary `Envelope` with one of the following arguments: `MathTransform`, `CoordinateOperation` or `CoordinateReferenceSystem`. The recommended method is the one expecting a `CoordinateOperation` object, since it contains sufficient information for handling the cases of envelopes that encompass a pole. The method expecting a `CoordinateReferenceSystem` object is merely a convenience method that infers the coordinate operation itself, but at the cost of performance if the same operation needs to be applied on many envelopes.

  Since:
    0.3
  See Also:
    `Extents`, `CRS`

  Defined in the `sis-referencing` module

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Envelope` | `fromWKT(CharSequence wkt)` Returns the bounding box of a geometry defined in Well Known Text (WKT) format.
    `static String` | `toPolygonWKT(Envelope envelope)` Formats the given envelope as a `POLYGON` element in the Well Known Text (WKT) format.
    `static String` | `toString(Envelope envelope)` Formats the given envelope as a `BOX` element.
    `static GeneralEnvelope` | `transform(CoordinateOperation operation, Envelope envelope)` Transforms an envelope using the given coordinate operation.
    `static Envelope` | `transform(Envelope envelope, CoordinateReferenceSystem targetCRS)` Transforms the given envelope to the specified CRS.
    `static GeneralEnvelope` | `transform(MathTransform transform, Envelope envelope)` Transforms an envelope using the given math transform.

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### transform

          public static Envelope transform(Envelope envelope,
                                           CoordinateReferenceSystem targetCRS)
                                    throws TransformException

      Transforms the given envelope to the specified CRS. If any argument is null, or if the envelope CRS is null or the same instance than the given target CRS, then the given envelope is returned unchanged. Otherwise a new transformed envelope is returned.
      Performance tip
      If there is many envelopes to transform with the same source and target CRS, then it is more efficient to get the `CoordinateOperation` or `MathTransform` instance once and invoke one of the others `transform(…)` methods.
      Parameters:
        `envelope` - the envelope to transform (may be `null`).
        `targetCRS` - the target CRS (may be `null`).
      Returns:
        a new transformed envelope, or directly `envelope` if no change was required.
      Throws:
        `TransformException` - if a transformation was required and failed.
      Since:
        0.5

    - #### transform

          public static GeneralEnvelope transform(MathTransform transform,
                                                  Envelope envelope)
                                           throws TransformException

      Transforms an envelope using the given math transform. The transformation is only approximative: the returned envelope may be bigger than necessary, or smaller than required if the bounding box contains a pole.
      Limitation
      This method can not handle the case where the envelope contains the North or South pole, or when it crosses the ±180° longitude, because `MathTransform` does not carry sufficient information. For a more robust envelope transformation, use `transform(CoordinateOperation, Envelope)` instead.
      Parameters:
        `transform` - the transform to use.
        `envelope` - envelope to transform, or `null`. This envelope will not be modified.
      Returns:
        the transformed envelope, or `null` if `envelope` was null.
      Throws:
        `TransformException` - if a transform failed.
      Since:
        0.5
      See Also:
        `transform(CoordinateOperation, Envelope)`

    - #### transform

          public static GeneralEnvelope transform(CoordinateOperation operation,
                                                  Envelope envelope)
                                           throws TransformException

      Transforms an envelope using the given coordinate operation. The transformation is only approximative: the returned envelope may be bigger than the smallest possible bounding box, but should not be smaller in most cases.

      This method can handle the case where the envelope contains the North or South pole, or when it cross the ±180° longitude.

      Note: If the envelope CRS is non-null, then the caller should ensure that the operation source CRS is the same than the envelope CRS. In case of mismatch, this method transforms the envelope to the operation source CRS before to apply the operation. This extra step may cause a lost of accuracy. In order to prevent this method from performing such pre-transformation (if not desired), callers can ensure that the envelope CRS is `null` before to call this method.
      Parameters:
        `operation` - the operation to use.
        `envelope` - envelope to transform, or `null`. This envelope will not be modified.
      Returns:
        the transformed envelope, or `null` if `envelope` was null.
      Throws:
        `TransformException` - if a transform failed.
      Since:
        0.5
      See Also:
        `transform(MathTransform, Envelope)`

    - #### fromWKT

          public static Envelope fromWKT(CharSequence wkt)
                                  throws FactoryException

      Returns the bounding box of a geometry defined in Well Known Text (WKT) format. This method does not check the consistency of the provided WKT. For example it does not check that every points in a `LINESTRING` have the same dimension. However this method ensures that the parenthesis are balanced, in order to catch some malformed WKT.

      Example:

      - `BOX(-180 -90, 180 90)` (not really a geometry, but understood by many software products)
      - `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))`
      See `GeneralEnvelope​.GeneralEnvelope(CharSequence)` for more information about the parsing rules.
      Parameters:
        `wkt` - the `BOX`, `POLYGON` or other kind of element to parse.
      Returns:
        the envelope of the given geometry.
      Throws:
        `FactoryException` - if the given WKT can not be parsed.
      See Also:
        `toString(Envelope)`, `CRS​.fromWKT(String)`, `org​.apache​.sis​.io​.wkt`

    - #### toString

          public static String toString(Envelope envelope)

      Formats the given envelope as a `BOX` element. The output is like below, where n is the number of dimensions (omitted if equals to 2):

      > `BOX` n `D(`lower corner`,` upper corner`)`

      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.
      The string returned by this method can be parsed by the `GeneralEnvelope` constructor.
      Parameters:
        `envelope` - the envelope to format.
      Returns:
        this envelope as a `BOX` or `BOX3D` (most typical dimensions) element.
      See Also:
        `fromWKT(CharSequence)`, `org​.apache​.sis​.io​.wkt`

    - #### toPolygonWKT

          public static String toPolygonWKT(Envelope envelope)
                                     throws IllegalArgumentException

      Formats the given envelope as a `POLYGON` element in the Well Known Text (WKT) format. `POLYGON` can be used as an alternative to `BOX` when the element needs to be considered as a standard WKT geometry.

      The string returned by this method can be parsed by the `GeneralEnvelope` constructor.

      Parameters:
        `envelope` - the envelope to format.
      Returns:
        the envelope as a `POLYGON` in WKT format.
      Throws:
        `IllegalArgumentException` - if the given envelope can not be formatted.
      See Also:
        `org​.apache​.sis​.io​.wkt`

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.