Module org.apache.sis.referencing
Package org.apache.sis.geometry

# Enum Class WraparoundMethod

Object
Enum<WraparoundMethod>
WraparoundMethod

All Implemented Interfaces:
  `Serializable`, `Comparable<WraparoundMethod>`, `Constable`

public enum WraparoundMethod extends Enum<WraparoundMethod>
The strategy to use for representing a region crossing the anti-meridian or other wraparound limit. Envelopes crossing the anti-meridian have a "lower" longitude value greater than the "upper" value ("lower" and "upper" should actually be understood as "starting point" and "ending point" in those cases) — an illustration is provided in the `GeneralEnvelope` documentation. When such regions are used with libraries or algorithms that are not designed for handling wraparound axes, it may be necessary to convert those regions to simpler geometric representations that algorithm can handle. The `CONTIGUOUS`, `CONTIGUOUS_LOWER`, `CONTIGUOUS_UPPER` and `EXPAND` enumeration values are strategies for simplifying the problem at the cost of shifting geometries partially outside the coordinate system domain, or making geometry bigger than necessary.

## Alternatives

All methods in this enumeration change the envelope or geometry without changing the coordinate system. Another approach for solving the anti-meridian problem is to change the range of longitude values, for example using [0 … 360]° instead of [−180 … +180]°, and then normalize envelopes in that new range. But this approach is interesting only when all geometries are known to fit in the new range of longitude values, otherwise this approach is only moving the problem to another part of the world.

## Generalization

The documentation in this class talks about longitude values crossing the anti-meridian because it is the most common case. But Apache SIS actually handles wraparound axes in a generic way. The same discussion applies also for example to the temporal axis of climatological data (January averages, February averages, …, December averages then back to January).

Since:
  1.1
See Also:
  - `GeneralEnvelope​.wraparound(WraparoundMethod)`

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class Enum

  `Enum​.EnumDesc<E extends Enum<E>>`

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `CONTIGUOUS`
  Make geometries contiguous by possibly shifting any corner outside the coordinate system domain.
  `CONTIGUOUS_LOWER`
  Make geometries contiguous by possibly shifting lower corner outside the coordinate system domain.
  `CONTIGUOUS_UPPER`
  Make geometries contiguous by possibly shifting upper corner outside the coordinate system domain.
  `EXPAND`
  Possibly expand the envelope to include the whole area in a single envelope or geometry.
  `NONE`
  No check performed for wraparound axes.
  `NORMALIZE`
  Envelope represented in a way where "lower" value may be greater than "upper" value.
  `SPLIT`
  Possibly separate the envelope in as many simple envelopes or geometries as needed.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static WraparoundMethod`
  `valueOf(String name)`
  Returns the enum constant of this class with the specified name.
  `static WraparoundMethod[]`
  `values()`
  Returns an array containing the constants of this enum class, in the order they are declared.

  ### Methods inherited from class Enum

  `clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

  ### Methods inherited from class Object

  `getClass, notify, notifyAll, wait, wait, wait`

- ## Enum Constant Details

  - ### NONE

    public static final WraparoundMethod NONE
    No check performed for wraparound axes. If a normalized envelope crosses the anti-meridian (lower longitude value > upper value), then a polygon created from the 4 envelope corners would define a different area than the envelope: the "interior" and "exterior" of the geometry would be interchanged. Use this method only when knowing that the envelopes or geometries do not cross the anti-meridian.

    Example: given the `BBOX(+170 0, -170 1)` envelope, a polygon created from the 4 corners and ignoring the fact that the envelope crosses the anti-meridian may be as below:

        POLYGON(+170 0, -170 0, -170 1, +170 1, +170 0)

  - ### NORMALIZE

    public static final WraparoundMethod NORMALIZE
    Envelope represented in a way where "lower" value may be greater than "upper" value. This method can represent envelopes crossing the anti-meridian without the sacrifices imposed by other methods (moving a corner outside the coordinate system domain or expanding the envelope). However, this method can be used only with algorithms designed for handling this representation. This is the case of Apache SIS `GeneralEnvelope` but often not the case of geometry libraries.

    This method is said "normalized" because it is the only representation in Apache SIS which is guaranteed to produce consistent results when adding points to an envelope or when computing unions and intersections of envelopes. All other methods may produce unpredictable or sub-optimal results, depending for example whether two geometries have been made contiguous on the same side of the coordinate system domain (`CONTIGUOUS_LOWER` versus `CONTIGUOUS_UPPER`).

    See Also:
      - `GeneralEnvelope​.normalize()`

  - ### CONTIGUOUS_UPPER

    public static final WraparoundMethod CONTIGUOUS_UPPER
    Make geometries contiguous by possibly shifting upper corner outside the coordinate system domain. If a normalized envelope crosses the anti-meridian (upper longitude value < lower value), then an integer amount of cycles (360°) will be added to the upper longitude value until we get `upper > lower`. This will usually result in an upper corner value outside the [−180 … +180]° longitude range.

    Example: given the `BBOX(+170 0, -170 1)` envelope, a polygon created after shifting the "upper" corner (-170 1) may be as below:

        POLYGON(+170 0, +190 0, +190 1, +170 1, +170 0)

  - ### CONTIGUOUS_LOWER

    public static final WraparoundMethod CONTIGUOUS_LOWER
    Make geometries contiguous by possibly shifting lower corner outside the coordinate system domain. If a normalized envelope crosses the anti-meridian (lower longitude value > upper value), then an integer amount of cycles (360°) will be subtracted from the lower longitude value until we get `lower < upper`. This will usually result in a lower corner value outside the [−180 … +180]° longitude range.

    Example: given the `BBOX(+170 0, -170 1)` envelope, a polygon created after shifting the "lower" corner (+170 0) may be as below:

        POLYGON(-190 0, -170 0, -170 1, -190 1, -190 0)

  - ### CONTIGUOUS

    public static final WraparoundMethod CONTIGUOUS
    Make geometries contiguous by possibly shifting any corner outside the coordinate system domain. This method is equivalent to either `CONTIGUOUS_LOWER` or `CONTIGUOUS_UPPER`, depending which method minimizes the area outside the coordinate system domain.

  - ### EXPAND

    public static final WraparoundMethod EXPAND
    Possibly expand the envelope to include the whole area in a single envelope or geometry. If a normalized envelope crosses the anti-meridian (lower corner values > upper corner values), then the envelope is expanded to span an area from axis minimum value to axis maximum value. This ensures that the geometry contains the original envelope area but is wider. Compared to the `CONTIGUOUS` methods, this `EXPAND` method does not move any parts outside the coordinate system domain.

    Example: given the `BBOX(+170 0, -170 1)` envelope, a polygon created after expanding the envelope may be as below:

        POLYGON(-180 0, +180 0, +180 1, -180 1, -180 0)

    See Also:
      - `GeneralEnvelope​.simplify()`

  - ### SPLIT

    public static final WraparoundMethod SPLIT
    Possibly separate the envelope in as many simple envelopes or geometries as needed. If a normalized envelope crosses the anti-meridian (lower corner values > upper corner values), then a geometry created from this envelope will be composed of 2 or more polygons on each side of the coordinate system. This ensures that the geometries represent exactly the envelope interior but with more complexity.

    Example: given the `BBOX(+170 0, -170 1)` envelope, polygons created after splitting the envelope may be as below:

        MULTI-POLYGON(
            (-180 0,  -170 0,  -170 1,  -180 1,  -180 0)
            (+170 0,  +180 0,  +180 1,  +170 1,  +170 0))

    See Also:
      - `AbstractEnvelope​.toSimpleEnvelopes()`

- ## Method Details

  - ### values

    public static WraparoundMethod[] values()
    Returns an array containing the constants of this enum class, in the order they are declared.
    Returns:
      an array containing the constants of this enum class, in the order they are declared

  - ### valueOf

    public static WraparoundMethod valueOf(String name)
    Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
    Parameters:
      `name` - the name of the enum constant to be returned.
    Returns:
      the enum constant with the specified name
    Throws:
      `IllegalArgumentException` - if this enum class has no constant with the specified name
      `NullPointerException` - if the argument is null