Coordinate operations may include many steps, each with their own set of parameters. For example transformations from one datum (e.g. NAD27) to another datum (e.g. WGS84) can be approximated by an affine transform (translation, rotation and scale) applied on the geocentric coordinates. This implies that the coordinates must be converted from geographic to geocentric domain before the affine transform, then back to geographic domain after the affine transform. The result is a three-steps process illustrated in the “Conceptual chain of operations” column of the example below. However because that operation chain is very common, the EPSG geodetic dataset provides a shortcut named “Geocentric translation in geographic domain”. Using this operation, the conversion steps between geographic and geocentric CRS are implicit. Consequently the datum shifts as specified by EPSG appears as if it was a single operation, but the real operation executed by Apache SIS is divided in more steps.
Example: transformation of geographic coordinates from NAD27 to WGS84 in Canada can be approximated by the EPSG:1172 coordinate operation. This single EPSG operation is actually a chain of three operations in which two steps are implicit. The operation as specified by EPSG is shown in the first column below. The same operation with the two hidden steps made explicit is shown in the second column. The last column shows the same operation as implemented by Apache SIS under the hood, which contains additional operations discussed below. For all columns, input coordinates of the first step and output coordinates of the last step are (latitude, longitude) coordinates in degrees.
The operation chain actually performed by Apache SIS is very different than the conceptual operation chain because the coordinate systems are not the same. Except for the first and last ones, all Apache SIS steps work on right-handed coordinate systems (as opposed to the left-handed coordinate system when latitude is before longitude), with angular units in radians (instead of degrees) and linear units relative to an ellipsoid of semi-major axis length of 1 (instead of Earth’s size). Working in those coordinate systems requires additional steps for unit conversions and axes swapping at the beginning and at the end of the chain. Apache SIS uses affine parametric conversions for this purpose, which allow to combine axes swapping and unit conversions in a single step (see affine transform for more information). The reason why Apache SIS splits conceptual operations in such fine-grained operations is to allow more efficient concatenations of operation steps. This approach often allows cancellation of two consecutive affine transforms, for example a conversion from radians to degrees (e.g. after a geocentric to ellipsoid conversion) immediately followed by a conversion from degrees to radians (e.g. before a map projection). Another example is the Affine parametric transformation step above, which combines both the geocentric translation step and a scale factor implied by the ellipsoid change.
All those operation chains can be viewed in Well Known Text (WKT) or pseudo-WKT format.
The simplest operation chain, as specified by the authority, is given directly by the
String representation of the CoordinateOperation instance.
This WKT 2 representation contains not only a description of operations with their parameter values,
but also additional information about the context in which the operation applies (the source and target CRS)
together with some metadata like the accuracy and domain of validity.
Some operation steps and parameters may be omitted if they can be inferred from the context.
Example:
the WKT 2 representation on the right is for the same coordinate operation than the one used in previous example.
This representation can be obtained by a call to System.out.println(cop)
where cop is a CoordinateOperation instance.
Some characteristics of this representation are:
The SourceCRS and TargetCRS elements determine axis order and units.
For this reason, axis swapping and unit conversions do not need to be represented in this WKT.
The “Geocentric translation in geographic domain” operation implies conversions between geographic and geocentric coordinate reference systems.
Ellipsoid semi-axis lengths are inferred from above SourceCRS and TargetCRS elements,
so they do not need to be specified in this WKT.
The operation accuracy (20 metres) is much greater than the numerical floating-point precision. This kind of metadata could hardly be guessed from the mathematical function alone.
CoordinateOperation["NAD27 to WGS 84 (3)", SourceCRS[full CRS definition required here but omitted for brevity], TargetCRS[full CRS definition required here but omitted for brevity], Method["Geocentric translations (geog2D domain)"], Parameter["X-axis translation", -10.0, Unit["metre", 1]], Parameter["Y-axis translation", 158.0, Unit["metre", 1]], Parameter["Z-axis translation", 187.0, Unit["metre", 1]], OperationAccuracy[20.0], Area["Canada - onshore and offshore"], BBox[40.04, -141.01, 86.46, -47.74], Id["EPSG", 1172, "8.9"]]
An operation chain closer to what Apache SIS really performs is given by the
String representation of the MathTransform instance.
In this WKT 1 representation, contextual information and metadata are lost;
a MathTransform is like a mathematical function with no knowledge about the meaning of the coordinates on which it operates.
Since contextual information are lost, implicit operations and parameters become explicit.
This representation is useful for debugging since any axis swapping operation (for example) become visible.
Apache SIS constructs this representation from the data structure in memory,
but convert them in a more convenient form for human, for example by converting radians to degrees.
Example:
the WKT 1 representation on the right is for the same coordinate operation than the one used in previous example.
This representation can be obtained by a call to System.out.println(cop.getMathTransform())
where cop is a CoordinateOperation instance.
Some characteristics of this representation are:
Since there is not anymore (on intent) any information about source and target CRS, axis swapping (if needed) and unit conversions must be performed explicitly. This is the task of the first and last affine operations in this WKT.
The “Geocentric translation” operation is not anymore applied in the geographic domain, but in the geocentric domain. Consequently conversions between geographic and geocentric coordinate reference systems must be made explicit. Those explicit steps are also necessary for specifying the ellipsoid semi-axis lengths, since they cannot anymore by inferred for source and target CRS.
Conversions between geographic and geocentric coordinates are three-dimensional. Consequently operations for increasing and reducing the number of dimensions are inserted. By default the ellipsoidal height before conversion is set to zero.
Concat_MT[
Param_MT["Affine parametric transformation",
Parameter[parameters performing axis swapping omitted for brevity]],
Inverse_MT[Param_MT["Geographic3D to 2D conversion"]],
Param_MT["Geographic/geocentric conversions",
Parameter["semi_major", 6378206.4],
Parameter["semi_minor", 6356583.8]],
Param_MT["Geocentric translations (geocentric domain)",
Parameter["X-axis translation", -10.0],
Parameter["Y-axis translation", 158.0],
Parameter["Z-axis translation", 187.0]],
Param_MT["Geocentric_To_Ellipsoid",
Parameter["semi_major", 6378137.0],
Parameter["semi_minor", 6356752.314245179]],
Param_MT["Geographic3D to 2D conversion"],
Param_MT["Affine parametric transformation",
Parameter[parameters performing axis swapping omitted for brevity]]]
The latter form is often useful for debugging. If a coordinate operation seems to produce wrong results, inspecting the Well Known Text like above should be the first thing to do. The Frequently Asked Questions page gives more tips about common causes of coordinate transformation errors.