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

Class InterpolatedMolodenskyTransform

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.InterpolatedMolodenskyTransform
All Implemented Interfaces:
Serializable, Parameterized, LenientComparable, org.opengis.referencing.operation.MathTransform
public class InterpolatedMolodenskyTransform extends DatumShiftTransform
Transforms between two geographic CRS by performing geocentric translations interpolated from a grid file, but using Molodensky approximation. This transformation is conceptually defined as a translation in geocentric coordinates as performed by InterpolatedGeocentricTransform, but uses the Molodensy (non-abridged) approximation for performance reasons. Errors are less than 3 centimetres for the "France geocentric interpolation" (ESPG:9655). By comparison, the finest accuracy reported in the grid file for France is 5 centimetres.

Algorithm

This class transforms two- or three- dimensional coordinates from a geographic CRS to another geographic CRS. The changes between source and target coordinates are small (usually less than 400 metres), but vary for every position. Those changes are provided in a datum shift grid, usually loaded from one or two files.

Many datum shift grids like NADCON and NTv2 apply the interpolated translations directly on geographic coordinates. This relatively simple case is handled by InterpolatedTransform. But in the InterpolatedMolodenskyTransform case, the interpolated translations are rather the (tX, tY, tZ) parameters of a Molodensky transformation.

Since:
0.7
Version:
1.0
Author:
Martin Desruisseaux (Geomatys)
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final double
    eccentricitySquared
    The square of eccentricity of the source ellipsoid.
    protected final double
    semiMajor
    Semi-major axis length (a) of the source ellipsoid.
    protected final double
    tX
    Shift along the geocentric X axis (toward prime meridian) in units of the semi-major axis of the source ellipsoid.
    protected final double
    tY
    Shift along the geocentric Y axis (toward 90°E) in units of the semi-major axis of the source ellipsoid.
    protected final 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
    Description
    protected
    InterpolatedMolodenskyTransform(org.opengis.referencing.datum.Ellipsoid source, boolean isSource3D, org.opengis.referencing.datum.Ellipsoid target, boolean isTarget3D, DatumShiftGrid<javax.measure.quantity.Angle,javax.measure.quantity.Length> grid)
    Creates a transform from the specified parameters.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected int
    computeHashCode()
    Computes a hash value for this transform.
    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, DatumShiftGrid<javax.measure.quantity.Angle,javax.measure.quantity.Length> grid)
    Creates a transformation between two geographic CRS.
    boolean
    equals(Object object, ComparisonMode mode)
    Compares the specified object with this math transform for equality.
    org.opengis.parameter.ParameterDescriptorGroup
    getParameterDescriptors()
    Returns a description of the internal parameters of this InterpolatedMolodenskyTransform transform.
    org.opengis.parameter.ParameterValueGroup
    getParameterValues()
    Returns a copy of internal parameter values of this transform.
    final int
    getSourceDimensions()
    Gets the dimension of input points.
    final int
    getTargetDimensions()
    Gets the dimension of output points.
    org.opengis.referencing.operation.MathTransform
    inverse()
    Returns the inverse of this interpolated Molodensky transform.
    org.opengis.referencing.operation.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 org.apache.sis.referencing.operation.transform.DatumShiftTransform

    getContextualParameters

    Methods inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform

    derivative, equals, formatTo, getDomain, hashCode, isIdentity, transform, transform, transform, transform, tryConcatenate

    Methods inherited from class org.apache.sis.io.wkt.FormattableObject

    print, toString, toString, toWKT

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface org.opengis.referencing.operation.MathTransform

    toWKT

  • 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.
      See Also:

    • 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:

    • 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:

    • 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:

  • Constructor Details

    • InterpolatedMolodenskyTransform

      protected InterpolatedMolodenskyTransform(org.opengis.referencing.datum.Ellipsoid source, boolean isSource3D, org.opengis.referencing.datum.Ellipsoid target, boolean isTarget3D, DatumShiftGrid<javax.measure.quantity.Angle,javax.measure.quantity.Length> grid)
      Creates a transform from the specified parameters. This InterpolatedMolodenskyTransform 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, InterpolatedMolodenskyTransform instances need to be concatenated with the following affine transforms:
      • Normalization before InterpolatedMolodenskyTransform:
        • Conversion of (λ,φ) from degrees to radians.
      • Denormalization after InterpolatedMolodenskyTransform:
        • Conversion of (λ,φ) from radians to degrees.
      After InterpolatedMolodenskyTransform 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.
      grid - the grid of datum shifts from source to target datum. The DatumShiftGrid.interpolateInCell(…) method shall compute (ΔX, ΔY, ΔZ) translations from source to target in the unit of source ellipsoid axes.
      See Also:

  • Method Details

    • 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, DatumShiftGrid<javax.measure.quantity.Angle,javax.measure.quantity.Length> grid) throws org.opengis.util.FactoryException
      Creates a transformation between two geographic CRS. This factory method combines the InterpolatedMolodenskyTransform 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.
      Note however that the given grid instance shall expect geographic coordinates (λ,φ) in radians.
      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.
      grid - the grid of datum shifts from source to target datum. The DatumShiftGrid.interpolateInCell(…) method shall compute (ΔX, ΔY, ΔZ) translations from source to target in the unit of source ellipsoid axes.
      Returns:
      the transformation between geographic coordinates in degrees.
      Throws:
      org.opengis.util.FactoryException - if an error occurred while creating a 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 work than the above transform(…) method, but on an arbitrary number of coordinate tuples and without computing derivative.
      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 interpolated 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 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 InterpolatedMolodenskyTransform 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:
      getParameterDescriptors in interface Parameterized
      Overrides:
      getParameterDescriptors in class AbstractMathTransform
      Returns:
      a description of the internal parameters.
      See Also:

    • getParameterValues

      @Debug public org.opengis.parameter.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:
      getParameterValues in interface Parameterized
      Overrides:
      getParameterValues in class DatumShiftTransform
      Returns:
      a copy of the internal parameter values for this transform.
      See Also:

    • getSourceDimensions

      public final int getSourceDimensions()
      Gets the dimension of input points.
      Specified by:
      getSourceDimensions in interface org.opengis.referencing.operation.MathTransform
      Specified by:
      getSourceDimensions in class AbstractMathTransform
      Returns:
      the input dimension, which is 2 or 3.
      See Also:

    • getTargetDimensions

      public final int getTargetDimensions()
      Gets the dimension of output points.
      Specified by:
      getTargetDimensions in interface org.opengis.referencing.operation.MathTransform
      Specified by:
      getTargetDimensions in class AbstractMathTransform
      Returns:
      the output dimension, which is 2 or 3.
      See Also:

    • computeHashCode

      protected int computeHashCode()
      Computes a hash value for this transform. This method is invoked by AbstractMathTransform.hashCode() when first needed.
      Overrides:
      computeHashCode in class DatumShiftTransform
      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 LenientComparable
      Overrides:
      equals in class DatumShiftTransform
      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: