# Package org.apache.sis.referencing

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 repository web site.

Since:
  0.4

Defined in the `sis-referencing` module

- Related Packages
  Package
  Description
  org.apache.sis.referencing.crs
  Coordinate Reference System (CRS) definitions as coordinate systems related to the earth through datum.
  org.apache.sis.referencing.cs
  Coordinate System (CS) definitions as the set of coordinate system axes that spans the coordinate space.
  org.apache.sis.referencing.datum
  Relationship of a `CoordinateSystem` (an abstract mathematical entity) to the earth or other system.
  org.apache.sis.referencing.factory
  Creates Coordinate Reference System (CRS) objects from given properties or authority codes.
  org.apache.sis.referencing.gazetteer
  Mapping between geographic identifiers (addresses, grid indexes…) and locations (descriptions, coordinates…).
  org.apache.sis.referencing.operation
  Relationship between any two Coordinate Reference Systems (CRS).
- 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`.
  CommonCRS
  Frequently-used geodetic CRS and datum that are guaranteed to be available in SIS.
  CommonCRS.Engineering
  Frequently-used engineering 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.
  CRS
  Static methods working on Coordinate Reference Systems.
  GeodeticCalculator
  Performs geodetic calculations on a sphere or an ellipsoid.
  GeodeticException
  Unchecked exception thrown when an error occurred while computing a geodetic value.
  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`.