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

Class InterpolatedTransform

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.InterpolatedTransform
All Implemented Interfaces:
Serializable, Parameterized, LenientComparable, org.opengis.referencing.operation.MathTransform
Direct Known Subclasses:
InterpolatedTransform2D
public class InterpolatedTransform extends DatumShiftTransform
Transforms between two CRS by performing translations interpolated from a grid file. The source and target coordinate reference systems are typically, but not necessarily, two-dimensional geographic CRS. The actual number of dimensions is determined by DatumShiftGrid.getTranslationDimensions().
Example: this transform is used for example with NADCON and NTv2 datum shift grids.

Input and output coordinates

First, "real world" input coordinates (x,y) are converted to grid coordinates (gridX, gridY), which are zero-based indices in the two-dimensional grid. This conversion is applied by an affine transform before to be passed to the transform methods of this InterpolatedTransform class.

Translation vectors are stored in the datum shift grid at the specified grid indices. If the grid indices are non-integer values, then the translations are interpolated using a bilinear interpolation. If the grid indices are outside the grid domain ([0 … width-1] × [0 … height-1] where width and height are the number of columns and rows in the grid), then the translations are extrapolated. The translation is finally added to the input coordinates.

The input and output coordinates can have any number of dimensions, provided that they are the same than the number of translation dimensions. However, current implementation uses only the two first dimensions for interpolations in the grid.

Since:
0.7
Version:
1.1
See Also:

  • Field Details

    • serialVersionUID

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

    • GRID_DIMENSION

      private static final int GRID_DIMENSION
      Number of dimensions used for interpolating in the datum shift grid. This is not necessarily the same than the number of dimensions of interpolated values. In current SIS implementation, this number of dimensions is fixed by the DatumShiftGrid API.
      See Also:

    • dimension

      private final int dimension
      The value of DatumShiftGrid.getTranslationDimensions(), stored for efficiency.

    • inverse

      private final InterpolatedTransform.Inverse inverse
      The inverse of this interpolated transform.
      See Also:

  • Constructor Details

    • InterpolatedTransform

      protected InterpolatedTransform(DatumShiftGrid<T,T> grid) throws NoninvertibleMatrixException
      Creates a transform for the given interpolation grid. This InterpolatedTransform class works with coordinate values in units of grid cell For example, input coordinates (4,5) is the position of the center of the cell at grid index (4,5). The output units are the same than the input units.

      For converting geodetic coordinates, InterpolatedTransform instances need to be concatenated with the following affine transforms:

      • Normalization before InterpolatedTransform for converting the geodetic coordinates into grid coordinates.
      • Denormalization after InterpolatedTransform for converting grid coordinates into geodetic coordinates.
      After InterpolatedTransform construction, the full conversion chain including the above affine transforms can be created by DatumShiftTransform.getContextualParameters().completeTransform(factory, this)}.
      Type Parameters:
      T - dimension of the coordinate tuples and the translation unit.
      Parameters:
      grid - the grid of datum shifts from source to target datum.
      Throws:
      NoninvertibleMatrixException - if the conversion from geodetic coordinates to grid indices cannot be inverted.
      See Also:

  • Method Details

    • createGeodeticTransformation

      public static <T extends javax.measure.Quantity<T>> org.opengis.referencing.operation.MathTransform createGeodeticTransformation(org.opengis.referencing.operation.MathTransformFactory factory, DatumShiftGrid<T,T> grid) throws org.opengis.util.FactoryException
      Creates a transformation between two geodetic CRS. This factory method combines the InterpolatedTransform instance with the steps needed for converting values between geodetic and grid coordinates.

      Unit of measurement

      The unit of measurement is determined by DatumShiftGrid.getCoordinateUnit():
      • If the datum shift unit is angular, then the transform will work with input and output coordinates in degrees of angle.
      • If the datum shift unit is linear, then the transform will work with input and output coordinates in metres.
      • If the datum shift unit is temporal, then the transform will work with input and output coordinates in seconds.
      • Generally for all units other than angular, the transform will work with input and output coordinates in the unit given by Unit.getSystemUnit().
      Type Parameters:
      T - dimension of the coordinate tuples and the translation unit.
      Parameters:
      factory - the factory to use for creating the transform.
      grid - the grid of datum shifts from source to target datum. The DatumShiftGrid.interpolateInCell(…) method shall compute translations from source to target as ratio of offsets divided by cell sizes.
      Returns:
      the transformation between geodetic coordinates.
      Throws:
      org.opengis.util.FactoryException - if an error occurred while creating a transform.

    • getShiftGrid

      public final DatumShiftGrid<?,?> getShiftGrid()
      Returns the grid of datum shifts specified at construction time.
      Returns:
      the grid of datum shifts from source to target datum.
      Since:
      1.1

    • getSourceDimensions

      public final int getSourceDimensions()
      Returns the number of input dimensions. This fixed to DatumShiftGrid.getTranslationDimensions().
      Specified by:
      getSourceDimensions in interface org.opengis.referencing.operation.MathTransform
      Specified by:
      getSourceDimensions in class AbstractMathTransform
      Returns:
      the dimension of input points.
      See Also:

    • getTargetDimensions

      public final int getTargetDimensions()
      Returns the number of target dimensions. This fixed to DatumShiftGrid.getTranslationDimensions().
      Specified by:
      getTargetDimensions in interface org.opengis.referencing.operation.MathTransform
      Specified by:
      getTargetDimensions in class AbstractMathTransform
      Returns:
      the dimension of output points.
      See Also:

    • transform

      public org.opengis.referencing.operation.Matrix transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) throws org.opengis.referencing.operation.TransformException
      Applies the datum shift on a coordinate tuple 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 an arbitrary number of coordinate tuples.
      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 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.

    • createInverse

      InterpolatedTransform.Inverse createInverse()
      Invoked at construction time for creating the inverse transform. To overridden by the two-dimensional transform case.

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