Module org.apache.sis.referencing

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. Another 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:

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 Common­CRS enumerations. Other convenience methods are CRS​.for­Code(String), CRS​.from­WKT(String) and CRS​.from­XML(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: 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 Authority­Factory 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 Common­CRS​.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