Enum Convention

java.lang.Object
java.lang.Enum<Convention>
org.apache.sis.io.wkt.Convention
All Implemented Interfaces:
Serializable, Comparable<Convention>, java.lang.constant.Constable

public enum Convention extends Enum<Convention>
The convention to use for WKT formatting. This enumeration specifies whether to use the Well Known Text format defined by ISO 19162 (also known as “WKT 2”), or whether to use the format previously defined in OGC 01-009 (referenced as “WKT 1”).

WKT 1 variants

The WKT 2 format should be parsed and formatted consistently by all software products. But the WKT 1 format has been interpreted differently by various implementers. Apache SIS can adapt itself to different WKT variants, sometimes automatically. But some aspects cannot be guessed. One noticeable source of confusion is the unit of measurement of PRIMEM[…] and PARAMETER[…] elements:
  • The unit of the Prime Meridian shall be the angular unit of the enclosing Geographic CRS according the OGC 01-009 (Coordinate transformation services) specification.
  • An older specification — Simple Features — was unclear on this matter and has been interpreted by many software products as fixing the unit to decimal degrees.
  • Some software products support only (longitude, latitude) axis order and ignore completely all AXIS[…] elements in the WKT.
Despite the first interpretation being specified by both OGC 01-009 and ISO 19162 standards, the second interpretation appears to be in wide use for WKT 1. Apache SIS uses the standard interpretation by default, but the WKT1_COMMON_UNITS enumeration allows parsing and formatting using the older interpretation. The WKT1_IGNORE_AXES enumeration mimics the most minimalist WKT 1 parsers, but should be avoided when not imposed by compatibility reasons.
Since:
0.4
Version:
0.6
See Also:
  • Nested Class Summary

    Nested classes/interfaces inherited from class java.lang.Enum

    Enum.EnumDesc<E extends Enum<E>>
  • Enum Constant Summary

    Enum Constants
    Enum Constant
    Description
    A special convention for formatting objects as stored internally by Apache SIS.
    The OGC 01-009 format, also known as “WKT 1”.
    The Simple Feature format, also known as “WKT 1”.
    The Simple Feature format without parsing of axis elements.
    The ISO 19162 format, also known as “WKT 2”.
    The ISO 19162 format with omission of some optional elements.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) static final Convention
    The default conventions.
    private final boolean
    true for using WKT 1 syntax, or false for using WKT 2 syntax.
    (package private) final boolean
    true for using short upper-case keywords by default.
    (package private) final boolean
    true for a frequently-used convention about units instead of the standard one.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Convention(boolean isWKT1, boolean toUpperCase, boolean usesCommonUnits)
    Creates a new enumeration value.
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) final org.opengis.metadata.citation.Citation
    Returns the default authority to look for when fetching identified object names and identifiers.
    boolean
    Returns true if this convention is one of the simplified variants of WKT.
    int
    Returns the major version of the Well Known Text represented by this convention.
    (package private) final boolean
    true if the identifiers should be formatted for all elements instead of only the last one.
    static Convention
    Returns the enum constant of this type with the specified name.
    static Convention[]
    Returns an array containing the constants of this enum type, in the order they are declared.

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait
  • Enum Constant Details

    • WKT2

      public static final Convention WKT2
      The ISO 19162 format, also known as “WKT 2”. This convention follows the ISO recommendations.

      Unless otherwise specified by WKTFormat.setNameAuthority(Citation), projections and parameters formatted with this convention will use the EPSG names when available.

      This is the default convention used by FormattableObject.toWKT() and for new WKTFormat instances.

      See Also:
    • WKT2_SIMPLIFIED

      public static final Convention WKT2_SIMPLIFIED
      The ISO 19162 format with omission of some optional elements. This convention is identical to the WKT2 convention except for the following aspects:
      • By default long keywords are used instead of short ones (e.g. "GeodeticCRS" instead of "GeodCRS") except for the "Unit" keyword, because they match the class or interface names.
      • PrimeMeridian element omitted if the meridian is Greenwich.
      • Axis element omits the Order sub-element.
      • Unit elements are less verbose:
        • Ellipsoid and VerticalExtent elements omit the LengthUnit sub-element if that unit is Units.METRE.
        • Parameter elements omit the LengthUnit sub-element if that unit is the same than the unit of the ProjectedCRS axes.
        • Parameter and PrimeMeridian elements omit the AngleUnit sub-element if that unit is the same than the unit of the GeodeticCRS axes.
        • Axes unit is declared only once after the axes instead of repeated for each axis if the unit is the same for all axes.
        • AngleUnit, LengthUnit, ScaleUnit, ParametricUnit and TimeUnit are formatted as plain Unit elements.
      • Id is formatted only for the root element (omit parameters and operation methods Id).
      Those modifications are allowed by the ISO 19162 standard, so the WKT is still valid.

      This is the default convention used by FormattableObject.toString().

    • WKT1

      public static final Convention WKT1
      The OGC 01-009 format, also known as “WKT 1”. A definition for this format is shown in Extended Backus Naur Form (EBNF) on GeoAPI.

      Unless otherwise specified by WKTFormat.setNameAuthority(Citation), projections and parameters formatted with this convention will use the OGC names when available.

      Differences compared to WKT 2

      WKT 1 and WKT 2 differ in their keywords and syntax, but also in more subtle ways regarding axis names, parameter and code list values. For example, in GeocentricCRS, WKT 1 uses a legacy set of Cartesian axes which were defined in OGC 01-009. Those axes use the Other, Easting and Northing axis directions instead of the geocentric ones. For more uniform handling of CRS objects in client code, SIS parser replaces some WKT 1 conventions by the ISO ones when possible.
      Geocentric axis directions
      ISO 19111 OGC 01-009 Description
      Geocentric X Other Toward prime meridian
      Geocentric Y Easting Toward 90°E longitude
      Geocentric Z Northing Toward north pole
      Coordinate system axis names
      CRS type WKT1 names ISO abbreviations
      Geographic Lon, Lat λ, φ
      Vertical H H or h
      Projected X, Y E, N
      Geocentric X, Y, Z X, Y, Z
      See Also:
    • WKT1_COMMON_UNITS

      public static final Convention WKT1_COMMON_UNITS
      The Simple Feature format, also known as “WKT 1”. Simple Feature is anterior to OGC 01-009 and defines the same format, but was unclear about the unit of measurement for prime meridians and projection parameters. Consequently, many implementations interpreted those angular units as fixed to degrees instead than being context-dependent.

      This convention is identical to WKT1 except for the following aspects:

      • The angular units of PRIMEM and PARAMETER elements are always degrees, no matter the units of the enclosing GEOGCS element.
      • Unit names use American spelling instead of the international ones (e.g. "meter" instead of "metre").
    • WKT1_IGNORE_AXES

      public static final Convention WKT1_IGNORE_AXES
      The Simple Feature format without parsing of axis elements. This convention is identical to WKT1_COMMON_UNITS except that all AXIS[…] elements are ignored. Since the WKT 1 specification said that the default axis order shall be (x,y) or (longitude, latitude), ignoring AXIS[…] elements is equivalent to forcing the coordinate systems to that default order.

      Note that AXIS[…] elements still need to be well formed even when parsing a text with this convention. Malformed axis elements will continue to cause a ParseException despite their content being ignored.

      This convention may be useful for compatibility with some other software products that do not handle axis order correctly. But except when imposed by such compatibility reasons, this convention should be avoided as much as possible.

      Since:
      0.6
    • INTERNAL

      @Debug public static final Convention INTERNAL
      A special convention for formatting objects as stored internally by Apache SIS. The result is similar to the one produced using the WKT2_SIMPLIFIED convention, with the following differences:
      • All quoted texts (not only the remarks) preserve non-ASCII characters.
      • Map projections are shown as SIS stores them internally, i.e. with the separation between linear and non-linear steps, rather than as a single operation.
      • Parameter elements omit the unit of measurement if that unit is equal to the default unit (as declared in the parameter descriptor).
      • CompoundCRS elements show nested compound CRS if any (the structure is not flattened).
      • Id elements are formatted for child elements in addition to the root one.
      • Id element omits the URI sub-element if the latter is derived by Apache SIS from the Id properties.
      • Remarks element is formatted for all identified objects, not only CRS or coordinate operations.
      • Additional attributes not defined by ISO 19162 may be formatted:
      This convention is used only for debugging purpose.
      See Also:
  • Field Details

    • DEFAULT

      static final Convention DEFAULT
      The default conventions.
    • isWKT1

      private final boolean isWKT1
      true for using WKT 1 syntax, or false for using WKT 2 syntax.
    • toUpperCase

      final boolean toUpperCase
      true for using short upper-case keywords by default.
    • usesCommonUnits

      final boolean usesCommonUnits
      true for a frequently-used convention about units instead of the standard one.
      • If true, forces PRIMEM and PARAMETER angular units to degrees instead of inferring the unit from the context. The standard value is false, which means that the angular units are inferred from the context as required by the WKT 1 specification.
      • If true, uses US unit names instead of the international names. For example, Americans said "meter" instead of "metre".
  • Constructor Details

    • Convention

      private Convention(boolean isWKT1, boolean toUpperCase, boolean usesCommonUnits)
      Creates a new enumeration value.
  • Method Details

    • values

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

      public static Convention 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
    • majorVersion

      public int majorVersion()
      Returns the major version of the Well Known Text represented by this convention. In current Apache SIS implementation, this method can return only 1 or 2.
      Returns:
      1 if this convention is one of the WKT 1 variants, or 2 otherwise.
    • isSimplified

      public boolean isSimplified()
      Returns true if this convention is one of the simplified variants of WKT. The simplifications are documented in the WKT2_SIMPLIFIED javadoc.

      This methods consider version 1 of WKT as a “simplified” convention, since this version was indeed simpler than version 2.

      Returns:
      true it this convention uses a simplified variant of WKT.
    • showIdentifiers

      final boolean showIdentifiers()
      true if the identifiers should be formatted for all elements instead of only the last one.
    • getNameAuthority

      final org.opengis.metadata.citation.Citation getNameAuthority()
      Returns the default authority to look for when fetching identified object names and identifiers. The difference between various authorities are most easily seen in projection and parameter names. The value returned by this method can be overwritten by WKTFormat.setNameAuthority(Citation).
      Example: The following table shows the names given by various organizations or projects for the same projection:
      Map projection name examples
      Authority Projection name
      EPSG Mercator (variant A)
      OGC Mercator_1SP
      GEOTIFF CT_Mercator
      Returns:
      the organization, standard or project to look for when fetching Map Projection parameter names.
      See Also: