# Package org.apache.sis.referencing

Base classes for reference systems used for general positioning. An explanation for this package is provided in the OpenGIS® javadoc. The remaining discussion on this page is specific to the SIS implementation.

The most commonly used kinds of Reference Systems in Apache SIS are the Coordinate Reference Systems (CRS), which handle coordinates of arbitrary dimensions. The SIS implementations can handle 2D and 3D coordinates, as well as 4D, 5D, etc. An other less-frequently used kind of Reference System uses labels instead, as in postal address. This package is the root for both kinds, with an emphasis on the one for coordinates. The two kinds of referencing system are implemented in the following packages:

- `org​.apache​.sis​.referencing​.crs` for referencing by coordinates (ISO 19111)
- `org​.apache​.sis​.referencing​.gazetteer` for referencing by geographic identifiers (ISO 19112), together with the linking from geographic identifiers to coordinates.

Fetching geodetic object instances
Geodetic objects can be instantiated either directly by specifying all information to a factory method or constructor, or indirectly by specifying the identifier of an entry in a database. In particular, the EPSG database provides definitions for many geodetic objects, and Apache SIS provides convenience shortcuts for some of them in the `CommonCRS` enumerations. Other convenience methods are `CRS​.forCode(String)`, `CRS​.fromWKT(String)` and `CRS​.fromXML(String)`
Usage example
The following example projects a (latitude, longitude) coordinate to a Universal Transverse Mercator projection in the zone of the coordinate:

>     GeographicCRS source = CommonCRS.WGS84.geographic();
>     ProjectedCRS  target = CommonCRS.WGS84.UTM(20, 30);                        // 20°N 30°E   (watch out axis order!)
>     CoordinateOperation operation = CRS.findOperation(source, target, null);
>     if (CRS.getLinearAccuracy(operation) > 100) {
>         // If the accuracy is coarser than 100 metres (or any other threshold at application choice)
>         // maybe the operation is not suitable. Decide here what to do (throw an exception, etc).
>     }
>     MathTransform mt = operation.getMathTransform();
>     DirectPosition position = new DirectPosition2D(20, 30);                    // 20°N 30°E   (watch out axis order!)
>     position = mt.transform(position, position);
>     System.out.println(position);

The EPSG database
The EPSG geodetic parameter dataset is a structured database required to:

- define Coordinate Reference Systems (CRS) such that coordinates describe positions unambiguously;
- define Coordinate Operations that allow coordinates to be changed from one CRS to another CRS.

Various programmatic elements in Apache SIS have a relationship with EPSG entries, including:

- classes or methods implementing a specific coordinate operation method;
- enumeration constants representing some specific CRS;
- fields containing parameter values.

Relationship with EPSG has two components documented in the javadoc: the object type and the EPSG code. The type specifies which `AuthorityFactory` method to invoke, while the code specifies the argument value to give to that method in order to get the EPSG object. For example the `CommonCRS​.WGS84` documentation said that object of type geodetic datum is associated to code `EPSG:6326`. This means that the EPSG object could be obtained by the following code:

>     DatumAuthorityFactory factory = ...; // TODO: document how to obtain an EPSG factory.
>     GeodeticDatum datum = factory.createGeodeticDatum("6326");

The EPSG objects can also be inspected online on the EPSG registry web site.

Since:
  0.4

Defined in the `sis-referencing` module

- Class Summary
  Class | Description
  --- | ---
  AbstractIdentifiedObject | Base class for objects identified by a name or a code.
  AbstractReferenceSystem | Description of a spatial and temporal reference system used by a dataset.
  Builder<B extends Builder<B>> | Base class of builders for various kind of `IdentifiedObject`.
  CRS | Static methods working on Coordinate Reference Systems.
  GeodeticCalculator | Performs geodetic calculations on a sphere or an ellipsoid.
  IdentifiedObjects | Utility methods working on arbitrary implementations of the `IdentifiedObject` interface.
  ImmutableIdentifier | Immutable value uniquely identifying an object within a namespace, together with a version.
  NamedIdentifier | An identification of a CRS object which is both a `Identifier` and a `GenericName`.

- Enum Summary
  Enum | Description
  --- | ---
  CommonCRS | Frequently-used geodetic CRS and datum that are guaranteed to be available in SIS.
  CommonCRS.Temporal | Frequently-used temporal CRS and datum that are guaranteed to be available in SIS.
  CommonCRS.Vertical | Frequently-used vertical CRS and datum that are guaranteed to be available in SIS.

- Exception Summary
  Exception | Description
  --- | ---
  GeodeticException | Unchecked exception thrown when an error occurred while computing a geodetic value.