Umeyama documentation#

umeyama(src, dst, estimate_scale=True)#

Estimates the optimal similarity transformation between two point sets.

Computes the rotation matrix \(R\), translation vector \(\mathbf{t}\), and uniform scale factor \(c\) that minimizes

\[\frac{1}{n} \sum_{i=1}^{n} \left\| \mathbf{q}_i - \left( c\,R\,\mathbf{p}_i + \mathbf{t} \right) \right\|^2\]

where \(\{\mathbf{p}_i\}\) and \(\{\mathbf{q}_i\}\) are the source and destination point sets respectively.

Parameters:

  • src (ArrayLike) – Source points of shape (n, d), where n is the number of points and d is the dimensionality.

  • dst (ArrayLike) – Destination points of shape (n, d). Must have the same shape as src.

  • estimate_scale (bool) – If True, estimate the uniform scale factor. If False, the scale is fixed to 1.0. Default is True.

Returns:

A dataclass containing:

  • rotation: Orthogonal rotation matrix of shape (d, d).

  • translation: Translation vector of shape (d,).

  • scale: Uniform scale factor (1.0 if estimate_scale is False).

  • transformation_matrix: Homogeneous transformation matrix of shape (d+1, d+1).

Return type:

UmeyamaResult

Raises:

ValueError – If src and dst have different shapes, fewer than 2 points, fewer than 2 dimensions, or if the source point set has zero variance.

Notes

The method handles the reflection ambiguity by inspecting the determinant of the matrix \(U V^T\) from the SVD of the covariance matrix and correcting the sign of the last singular value accordingly.

References

  • Umeyama, Shinji. “Least-Squares Estimation of Transformation Parameters Between Two Point Patterns.” IEEE Transactions on Pattern Analysis and Machine Intelligence 13, no. 4 (April 1991): 376-80. https://doi.org/10.1109/34.88573.

class UmeyamaResult(rotation, translation, scale)#

Bases: object

Result of the Umeyama transformation estimation.

apply(points)#

Applies the Umeyama transformation to a set of points.

Transforms each point \(\mathbf{p}_i\) as

\[\mathbf{p}_i' = c\,R\,\mathbf{p}_i + \mathbf{t}\]
Parameters:

points (ArrayLike) – Points of shape (n, d) to transform.

Return type:

NDArray[float64]

Returns:

Transformed points as a numpy.ndarray of shape (n, d).

Raises:

ValueError – If the point dimensionality does not match the transformation.

rmse(src, dst)#

Computes the root mean square error after applying the transformation.

\[\mathrm{RMSE} = \sqrt{\frac{1}{n} \sum_{i=1}^{n} \left\| \mathbf{q}_i - \left( c\,R\,\mathbf{p}_i + \mathbf{t} \right) \right\|^2}\]
Parameters:

  • src (ArrayLike) – Source points of shape (n, d).

  • dst (ArrayLike) – Destination points of shape (n, d).

Return type:

float

Returns:

Root mean square error as a float.

Raises:

ValueError – If src and dst have different shapes or incompatible dimensionality with the transformation.

rotation: NDArray[float64]#

Orthogonal rotation matrix of shape (d, d).

scale: float#

Uniform scaling factor. Equal to 1.0 when estimated without scaling.

property transformation_matrix: NDArray[float64]#

Homogeneous transformation matrix of shape (d+1, d+1).

Dynamically computed from rotation, translation, and scale.

translation: NDArray[float64]#

Translation vector of shape (d,).