org.apache.sis.referencing.cs

## Enum AxesConvention

- Object
- - Enum<AxesConvention>
  - - AxesConvention

- All Implemented Interfaces:
    Serializable, Comparable<AxesConvention>, AxisFilter

      public enum AxesConvention
      extends Enum<AxesConvention>
      implements AxisFilter

  High-level characteristics about the axes of a coordinate system. This enumeration provides a convenient way to identify some common axes conventions like axis order or range of longitude values. Apache SIS Coordinate System objects can be made compliant to a given convention by calls to their `forConvention(AxesConvention)` method.

  The following table summarizes the coordinate system aspects that may be modified by each enum value, with an example of change applied by the enum. Blank cells mean that the property is not changed by the enum value.

  Coordinate system properties changed by enum values
  Property | Example | Normalized | Conventionally oriented | Right handed | Positive range
  --- | --- | --- | --- | --- | ---
  Axis order | (longitude, latitude) | ✔ | ✔ | ✔ |
  Axis direction | (east, north) | ✔ | ✔ |  |
  Unit of measurement | Angular degrees & metres | ✔ |  |  |
  Range of values | [0 … 360]° of longitude |  |  |  | ✔

  Discussion on axis order
  The axis order is specified by the authority (typically a national agency) defining the Coordinate Reference System (CRS). The order depends on the CRS type and the country defining the CRS. In the case of geographic CRS, the (latitude, longitude) axis order is widely used by geographers and pilotes for centuries. However software developers tend to consistently use the (x,y) order for every kind of CRS. Those different practices resulted in contradictory definitions of axis order for almost every CRS of kind `GeographicCRS`, for some `ProjectedCRS` in the South hemisphere (South Africa, Australia, etc.) and for some polar projections among others.

  Recent OGC standards mandate the use of axis order as defined by the authority. Oldest OGC standards used the (x,y) axis order instead, ignoring any authority specification. Many software products still use the old (x,y) axis order, because it is easier to implement. Apache SIS supports both conventions. By default, SIS creates CRS with axis order as defined by the authority. Those CRS are created by calls to the `CRS​.forCode(String)` method. The actual axis order can be verified after the CRS creation with `System​.out​.println(crs)`. If (x,y) axis order is wanted for compatibility with older OGC specifications or other software products, CRS forced to "longitude first" axis order can be created using the `CONVENTIONALLY_ORIENTED` or `NORMALIZED` enumeration value.

  Range of longitude values
  Most geographic CRS have a longitude axis defined in the [-180 … +180]° range. All map projections in Apache SIS are designed to work in that range. This is also the range of `Math` trigonometric functions like `atan2(y,x)`. However some data use the [0 … 360]° range instead. A geographic CRS can be shifted to that range of longitude values using the `POSITIVE_RANGE` enumeration value. The choice of longitude range will impact not only some coordinate conversions, but also the methods that verify the domain of validity (e.g. `GeneralEnvelope​.normalize()`).
  Since:
    0.4
  See Also:
    `AbstractCS​.forConvention(AxesConvention)`, `AbstractCRS​.forConvention(AxesConvention)`

  Defined in the `sis-referencing` module

- - ### Enum Constant Summary

    Enum Constants
    Enum Constant and Description
    `CONVENTIONALLY_ORIENTED` Axes are oriented toward conventional directions and ordered for a right-handed coordinate system.
    `NORMALIZED` Axes order, direction and units of measure are forced to commonly used pre-defined values.
    `POSITIVE_RANGE` Axes having a wraparound range meaning are shifted to their ranges of positive values.
    `RIGHT_HANDED` Axes are ordered for a right-handed coordinate system.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static AxesConvention` | `valueOf(String name)` Returns the enum constant of this type with the specified name.
    `static AxesConvention[]` | `values()` Returns an array containing the constants of this enum type, in the order they are declared.

    - ### Methods inherited from class Enum

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

    - ### Methods inherited from class Object

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

    - ### Methods inherited from interface AxisFilter

      `accept, getDirectionReplacement, getUnitReplacement`

- - ### Enum Constant Detail

    - #### NORMALIZED

          public static final AxesConvention NORMALIZED

      Axes order, direction and units of measure are forced to commonly used pre-defined values. This enum represents the following changes to apply on a coordinate system:
      - Axes are oriented and ordered as defined for `CONVENTIONALLY_ORIENTED` coordinate systems.
      - Known units are normalized (this list may be expanded in future SIS versions):
        - Angular units are set to `Units​.DEGREE`.
        - Linear units are set to `Units​.METRE`.
        - Temporal units are set to `Units​.DAY`.
      Current implementation does not normalize longitude values to the [-180 … +180]° range and does not set the prime meridian to Greenwich. However those rules may be adjusted in future SIS versions based on experience gained. For more predictable results, consider using `CONVENTIONALLY_ORIENTED` or `RIGHT_HANDED` instead.
      Rational: The reason why we do not yet normalize the range and the prime meridian is because doing so would cause the conversion between old and new coordinate systems to be non-affine for axes having `RangeMeaning​.WRAPAROUND`. Furthermore changing the prime meridian would be a datum change rather than a coordinate system change, and datum changes are more difficult to handle by coordinate operation factories.
      See Also:
        `CommonCRS​.normalizedGeographic()`, `CoordinateSystems​.replaceAxes(CoordinateSystem, AxisFilter)`

    - #### CONVENTIONALLY_ORIENTED

          public static final AxesConvention CONVENTIONALLY_ORIENTED

      Axes are oriented toward conventional directions and ordered for a right-handed coordinate system. Units of measurement are unchanged.

      More specifically, directions opposites to the following ones are replaced by their "forward" counterpart (e.g. `SOUTH` → `NORTH`):

      Axis directions used by convention
      Preferred `AxisDirection` | Purpose
      --- | ---
      `EAST`, `NORTH`, `UP`, `FUTURE` | Commonly used (x, y, z, t) directions for coordinates.
      `DISPLAY_RIGHT`, `DISPLAY_DOWN` | Commonly used (x, y) directions for screen devices.
      `ROW_POSITIVE`, `COLUMN_POSITIVE` | Indices in grids or matrices.

      Then, axes are ordered for `RIGHT_HANDED` coordinate system.
      Usage
      This enum is often used for deriving a coordinate system with the (longitude, latitude) or (x,y) axis order. We do not provide a "longitude or x axis first" enumeration value because such criterion is hard to apply to inter-cardinal directions and has no meaning for map projections over a pole, while the right-handed rule can apply everywhere.

      Right-handed coordinate systems have a precise meaning in Apache SIS. However conventionally oriented coordinate systems have a looser definition. A similar concept appears in the Web Map Services (WMS) 1.3 specification, quoted here:

      6.7.2 Map CS — The usual orientation of the Map CS shall be such that the i axis is parallel to the East-to-West axis of the Layer CRS and increases Eastward, and the j axis is parallel to the North-to-South axis of the Layer CRS and increases Southward. This orientation will not be possible in some cases, as (for example) in an orthographic projection over the South Pole. The convention to be followed is that, wherever possible, East shall be to the right edge and North shall be toward the upper edge of the Map CS.
      Since:
        0.5

    - #### RIGHT_HANDED

          public static final AxesConvention RIGHT_HANDED

      Axes are ordered for a right-handed coordinate system. Axis directions, ranges or ordinate values and units of measurement are unchanged. In the two-dimensional case, the handedness is defined from the point of view of an observer above the plane of the system.

      Note that a right-handed coordinate system does not guarantee that longitude or x axis will be first in every cases. The most notable exception is the case of (West, North) orientations. The following table lists that case, together with other common axis orientations. The axes orientations implied by this `RIGHT_HANDED` enum is shown, together with `CONVENTIONALLY_ORIENTED` axes for reference:

      Examples of left-handed and right-handed coordinate systems
      Left-handed | Right-handed | Conventionally oriented | Remarks
      --- | --- | --- | ---
      North, East | East, North | East, North | This is the most common case.
      West, North | North, West | East, North | This right-handed system has latitude first.
      South, West | West, South | East, North | Used for the mapping of southern Africa.
      South along 0°, South along 90° West | South along 90° West, South along 0° | (Same as right-handed) | Can be used for the mapping of North pole.

      See Also:
        `CoordinateSystems​.angle(AxisDirection, AxisDirection)`, Right-hand rule on Wikipedia

    - #### POSITIVE_RANGE

          public static final AxesConvention POSITIVE_RANGE

      Axes having a wraparound range meaning are shifted to their ranges of positive values. The units of measurement and range period (difference between maximum and minimum value) are unchanged.

      Note that projecting geometry objects from the old to the new coordinate system may require a non-affine conversion. Some geometries may need to be separated in two parts, and others may need to be merged.

      Usage
      The most frequent usage of this enum is for shifting longitude values from the [-180 … +180]° range to the [0 … 360]° range. However this enum could also be used with climatological calendars if their time axis has a wrapround range meaning.

      Note that conversions from an coordinate system using the [-180 … +180]° range to a coordinate system using the [0 … 360]° range may not be affine. For example the data in the West hemisphere ([-180 … 0]°) may need to move on the right side of the East hemisphere ([180 … 360]°).

      See Also:
        `RangeMeaning​.WRAPAROUND`

  - ### Method Detail

    - #### values

          public static AxesConvention[] values()

      Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

          for (AxesConvention c : AxesConvention.values())
              System.out.println(c);

      Returns:
        an array containing the constants of this enum type, in the order they are declared

    - #### valueOf

          public static AxesConvention valueOf(String name)

      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (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 type has no constant with the specified name
        `NullPointerException` - if the argument is null

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