Package org.apache.sis.referencing

# Enum CommonCRS.Vertical

Object
Enum<CommonCRS.Vertical>
Vertical

All Implemented Interfaces:
  `Serializable`, `Comparable<CommonCRS​.Vertical>`, `Constable`

Enclosing class:
  CommonCRS

public static enum CommonCRS.Vertical extends Enum<CommonCRS.Vertical>
Frequently-used vertical CRS and datum that are guaranteed to be available in SIS. Methods in this enumeration are shortcuts for object definitions in the EPSG database. If there is no EPSG database available, or if the query failed, or if there is no EPSG definition for an object, then `Vertical` fallback on hard-coded values. Consequently, those methods never return `null`.

Referencing objects are cached after creation. Invoking the same method on the same `Vertical` instance twice will return the same `IdentifiedObject` instance, unless the internal cache has been cleared (e.g. the application is running in a container environment and some modules have been installed or uninstalled).

Example: the following code fetches a vertical Coordinate Reference System for heights above the Mean Sea Level (MSL):

>     VerticalCRS crs = CommonCRS.Vertical.MEAN_SEA_LEVEL.crs();

Below is an alphabetical list of object names available in this enumeration:

> Geodetic objects accessible by enumeration constants
> Name or alias | Object type | Enumeration value
> --- | --- | ---
> Barometric altitude | CRS, Datum | `BAROMETRIC`
> Mean Sea Level | Datum | `MEAN_SEA_LEVEL`
> Mean Sea Level depth | CRS | `DEPTH`
> Mean Sea Level height | CRS | `MEAN_SEA_LEVEL`
> NAVD88 height | CRS | `NAVD88`
> North American Vertical Datum 1988 | Datum | `NAVD88`
> Other surface | CRS, Datum | `OTHER_SURFACE`

Note: We do not provide a `GEOIDAL` value because its definition depends on the realization epoch. For example EGM84, EGM96 and EGM2008 are applications of three different geoid models on the WGS 84 ellipsoid. The `MEAN_SEA_LEVEL` value can be used instead as an approximation of geoidal heights.

Since:
  0.4
See Also:
  - `CommonAuthorityFactory`

Defined in the `sis-referencing` module

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class Enum

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

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `BAROMETRIC`
  Height measured by atmospheric pressure in hectopascals (hPa).
  `DEPTH`
  Depth measured below the Mean Sea Level (MSL) in metres.
  `ELLIPSOIDAL`
  Height measured along the normal to the ellipsoid used in the definition of horizontal datum.
  `MEAN_SEA_LEVEL`
  Height measured above the Mean Sea Level (MSL) in metres.
  `NAVD88`
  North American Vertical Datum 1988 height.
  `OTHER_SURFACE`
  Height measured above other kind of surface, for example a geological feature.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `VerticalCRS`
  `crs()`
  Returns the coordinate reference system associated to this vertical object.
  `VerticalDatum`
  `datum()`
  Returns the datum associated to this vertical object.
  `static CommonCRS​.Vertical`
  `valueOf(String name)`
  Returns the enum constant of this type with the specified name.
  `static CommonCRS​.Vertical[]`
  `values()`
  Returns an array containing the constants of this enum type, 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

  - ### BAROMETRIC

    public static final CommonCRS.Vertical BAROMETRIC
    Height measured by atmospheric pressure in hectopascals (hPa). Hectopascals are the units of measurement used by the worldwide meteorological community. The datum is not specific to any location or epoch.
    See Also:
      - `VerticalDatumType​.BAROMETRIC`

  - ### MEAN_SEA_LEVEL

    public static final CommonCRS.Vertical MEAN_SEA_LEVEL
    Height measured above the Mean Sea Level (MSL) in metres. Can be used as an approximation of geoidal heights (height measured above an equipotential surface), except that MSL are not specific to any location or epoch.

    > Mean Sea Level properties
    > EPSG identifiers: | 5714 (datum: 5100)
    > Primary names: | "MSL height" (datum: "Mean Sea Level")
    > Abbreviations or aliases: | "mean sea level height" (datum: "MSL")
    > Direction: | `AxisDirection.UP`
    > Unit: | `Units.METRE`

    See Also:
      - `VerticalDatumType​.GEOIDAL`

  - ### DEPTH

    public static final CommonCRS.Vertical DEPTH
    Depth measured below the Mean Sea Level (MSL) in metres.

    > Depth properties
    > EPSG identifiers: | 5715 (datum: 5100)
    > Primary names: | "MSL depth" (datum: "Mean Sea Level")
    > Abbreviations or aliases: | "mean sea level depth" (datum: "MSL")
    > Direction: | `AxisDirection.DOWN`
    > Unit: | `Units.METRE`

    See Also:
      - `VerticalDatumType​.GEOIDAL`

  - ### NAVD88

    public static final CommonCRS.Vertical NAVD88
    North American Vertical Datum 1988 height.

    > NAVD88 properties
    > WMS identifier: | CRS:88
    > EPSG identifiers: | 5703 (datum: 5103)
    > Primary names: | "NAVD88 height" (datum: "North American Vertical Datum 1988")
    > Abbreviations or aliases: | " North American Vertical Datum of 1988 height (m)" (datum: "NAVD88")
    > Direction: | `AxisDirection.UP`
    > Unit: | `Units.METRE`

    Since:
      0.7
    See Also:
      - `CommonCRS​.NAD83`

  - ### ELLIPSOIDAL

    public static final CommonCRS.Vertical ELLIPSOIDAL
    Height measured along the normal to the ellipsoid used in the definition of horizontal datum. The unit of measurement is metres.

    Ellipsoidal height is not part of ISO 19111 international standard. Such vertical CRS is usually not recommended since ellipsoidal heights make little sense without their (latitude, longitude) locations. The ISO specification defines instead three-dimensional `GeographicCRS` for that reason. Users are encouraged to avoid this orphan ellipsoidal height as much as possible.

  - ### OTHER_SURFACE

    public static final CommonCRS.Vertical OTHER_SURFACE
    Height measured above other kind of surface, for example a geological feature. The unit of measurement is metres.
    See Also:
      - `VerticalDatumType​.OTHER_SURFACE`

- ## Method Details

  - ### values

    public static CommonCRS.Vertical[] 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 CommonCRS.Vertical 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

  - ### crs

    public VerticalCRS crs()
    Returns the coordinate reference system associated to this vertical object. The following table summarizes the CRS known to this class, together with an enumeration value that can be used for fetching that CRS:

    > Commonly used vertical CRS
    > Name or alias | Enum | EPSG
    > --- | --- | ---
    > Barometric altitude | `BAROMETRIC` |
    > Mean Sea Level depth | `DEPTH` | 5715
    > Mean Sea Level height | `MEAN_SEA_LEVEL` | 5714
    > Other surface | `OTHER_SURFACE` |

    Returns:
      the CRS associated to this enum.
    See Also:
      - `DefaultVerticalCRS`

  - ### datum

    public VerticalDatum datum()
    Returns the datum associated to this vertical object. The following table summarizes the datum known to this class, together with an enumeration value that can be used for fetching that datum:

    > Commonly used vertical datum
    > Name or alias | Enum | EPSG
    > --- | --- | ---
    > Barometric altitude | `BAROMETRIC` |
    > Mean Sea Level | `MEAN_SEA_LEVEL` | 5100
    > Other surface | `OTHER_SURFACE` |

    Returns:
      the datum associated to this enum.
    See Also:
      - `DefaultVerticalDatum`