Register 3-D point clouds using rotation, translation, and scale transformations.
Usage
def Superpose3D(X, # <-- Nx3 array of coords for the "frozen" point cloud
x, # <-- Nx3 array of coords for the "mobile" point cloud
# ---- optional arguments: ----
w = None, # optional weights for the calculation of RMSD
allow_rescale=False, # attempt to rescale mobile point cloud?
report_quaternion=False) # report rotation angle and axis?
Superpose3D() takes two ordered lists (or numpy arrays) of xyz coordinates (of the same length, N) representing points in a point cloud (X and x). Treating them as rigid objects, "Superpose3D()" attempts to superimpose them using rotations, translations, and (optionally) scale transformations in order to minimize the root-mean-squared-distance (RMSD) between corresponding points from either point cloud, where RMSD is defined as:
RMSD = sqrt( (Σ_n w[n] * Σ_i |X[n][i] - (Σ_j c*R[i][j]*x[n][j] + T[i])|^2) / (Σ_n w[n]) )
If w=None, equal weights are used. In that case:
RMSD = sqrt( (Σ_n Σ_i |X[n][i] - (Σ_j c*R[i][j]*x[n][j] + T[i])|^2) / N )
...where:
R = a rotation matrix (a 3x3 numpy array representing the rotation. |R|=1)
T = a translation vector (a 1-D numpy array containing x,y,z displacements)
c = a scalar (a number, 1 by default)
This function returns a 4-tuple containing the optimal values of:
(RMSD, R, T, c)
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.)
If the rotation angle and axis are needed, then set the report_quaternion argument to True. In that case, the function will return this 4-tuple instead:
(RMSD, q, T, c)
...where q is the quaternion corresponding to rotation R, from which the rotation angle and rotation axis can be easily determined.
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.
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 stereoisomer.
Note: A C++ version of this repository is available at https://github.com/jewettaij/superpose3d_cpp
1 maintainer
Release files for superpose3d 1.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| superpose3d-1.5.0.tar.gz | 9.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| superpose3d-1.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 16.6 kB
Release files / superpose3d-1.5.0.tar.gz
| Download URL | superpose3d-1.5.0.tar.gz |
|---|---|
| Size | 9.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f44d9b679e4ef8aaf4f4cb86b28fc2350ded22723792eae2912b96d52b841ed9
|
|
BLAKE2b-256 checksum How to use checksums |
9851616ad4f70702bf9be92ebb9a83709147a66e580b2eeab4acb38c15d6ad71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.0.1 CPython/3.10.16
|
Release files / superpose3d-1.5.0-py3-none-any.whl
| Download URL | superpose3d-1.5.0-py3-none-any.whl |
|---|---|
| Size | 7.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a26a6a7a3f17288020f29133b01602332abed4dcc2c68076c5dd8c4f108a56f9
|
|
BLAKE2b-256 checksum How to use checksums |
d8145807fd41fc3b66c752f44a6b00c5158205cb7349a23e952c0391ca48575f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.0.1 CPython/3.10.16
|
