Class MolodenskyTransform

All Implemented Interfaces:
`Serializable`, `Parameterized`, `Lenient­Comparable`, `Math­Transform`

public class MolodenskyTransform extends DatumShiftTransform
Two- or three-dimensional datum shift using the (potentially abridged) Molodensky transformation. The Molodensky transformation (EPSG:9604) and the abridged Molodensky transformation (EPSG:9605) transform geographic points from one geographic coordinate reference system to another (a datum shift). The Molodensky formulas are approximations of Geocentric translation (geographic domain) transformations (EPSG:1035 and 9603), but performed directly on geographic coordinates without Geographic/Geocentric conversions.

`Molodensky­Transform`s works conceptually on three-dimensional coordinates, but the ellipsoidal height can be omitted resulting in two-dimensional coordinates. No dimension other than 2 or 3 are allowed.

• If the height is omitted from the input coordinates (`is­Source3D` = `false`), then the source dimensions is 2 and the height is assumed to be zero.
• If the height is omitted from the output coordinates (`is­Target3D` = `false`), then the target dimensions is 2 and the computed height (typically non-zero even if the input height was zero) is lost.
The transform expect coordinate values if the following order:
1. longitudes (λ) relative to the prime meridian (usually Greenwich),
2. latitudes (φ),
3. optionally heights above the ellipsoid (h).
The units of measurements depend on how the `Math­Transform` has been created:
• `Molodensky­Transform` instances created directly by the constructor work with angular values in radians. That constructor is reserved for subclasses only.
• Transforms created by the `create­Geodetic­Transformation(…)` static method work with angular values in degrees and heights in the same units than the source ellipsoid axes (usually metres).

Comparison of Molodensky and geocentric translation

Compared to the "Geocentric translation (geographic domain)" method, the Molodensky method has errors usually within a few centimetres. The Abridged Molodensky method has more noticeable errors, of a few tenths of centimetres.

Another difference between Molodensky and geocentric translation methods is their behavior when crossing the anti-meridian. If a datum shift causes a longitude to cross the anti-meridian (e.g. 179.999° become 180.001°), the Molodensky method will keep 180.001° as-is while the geocentric translation method will wrap the longitude to -179.999°. Such wrap-around behavior may or may not be desired, depending on the applications.

Since:
0.7

Defined in the `sis-referencing` module

Nested classes/interfaces inherited from class AbstractMathTransform

`Abstract­Math­Transform​.Inverse`
• Field Summary

Fields
Modifier and Type
Field
Description
`protected final double`
`eccentricity­Squared`
The square of eccentricity of the source ellipsoid.
`protected final double`
`semi­Major`
Semi-major axis length (a) of the source ellipsoid.
`protected final double`
`t­X`
Shift along the geocentric X axis (toward prime meridian) in units of the semi-major axis of the source ellipsoid.
`protected final double`
`t­Y`
Shift along the geocentric Y axis (toward 90°E) in units of the semi-major axis of the source ellipsoid.
`protected final double`
`t­Z`
Shift along the geocentric Z axis (toward north pole) in units of the semi-major axis of the source ellipsoid.
• Constructor Summary

Constructors
Modifier
Constructor
Description
`protected `
```Molodensky­Transform(Ellipsoid source, boolean is­Source3D, Ellipsoid target, boolean is­Target3D, double t­X, double t­Y, double t­Z, boolean is­Abridged)```
Creates a Molodensky transform from the specified parameters.
• Method Summary

Modifier and Type
Method
Description
`protected int`
`compute­Hash­Code()`
Computes a hash value for this transform.
`static Math­Transform`
```create­Geodetic­Transformation(Math­Transform­Factory factory, Ellipsoid source, boolean is­Source3D, Ellipsoid target, boolean is­Target3D, double t­X, double t­Y, double t­Z, boolean is­Abridged)```
Creates a transformation between two from geographic CRS.
`boolean`
```equals(Object object, Comparison­Mode mode)```
Compares the specified object with this math transform for equality.
`Parameter­Descriptor­Group`
`get­Parameter­Descriptors()`
Returns a description of the internal parameters of this `Molodensky­Transform` transform.
`Parameter­Value­Group`
`get­Parameter­Values()`
Returns a copy of internal parameter values of this transform.
`final int`
`get­Source­Dimensions()`
Gets the dimension of input points.
`final int`
`get­Target­Dimensions()`
Gets the dimension of output points.
`Math­Transform`
`inverse()`
Returns the inverse of this Molodensky transform.
`boolean`
`is­Identity()`
Returns `true` if this transform is the identity one.
`Matrix`
```transform(double[] src­Pts, int src­Off, double[] dst­Pts, int dst­Off, boolean derivate)```
Transforms the (λ,φ) or (λ,φ,h) coordinates between two geographic CRS, and optionally returns the derivative at that location.
`void`
```transform(double[] src­Pts, int src­Off, double[] dst­Pts, int dst­Off, int num­Pts)```
Transforms the (λ,φ) or (λ,φ,h) coordinates between two geographic CRS.

Methods inherited from class DatumShiftTransform

`get­Contextual­Parameters`

Methods inherited from class AbstractMathTransform

`derivative, equals, format­To, hash­Code, transform, transform, transform, transform, try­Concatenate`

Methods inherited from class FormattableObject

`print, to­String, to­String, to­WKT`

Methods inherited from class Object

`clone, finalize, get­Class, notify, notify­All, wait, wait, wait`

Methods inherited from interface MathTransform

`to­WKT`
• Field Details

• tX

protected final double tX
Shift along the geocentric X axis (toward prime meridian) in units of the semi-major axis of the source ellipsoid.
• tY

protected final double tY
Shift along the geocentric Y axis (toward 90°E) in units of the semi-major axis of the source ellipsoid.
• tZ

protected final double tZ
Shift along the geocentric Z axis (toward north pole) in units of the semi-major axis of the source ellipsoid.
• semiMajor

protected final double semiMajor
Semi-major axis length (a) of the source ellipsoid.
• eccentricitySquared

protected final double eccentricitySquared
The square of eccentricity of the source ellipsoid. This can be computed by ℯ² = (a²-b²)/a² where a is the semi-major axis length and b is the semi-minor axis length.
• Constructor Details

• MolodenskyTransform

protected MolodenskyTransform(Ellipsoid source, boolean isSource3D, Ellipsoid target, boolean isTarget3D, double tX, double tY, double tZ, boolean isAbridged)
Creates a Molodensky transform from the specified parameters. This `Molodensky­Transform` class expects coordinate values in the following order and units:
1. longitudes in radians relative to the prime meridian (usually Greenwich),
3. optionally heights above the ellipsoid, in same units than the source ellipsoid axes.
For converting geographic coordinates in degrees, `Molodensky­Transform` instances need to be concatenated with the following affine transforms:
• Normalization before `Molodensky­Transform`:
• Conversion of (λ,φ) from degrees to radians.
• Denormalization after `Molodensky­Transform`:
• Conversion of (λ,φ) from radians to degrees.
After `Molodensky­Transform` construction, the full conversion chain including the above affine transforms can be created by `Datum­Shift­Transform​.get­Contextual­Parameters().complete­Transform(factory, this)}`.
Parameters:
`source` - the source ellipsoid.
`is­Source3D` - `true` if the source coordinates have a height.
`target` - the target ellipsoid.
`is­Target3D` - `true` if the target coordinates have a height.
`t­X` - the geocentric X translation in same units than the source ellipsoid axes.
`t­Y` - the geocentric Y translation in same units than the source ellipsoid axes.
`t­Z` - the geocentric Z translation in same units than the source ellipsoid axes.
`is­Abridged` - `true` for the abridged formula, or `false` for the complete one.
• Method Details

• createGeodeticTransformation

public static MathTransform createGeodeticTransformation(MathTransformFactory factory, Ellipsoid source, boolean isSource3D, Ellipsoid target, boolean isTarget3D, double tX, double tY, double tZ, boolean isAbridged) throws FactoryException
Creates a transformation between two from geographic CRS. This factory method combines the `Molodensky­Transform` instance with the steps needed for converting values between degrees to radians. The transform works with input and output coordinates in the following units:
1. longitudes in degrees relative to the prime meridian (usually Greenwich),
2. latitudes in degrees,
3. optionally heights above the ellipsoid, in same units than the source ellipsoids axes.
Parameters:
`factory` - the factory to use for creating the transform.
`source` - the source ellipsoid.
`is­Source3D` - `true` if the source coordinates have a height.
`target` - the target ellipsoid.
`is­Target3D` - `true` if the target coordinates have a height.
`t­X` - the geocentric X translation in same units than the source ellipsoid axes.
`t­Y` - the geocentric Y translation in same units than the source ellipsoid axes.
`t­Z` - the geocentric Z translation in same units than the source ellipsoid axes.
`is­Abridged` - `true` for the abridged formula, or `false` for the complete one.
Returns:
the transformation between geographic coordinates in degrees.
Throws:
`Factory­Exception` - if an error occurred while creating a transform.
• isIdentity

public boolean isIdentity()
Returns `true` if this transform is the identity one. Molodensky transform is considered identity (minus rounding errors) if:
• the X,Y,Z shift are zero,
• difference between semi-major axis lengths (Δa) is zero,
• difference between flattening factors (Δf) is zero,
• the input and output dimension are the same.
Specified by:
`is­Identity` in interface `Math­Transform`
Overrides:
`is­Identity` in class `Abstract­Math­Transform`
Returns:
`true` if this transform is the identity transform.
• transform

public Matrix transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) throws TransformException
Transforms the (λ,φ) or (λ,φ,h) coordinates between two geographic CRS, and optionally returns the derivative at that location.
Specified by:
`transform` in class `Abstract­Math­Transform`
Parameters:
`src­Pts` - the array containing the source coordinate (can not be `null`).
`src­Off` - the offset to the point to be transformed in the source array.
`dst­Pts` - the array into which the transformed coordinate is returned. May be the same than `src­Pts`. May be `null` if only the derivative matrix is desired.
`dst­Off` - the offset to the location of the transformed point that is stored in the destination array.
`derivate` - `true` for computing the derivative, or `false` if not needed.
Returns:
the matrix of the transform derivative at the given source position, or `null` if the `derivate` argument is `false`.
Throws:
`Transform­Exception` - if the point can not be transformed or if a problem occurred while calculating the derivative.
• transform

public void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws TransformException
Transforms the (λ,φ) or (λ,φ,h) coordinates between two geographic CRS. This method performs the same transformation than `transform(double[], int, double[], int, boolean)`, but the formulas are repeated here for performance reasons.
Specified by:
`transform` in interface `Math­Transform`
Overrides:
`transform` in class `Abstract­Math­Transform`
Parameters:
`src­Pts` - the array containing the source point coordinates.
`src­Off` - the offset to the first point to be transformed in the source array.
`dst­Pts` - the array into which the transformed point coordinates are returned. May be the same than `src­Pts`.
`dst­Off` - the offset to the location of the first transformed point that is stored in the destination array.
`num­Pts` - the number of point objects to be transformed.
Throws:
`Transform­Exception` - if a point can not be transformed.
• inverse

public MathTransform inverse()
Returns the inverse of this Molodensky transform. The source ellipsoid of the returned transform will be the target ellipsoid of this transform, and conversely.
Specified by:
`inverse` in interface `Math­Transform`
Overrides:
`inverse` in class `Abstract­Math­Transform`
Returns:
a Molodensky transform from the target ellipsoid to the source ellipsoid of this transform.
• getParameterDescriptors

public ParameterDescriptorGroup getParameterDescriptors()
Returns a description of the internal parameters of this `Molodensky­Transform` transform. The returned group contains parameter descriptors for the number of dimensions and the eccentricity.
Note: this method is mostly for debugging purposes since the isolation of non-linear parameters in this class is highly implementation dependent. Most GIS applications will instead be interested in the contextual parameters.
Specified by:
`get­Parameter­Descriptors` in interface `Parameterized`
Overrides:
`get­Parameter­Descriptors` in class `Abstract­Math­Transform`
Returns:
a description of the internal parameters.
• getParameterValues

public ParameterValueGroup getParameterValues()
Returns a copy of internal parameter values of this transform. The returned group contains parameters for the source ellipsoid semi-axis lengths and the differences between source and target ellipsoid parameters.
Note: this method is mostly for debugging purposes since the isolation of non-linear parameters in this class is highly implementation dependent. Most GIS applications will instead be interested in the contextual parameters.
Specified by:
`get­Parameter­Values` in interface `Parameterized`
Overrides:
`get­Parameter­Values` in class `Datum­Shift­Transform`
Returns:
a copy of the internal parameter values for this transform.
• getSourceDimensions

public final int getSourceDimensions()
Gets the dimension of input points.
Specified by:
`get­Source­Dimensions` in interface `Math­Transform`
Specified by:
`get­Source­Dimensions` in class `Abstract­Math­Transform`
Returns:
the input dimension, which is 2 or 3.
• getTargetDimensions

public final int getTargetDimensions()
Gets the dimension of output points.
Specified by:
`get­Target­Dimensions` in interface `Math­Transform`
Specified by:
`get­Target­Dimensions` in class `Abstract­Math­Transform`
Returns:
the output dimension, which is 2 or 3.
• computeHashCode

protected int computeHashCode()
Computes a hash value for this transform. This method is invoked by `Abstract­Math­Transform​.hash­Code()` when first needed.
Overrides:
`compute­Hash­Code` in class `Datum­Shift­Transform`
Returns:
the hash code value. This value may change between different execution of the Apache SIS library.
• equals

public boolean equals(Object object, ComparisonMode mode)
Compares the specified object with this math transform for equality.
Specified by:
`equals` in interface `Lenient­Comparable`
Overrides:
`equals` in class `Datum­Shift­Transform`
Parameters:
`object` - the object to compare with this transform.
`mode` - the strictness level of the comparison. Default to `STRICT`.
Returns:
`true` if the given object is considered equals to this math transform.