Thin-Plate Spline (TPS) Warping

Thin-Plate Spline (TPS) Warping#

The opynsim.tps3d module contains classes/functions related to using the Thin-Plate Spline (TPS) technique with 3D data.

Overview#

TPS is a non-linear scaling technique that requires corresponding pairs of points (landmarks) from both a “source” and “destination” to create warped “result” points. OPynSim’s implementation of TPS was ported from OpenSim Creator, which provides a concrete use-case for TPS in its mesh warper documentation. This documentation page is a brief explanation of the primary literature sources on the topic of TPS.

The primary literature source for the TPS technique is:

F.L. Bookstein, “Principal warps: thin-plate splines and the decomposition of deformations,” in IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 11, no. 6, pp. 567-585, June 1989, doi: 10.1109/34.24792.

See also: Relevant Literature

A high-level view of the TPS technique in three dimensions is that warping a 3D point (\(v\)) involves evaluating this equation (referred to as “warping equation” in this documentation page):

\[f(v) = a_1 + a_2v_x + a_3v_y + a_4v_z + \sum_{i=1}^K w_i ||u_i - v||\]

Where \(a_1\), \(a_2\), \(a_3\), \(a_4\), \(w_i..w_K\), and \(u_i..u_K\) are \(\mathbb{R}^3\) vector coefficients computed from \(K\) source + destination landmark pairs. Evaluating \(f(v)\) is equivalent to calling opynsim.tps3d.TPSCoefficients3D.warp_point().

Note

OPynSim’s warping equation assumes a basis function (\(U\)) of \(U(u) = ||u||\), from:

Gunz, P., Mitteroecker, P., Bookstein, F.L. (2005). Semilandmarks in Three Dimensions. In: Slice, D.E. (eds) Modern Morphometrics in Physical Anthropology. Developments in Primatology: Progress and Prospects. Springer, Boston, MA. https://doi.org/10.1007/0-387-27614-9_3

Rather than \(U(u) = ||u||^2 log ||u||^2\), from the Bookstein source. This is because it tends to behave better. The choice of basis function is an implementation detail, noted here for completeness.

OPynSim provides a Python API for the TPS technique, in the form of:

As a high-level workflow example, a script that uses OPynSim script could load/gather landmark pairs (e.g. from scanner data, CSV files), provide them to opynsim.tps3d.solve_coefficients(), and then use methods like opynsim.tps3d.TPSCoefficients3D.warp_point() to warp other things from the “source” coordinate system to the warped/result coordinate system (e.g. muscle via points).

API Reference#

opynsim.tps3d.solve_coefficients(source_landmarks: ndarray[dtype=float64, shape=(*, 3), device='cpu', writable=False], destination_landmarks: ndarray[dtype=float64, shape=(*, 3), device='cpu', writable=False]) → opynsim._core.tps3d.TPSCoefficients3D#

Returns Thin-Plate Spline (TPS) warping coefficients solved by pairing N “source” points (source_landmarks) with N “destination” points (destination_landmarks).

Parameters:

  • source_landmarks – An (N, 3) array of 3D points.

  • destination_landmarks – An (N, 3) array of 3D points.

Returns:

A TPSCoefficients3D object that contains the calculated coefficients.

class opynsim.tps3d.TPSCoefficients3D#

Bases: object

Represents Thin-Plate Spline (TPS) coefficients in 3D that were calculated from corresponding pairs of points.

property a1#

The first term of the warping equation. Some systems treat this as the translation component of the warp.

property a2#

The second term of the warping equation. Some systems treat this as the first column of a 3x3 scale + rotation matrix.

property a3#

The second term of the warping equation. Some systems treat this as the second column of a 3x3 scale + rotation matrix.

property a4#

The second term of the warping equation. Some systems treat this as the third column of a 3x3 scale + rotation matrix.

warp_point(self, point: ndarray[dtype=float64, shape=(3), device='cpu', writable=False]) → numpy.ndarray[dtype=float64, shape=(3), device='cpu']#

Warps a single 3D point by putting point through the warping equation.

Parameters:

point – a 3-element ndarray.

Returns:

A 3-element ndarray that represents the warped point.

Relevant Literature#

  • Wikipedia: Thin-Plate Spline (link)

    • Top-level explanation of the algorithm

  • Principal warps: thin-plate splines and the decomposition of deformations, Bookstein, F.L. (link)

    • Primary literature source

    • Note: newer publications tend to use a different basis function

  • Manual Registration with Thin Plates, Herve Lombaert (link)

    • Easy-to-read explanation of the underlying maths behind the Thin-Plate Spline algorithm

    • Useful as a basic overview

  • Thin Plates Splines Warping, Khanh Ha (link)

    • Explanation of the low-level maths behind the Thin-Plate Spline algorithm (e.g. radial basis functions). Includes concrete C/C++/OpenCV examples

    • Useful as a basic overview for C++ implementors

  • Image Warping and Morphing, Frédo Durand (link)

    • Full presentation slides that explain the problem domain and how warping can be used to solve practical problems, etc. Explains some of the low-level maths very well (e.g. RBFs) and is a good tour of the field. Does not contain practical code examples.

    • Useful as a top-level overview of warping in general

  • Thin Plate Spline editor - an example program in C++, Jarno Elonen (link)

    • C++/OpenGL/libBLAS implementation of the TPS algorithm

    • Useful for implementors

  • CThinPlateSpline.h, Daniel Fürth (link)

    • C++/OpenCV Implementation

    • Useful for implementors

  • Interactive Thin-Plate Spline Interpolation, Sarath Chandra Kothapalli (link)

    • Basic python implementation of TPS using numpy and matlab.

    • Contains basic explanation of the algorithm in the README

    • Useful for implementors

  • 3D Thin Plate Spline Warping Function, Yang Yang (link)

    • MATLAB implementation of the algorithm

    • Useful for implementors

  • 3D Point set warping by thin-plate/rbf function, Wang Lin (link)

    • MATLAB implementation of the algorithm

    • Useful for implementors

Contents