Class ThinPlateSplineTransform

Object
ThinPlateSplineTransform
All Implemented Interfaces:
MathTransform

public class ThinPlateSplineTransform extends Object implements MathTransform
A 2D transformation using Thin Plate Splines (TPS) for smoothly interpolating between a set of control points. This transform is useful for georeferencing scanned maps or warping images based on Ground Control Points (GCPs).

This implementation uses separate TPS interpolators for the X and Y dimensions.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a Thin Plate Spline transform from a list of MappedPosition instances.
    ThinPlateSplineTransform(List<Coordinate> sourcePoints, List<Coordinate> targetPoints)
    Constructs a Thin Plate Spline transform from lists of source and target coordinates.
  • Method Summary

    Modifier and Type
    Method
    Description
    Estimates the Jacobian matrix (first-order partial derivatives) of the transformation at a given point using central differences.
    int
    Gets the dimension of input points.
    int
    Gets the dimension of output points.
    Returns the inverse of this transformation by swapping the source and target points.
    boolean
    Tests whether this transform does not move any points.
    Returns a human-readable description of this transform.
    Returns the Well-Known Text (WKT) representation of the transform.
    void
    transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)
    Transforms a list of coordinate point ordinal values.
    void
    transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)
    Transforms a list of coordinate point ordinal values.
    void
    transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)
    Transforms a list of coordinate point ordinal values.
    void
    transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)
    Transforms a list of coordinate point ordinal values.
    transform(Position ptSrc, Position ptDst)
    Transforms a 2D position using the thin plate spline transformation.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Constructor Details

    • ThinPlateSplineTransform

      public ThinPlateSplineTransform(List<Coordinate> sourcePoints, List<Coordinate> targetPoints)
      Constructs a Thin Plate Spline transform from lists of source and target coordinates.
      Parameters:
      sourcePoints - list of source coordinates (e.g., image coordinates)
      targetPoints - list of target coordinates (e.g., map coordinates)
      Throws:
      IllegalArgumentException - if the two lists are not of equal length
    • ThinPlateSplineTransform

      public ThinPlateSplineTransform(List<MappedPosition> positions)
      Constructs a Thin Plate Spline transform from a list of MappedPosition instances.
      Parameters:
      positions - list of mappings from source to target positions
      Throws:
      IllegalArgumentException - if the list is null, empty, or mismatched
  • Method Details

    • getSourceDimensions

      public int getSourceDimensions()
      Gets the dimension of input points.
      Specified by:
      getSourceDimensions in interface MathTransform
      Returns:
      The dimension of input points.
    • getTargetDimensions

      public int getTargetDimensions()
      Gets the dimension of output points.
      Specified by:
      getTargetDimensions in interface MathTransform
      Returns:
      The dimension of output points.
    • transform

      public Position transform(Position ptSrc, Position ptDst) throws MismatchedDimensionException, TransformException
      Transforms a 2D position using the thin plate spline transformation.
      Specified by:
      transform in interface MathTransform
      Parameters:
      ptSrc - the source position
      ptDst - the destination position to store the result (or null to create a new one)
      Returns:
      the transformed position
      Throws:
      MismatchedDimensionException - if dimensions are invalid
      TransformException - if the transformation fails
    • transform

      public void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws TransformException
      Transforms a list of coordinate point ordinal values. This method is provided for efficiently transforming many points. The supplied array of ordinal values will contain packed ordinal values. For example, if the source dimension is 3, then the ordinals will be packed in this order:

      (x0,y0,z0, x1,y1,z1 ...).

      Specified by:
      transform in interface MathTransform
      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:
      TransformException - if a point can't be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with NaN values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.
    • transform

      public void transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) throws TransformException
      Transforms a list of coordinate point ordinal values. This method is provided for efficiently transforming many points. The supplied array of ordinal values will contain packed ordinal values. For example, if the source dimension is 3, then the ordinals will be packed in this order:

      (x0,y0,z0, x1,y1,z1 ...).

      Specified by:
      transform in interface MathTransform
      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:
      TransformException - if a point can't be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with NaN values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.
    • transform

      public void transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws TransformException
      Transforms a list of coordinate point ordinal values. This method is provided for efficiently transforming many points. The supplied array of ordinal values will contain packed ordinal values. For example, if the source dimension is 3, then the ordinals will be packed in this order:

      (x0,y0,z0, x1,y1,z1 ...).

      Specified by:
      transform in interface MathTransform
      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.
      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:
      TransformException - if a point can't be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with NaN values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.
    • transform

      public void transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) throws TransformException
      Transforms a list of coordinate point ordinal values. This method is provided for efficiently transforming many points. The supplied array of ordinal values will contain packed ordinal values. For example, if the source dimension is 3, then the ordinals will be packed in this order:

      (x0,y0,z0, x1,y1,z1 ...).

      Specified by:
      transform in interface MathTransform
      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.
      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:
      TransformException - if a point can't be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with NaN values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.
    • derivative

      Estimates the Jacobian matrix (first-order partial derivatives) of the transformation at a given point using central differences.
      Specified by:
      derivative in interface MathTransform
      Parameters:
      point - the position to evaluate the derivative at
      Returns:
      a 2×2 matrix representing the derivative
      Throws:
      MismatchedDimensionException - if dimensions are invalid
      TransformException - if the transformation fails
    • inverse

      Returns the inverse of this transformation by swapping the source and target points.
      Specified by:
      inverse in interface MathTransform
      Returns:
      the inverse transform
      Throws:
      UnsupportedOperationException - if inversion is not supported
    • isIdentity

      public boolean isIdentity()
      Tests whether this transform does not move any points.
      Specified by:
      isIdentity in interface MathTransform
      Returns:
      true if this MathTransform is an identity transform; false otherwise.
    • toWKT

      public String toWKT() throws UnsupportedOperationException
      Returns the Well-Known Text (WKT) representation of the transform.
      Specified by:
      toWKT in interface MathTransform
      Returns:
      the WKT string
      Throws:
      UnsupportedOperationException - If this object can't be formatted as WKT.
    • toString

      public String toString()
      Returns a human-readable description of this transform.
      Overrides:
      toString in class Object
      Returns:
      string description