torchpose3d

Note: This is a fork of the NumPy implementation here.

Usage

def Superpose3D(input,    # <-- Nx3 tensor of coords for the "mobile" point cloud
                target,    # <-- Nx3 tensor of coords for the "frozen" point cloud
                # ---- optional arguments: ----
                weights = None,        # optional weights for the calculation of RMSD
                allow_rescale=False)   # attempt to rescale mobile point cloud?

Superpose3D() takes two torch.Tensors of xyz coordinates (of the same length, N) representing two ordered sets of points ("clouds", X and x). Treating them as rigid objects, "Superpose3D()" superimposes them using rotations, translations, and (optionally) scale transformations in order to minimize the root-mean-squared-distance (RMSD) between corresponding points from either cloud, where RMSD is defined as:

...where:

   R_ij = a rotation matrix    (a 3x3 numpy array representing the rotation. |R|=1)
   T_j  = a translation vector (a 1-D numpy array containing x,y,z displacements)
    c   = a scalar             (a number. optional. 1 by default)

This function returns a 4-tuple containing the optimal values of:

   (RMSD, R, T, c)

Note: The point clouds must contain the same number of points (N).

Note: This function does not attempt to determine which pairs of points from either cloud correspond. Instead, it infers them from the order of the arrays. (It assumes that the i'th point from X corresponds to the i'th point from x.) More generally, the open3d python module supports the IPC algorithm, and works with unordered point clouds of arbitrary size. (Usage example here. Also see: link1, link2, link3, link4(protein-alignment).)

Weighted RMSD

A weighted version of the RMSD minimization algorithm is also available if the caller supplies an extra argument specifying the weight of every point in the cloud (w_n). In that case, RMSD is defined as:

Algorithm

This function implements a more general variant of the method from this paper: R. Diamond, (1988) "A Note on the Rotational Superposition Problem", Acta Cryst. A44, pp. 211-216.

Scale transformations

This version has been augmented slightly to support scale transformations. (I.E. multiplication by scalars. This can be useful for the registration of two different annotated volumetric 3-D images of the same object taken at different magnifications.)

Note that if you enable scale transformations (i.e. if allow_rescale=True), you should be wary if the function returns a negative c value. Negative c values correspond to inversions (reflections). For this reason, if you are using this function to compare the conformations of molecules, you should probably set allow_rescale=False. This will prevent matching a molecule with its stereoenantiomer.

Installation using pip

pip install .

Later, you can uninstall torchpose3d using:

pip uninstall torchpose3d

Requirements

torchpose3d depends on PyTorch

License

torchpose3d is available under the terms of the MIT license.