NumPy¶

Forward-pass only. No autograd wrappers or RMSD loss functions.

numpy ¶

kabsch ¶

kabsch(
    P: ndarray, Q: ndarray, weights: ndarray | None = None
) -> tuple[np.ndarray, np.ndarray, np.ndarray]

Computes the optimal rotation and translation to align P to Q.

Parameters:

Name	Type	Description	Default
`P`	`ndarray`	Source points, shape [..., N, D].	required
`Q`	`ndarray`	Target points, shape [..., N, D].	required
`weights`	`ndarray \| None`	Per-point weights, shape [..., N]. Non-negative, must sum to > 0. When None, all points are weighted equally.	`None`

Returns:

Type	Description
`(R, t, rmsd)`	Rotation [..., D, D], translation [..., D], RMSD [...].

Note

R is only stable under global translation when the cross-covariance matrix H = P_c.T @ Q_c is well-conditioned. When the smallest singular value of H is near zero, U and V from the SVD are not unique, and a small perturbation can select a different rotation. Check the singular values of H if rotation stability matters for your use case.

kabsch_umeyama ¶

kabsch_umeyama(
    P: ndarray, Q: ndarray, weights: ndarray | None = None
) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

Computes the optimal rotation, translation, and scale to align P to Q (Q ~ c * R @ P + t).

Parameters:

Name	Type	Description	Default
`P`	`ndarray`	Source points, shape [..., N, D].	required
`Q`	`ndarray`	Target points, shape [..., N, D].	required
`weights`	`ndarray \| None`	Per-point weights, shape [..., N]. Non-negative, must sum to > 0. When None, all points are weighted equally.	`None`

Returns:

Type	Description
`(R, t, c, rmsd)`	Rotation [..., D, D], translation [..., D], scale [...],
`ndarray`	RMSD [...].

Note

Unlike kabsch, the cross-covariance H is divided by N here. This per-point normalization is required by the Umeyama scale estimator (c = trace(S * D) / var_P) and does not affect the rotation or translation.

R is only stable under global translation and uniform scaling when the cross-covariance matrix H = P_c.T @ Q_c is well-conditioned. When the smallest singular value of H is near zero, U and V from the SVD are not unique, and a small perturbation can select a different rotation. Check the singular values of H if rotation stability matters for your use case.

horn ¶

horn(
    P: ndarray, Q: ndarray, weights: ndarray | None = None
) -> tuple[np.ndarray, np.ndarray, np.ndarray]

Computes optimal rotation and translation to align P to Q using Horn's quaternion method.

Strictly 3D only. Forward-pass only (NumPy has no autograd).

Parameters:

Name	Type	Description	Default
`P`	`ndarray`	Source points, shape [..., N, 3].	required
`Q`	`ndarray`	Target points, shape [..., N, 3].	required
`weights`	`ndarray \| None`	Per-point weights, shape [..., N]. Non-negative, must sum to > 0. When None, all points are weighted equally.	`None`

Returns:

Type	Description
`(R, t, rmsd)`	Rotation [..., 3, 3], translation [..., 3], and RMSD [...].

horn_with_scale ¶

horn_with_scale(
    P: ndarray, Q: ndarray, weights: ndarray | None = None
) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

Computes optimal rotation, translation, and scale to align P to Q (Q ~ c * R @ P + t).

Strictly 3D only. Forward-pass only (NumPy has no autograd).

Parameters:

Name	Type	Description	Default
`P`	`ndarray`	Source points, shape [..., N, 3].	required
`Q`	`ndarray`	Target points, shape [..., N, 3].	required
`weights`	`ndarray \| None`	Per-point weights, shape [..., N]. Non-negative, must sum to > 0. When None, all points are weighted equally.	`None`

Returns:

Type	Description
`(R, t, c, rmsd)`	Rotation [..., 3, 3], translation [..., 3],
`ndarray`	scale [...], RMSD [...].