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

Enum Class WraparoundMethod

Object
Enum<WraparoundMethod>
WraparoundMethod
All Implemented Interfaces:
Serializable, Comparable<Wraparound­Method>, 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 General­Envelope 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:

  • 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 General­Envelope 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:

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

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

  • 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:
      Illegal­Argument­Exception - if this enum class has no constant with the specified name
      Null­Pointer­Exception - if the argument is null