Package org.apache.sis.referencing.operation.transform

Class MolodenskyTransform

java.lang.Object
org.apache.sis.io.wkt.FormattableObject
org.apache.sis.referencing.operation.transform.AbstractMathTransform
org.apache.sis.referencing.operation.transform.DatumShiftTransform
org.apache.sis.referencing.operation.transform.MolodenskyFormula
org.apache.sis.referencing.operation.transform.MolodenskyTransform
All Implemented Interfaces:
Serializable, Parameterized, LenientComparable, org.opengis.referencing.operation.MathTransform
Direct Known Subclasses:
MolodenskyTransform2D
public class MolodenskyTransform extends MolodenskyFormula
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.

MolodenskyTransforms 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 (isSource3D = false), then the source dimensions is 2 and the height is assumed to be zero.
  • If the height is omitted from the output coordinates (isTarget3D = 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 MathTransform has been created:
  • MolodenskyTransform instances created directly by the constructor work with angular values in radians.
  • Transforms created by the createGeodeticTransformation(…) 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
Version:
1.3
See Also:

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for inter-operability with different versions.
      See Also:

    • DESCRIPTOR

      @Debug private static org.opengis.parameter.ParameterDescriptorGroup DESCRIPTOR
      Internal parameter descriptor, used only for debugging purpose. Created only when first needed.
      See Also:

    • inverse

      private final MolodenskyTransform inverse
      The inverse of this Molodensky transform.
      See Also:

  • Constructor Details

    • MolodenskyTransform

      public MolodenskyTransform(org.opengis.referencing.datum.Ellipsoid source, boolean isSource3D, org.opengis.referencing.datum.Ellipsoid target, boolean isTarget3D, double tX, double tY, double tZ, boolean isAbridged)
      Creates a Molodensky transform from the specified parameters. This MolodenskyTransform class expects coordinate 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, MolodenskyTransform instances need to be concatenated with the following affine transforms:
      • Normalization before MolodenskyTransform:
        • Conversion of (λ,φ) from degrees to radians.
      • Denormalization after MolodenskyTransform:
        • Conversion of (λ,φ) from radians to degrees.
      After MolodenskyTransform construction, the full conversion chain including the above affine transforms can be created by DatumShiftTransform.getContextualParameters().completeTransform(factory, this)}.
      Parameters:
      source - the source ellipsoid.
      isSource3D - true if the source coordinates have a height.
      target - the target ellipsoid.
      isTarget3D - true if the target coordinates have a height.
      tX - the geocentric X translation in same units than the source ellipsoid axes.
      tY - the geocentric Y translation in same units than the source ellipsoid axes.
      tZ - the geocentric Z translation in same units than the source ellipsoid axes.
      isAbridged - true for the abridged formula, or false for the complete one.
      See Also:

    • MolodenskyTransform

      MolodenskyTransform(MolodenskyTransform inverse, org.opengis.referencing.datum.Ellipsoid source, org.opengis.referencing.datum.Ellipsoid target)
      Constructs the inverse of a Molodensky transform.
      Parameters:
      inverse - the transform for which to create the inverse.
      source - the source ellipsoid of the given inverse transform.
      target - the target ellipsoid of the given inverse transform.

  • Method Details

    • completeParameters

      final void completeParameters(Parameters pg, double semiMinor, javax.measure.Unit<?> unit, double Δf)
      Invoked by constructor and by MolodenskyFormula.getParameterValues() for setting all parameters other than axis lengths.
      Overrides:
      completeParameters in class MolodenskyFormula
      Parameters:
      pg - where to set the parameters.
      semiMinor - ignored.
      unit - the unit of measurement to declare.
      \u0394f - the flattening difference to set, or NaN if this method should fetch that value itself.

    • createGeodeticTransformation

      public static org.opengis.referencing.operation.MathTransform createGeodeticTransformation(org.opengis.referencing.operation.MathTransformFactory factory, org.opengis.referencing.datum.Ellipsoid source, boolean isSource3D, org.opengis.referencing.datum.Ellipsoid target, boolean isTarget3D, double tX, double tY, double tZ, boolean isAbridged) throws org.opengis.util.FactoryException
      Creates a transformation between two from geographic CRS. This factory method combines the MolodenskyTransform 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.
      isSource3D - true if the source coordinates have a height.
      target - the target ellipsoid.
      isTarget3D - true if the target coordinates have a height.
      tX - the geocentric X translation in same units than the source ellipsoid axes.
      tY - the geocentric Y translation in same units than the source ellipsoid axes.
      tZ - the geocentric Z translation in same units than the source ellipsoid axes.
      isAbridged - true for the abridged formula, or false for the complete one.
      Returns:
      the transformation between geographic coordinates in degrees.
      Throws:
      org.opengis.util.FactoryException - 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:
      isIdentity in interface org.opengis.referencing.operation.MathTransform
      Overrides:
      isIdentity in class AbstractMathTransform
      Returns:
      true if this transform is the identity transform.

    • transform

      public org.opengis.referencing.operation.Matrix transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) throws org.opengis.referencing.operation.TransformException
      Transforms the (λ,φ) or (λ,φ,h) coordinates between two geographic CRS, and optionally returns the derivative at that location.
      Specified by:
      transform in class AbstractMathTransform
      Parameters:
      srcPts - the array containing the source coordinates (cannot be null).
      srcOff - the offset to the point to be transformed in the source array.
      dstPts - the array into which the transformed coordinates is returned. May be the same than srcPts. May be null if only the derivative matrix is desired.
      dstOff - 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:
      org.opengis.referencing.operation.TransformException - if the point cannot be transformed or if a problem occurred while calculating the derivative.
      See Also:

    • transform

      public void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws org.opengis.referencing.operation.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 org.opengis.referencing.operation.MathTransform
      Overrides:
      transform in class AbstractMathTransform
      Parameters:
      srcPts - the array containing the source point coordinates.
      srcOff - the offset to the first point to be transformed in the source array.
      dstPts - the array into which the transformed point coordinates are returned. May be the same than srcPts.
      dstOff - the offset to the location of the first transformed point that is stored in the destination array.
      numPts - the number of point objects to be transformed.
      Throws:
      org.opengis.referencing.operation.TransformException - if a point cannot be transformed.

    • inverse

      public org.opengis.referencing.operation.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 org.opengis.referencing.operation.MathTransform
      Overrides:
      inverse in class AbstractMathTransform
      Returns:
      a Molodensky transform from the target ellipsoid to the source ellipsoid of this transform.

    • getParameterDescriptors

      @Debug public org.opengis.parameter.ParameterDescriptorGroup getParameterDescriptors()
      Returns a description of the internal parameters of this MolodenskyTransform 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:
      getParameterDescriptors in interface Parameterized
      Overrides:
      getParameterDescriptors in class AbstractMathTransform
      Returns:
      a description of the internal parameters.
      See Also: