org.apache.sis.referencing.operation.transform

Class MolodenskyTransform

Object

FormattableObject

AbstractMathTransform

DatumShiftTransform

MolodenskyTransform

All Implemented Interfaces:

Serializable, Parameterized, LenientComparable, MathTransform

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­Transforms 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 ordinate 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

See Also:

Serialized Form

Defined in the sis-referencing module

Nested Class Summary

Nested classes/interfaces inherited from class AbstractMathTransform

Abstract­Math­Transform.Inverse

Field Summary

Fields

Modifier and Type	Field and Description
protected double	eccentricitySquared The square of eccentricity of the source ellipsoid.
protected double	semiMajor Semi-major axis length (a) of the source ellipsoid.
protected double	tX Shift along the geocentric X axis (toward prime meridian) in units of the semi-major axis of the source ellipsoid.
protected double	tY Shift along the geocentric Y axis (toward 90°E) in units of the semi-major axis of the source ellipsoid.
protected double	tZ 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 and Description
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.

Method Summary

Modifier and Type	Method and Description
protected int	computeHashCode() Computes a hash value for this transform.
static MathTransform	createGeodeticTransformation(MathTransformFactory factory, Ellipsoid source, boolean isSource3D, Ellipsoid target, boolean isTarget3D, double tX, double tY, double tZ, boolean isAbridged) Creates a transformation between two from geographic CRS.
boolean	equals(Object object, ComparisonMode mode) Compares the specified object with this math transform for equality.
ParameterDescriptorGroup	getParameterDescriptors() Returns a description of the internal parameters of this Molodensky­Transform transform.
ParameterValueGroup	getParameterValues() Returns a copy of internal parameter values of this transform.
int	getSourceDimensions() Gets the dimension of input points.
int	getTargetDimensions() Gets the dimension of output points.
MathTransform	inverse() Returns the inverse of this Molodensky transform.
boolean	isIdentity() Returns true if this transform is the identity one.
Matrix	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) Transforms the (λ,φ) or (λ,φ,h) coordinates between two geographic CRS, and optionally returns the derivative at that location.
void	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) 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 Detail

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.

See Also:

Bursa­Wolf­Parameters.t­X

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.

See Also:

Bursa­Wolf­Parameters.t­Y

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.

See Also:

Bursa­Wolf­Parameters.t­Z

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.

See Also:

Default­Ellipsoid.get­Eccentricity­Squared()

Constructor Detail

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 ordinate values in the following order and units:

1. longitudes in radians relative to the prime meridian (usually Greenwich),
2. latitudes in radians,
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.

See Also:

create­Geodetic­Transformation(Math­Transform­Factory, Ellipsoid, boolean, Ellipsoid, boolean, double, double, double, boolean)

Method Detail

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.

See Also:

Abstract­Math­Transform.derivative(Direct­Position), Abstract­Math­Transform.transform(Direct­Position, Direct­Position), Math­Transforms.derivative­And­Transform(Math­Transform, double[], int, double[], int)

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

@Debug
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.

See Also:

Default­Operation­Method.get­Parameters()

getParameterValues

@Debug
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.

See Also:

Abstract­Math­Transform.get­Contextual­Parameters(), Abstract­Single­Operation.get­Parameter­Values()

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.

See Also:

Default­Operation­Method.get­Source­Dimensions()

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.

See Also:

Default­Operation­Method.get­Target­Dimensions()

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.

See Also:

Utilities.deep­Equals(Object, Object, Comparison­Mode)