# Difference between revisions of "Transform selection"

(Added description from 1.7.0 docstring) |
|||

Line 1: | Line 1: | ||

== Overview == | == Overview == | ||

'''transform_selection''' applies a transformation matrix to a selection. The matrix should actually be passed in as a single list -- not a list of lists. | '''transform_selection''' applies a transformation matrix to a selection. The matrix should actually be passed in as a single list -- not a list of lists. | ||

+ | |||

+ | |||

+ | === PYMOL API === | ||

+ | |||

+ | cmd.transform_selection(string selection, list matrix, int state, int log, int homogenous, int transpose): | ||

=== Details === | === Details === | ||

− | + | ||

+ | Note that when homogenous is zero, the input matrix is NOT a | ||

+ | standard homogenous 4x4 transformation matrix. Instead it is | ||

+ | something PyMOL-specific which consists of the following: | ||

+ | |||

+ | # a 3x3 matrix containing the rotation in the upper-left quadrant | ||

+ | # a 1x3 translation to be applied '''before''' rotation in the bottom row (matrix[12],matrix[13],matrix[14]). | ||

+ | # a 3x1 translation to be applied '''after''' rotation in the right-hand column (matrix[3],matrix[7],matrix[11]) | ||

+ | |||

+ | So, you can translate+rotate+translate with this one matrix. | ||

+ | |||

+ | In other words, if the matrix is: | ||

+ | |||

+ | [ m0 m1 m2 m3 \ | ||

+ | m4 m5 m6 m7 \ | ||

+ | m8 m9 m10 m11 \ | ||

+ | m12 m13 m14 m15 ] | ||

+ | |||

+ | Atoms will be transformed as follows | ||

+ | |||

+ | Y = M X | ||

+ | |||

+ | y0 = m0*(x0+m12) + m1*(x1+m13) + m2*(x2+m14) + m3 \ | ||

+ | y1 = m4*(x0+m12) + m5*(x1+m13) + m6*(x2+m14) + m7 \ | ||

+ | y2 = m8*(x0+m12) + m9*(x1+m13) + m10*(x2+m14) + m11 | ||

== Example == | == Example == | ||

− | |||

− | |||

− | |||

− | |||

− | |||

=== Real-World Example === | === Real-World Example === | ||

Line 25: | Line 49: | ||

-bestCOM2[0], -bestCOM2[1], -bestCOM2[2], 1.); | -bestCOM2[0], -bestCOM2[1], -bestCOM2[2], 1.); | ||

</source> | </source> | ||

− | where bestU is the transpose of the best rotation matrix, bestCOM1 is the center of mass (COM) for molecule 1, and bestCOM2 is for two. '''pyU''' becomes '''rotMat'''. The call in Python is then, | + | where bestU is the transpose of the best rotation matrix, bestCOM1 is the center of mass (COM) for molecule 1, and bestCOM2 is for molecule two. '''pyU''' becomes '''rotMat'''. The call in Python is then, |

<source lang="python"> | <source lang="python"> | ||

# | # |

## Latest revision as of 06:56, 1 June 2015

## Overview

**transform_selection** applies a transformation matrix to a selection. The matrix should actually be passed in as a single list -- not a list of lists.

### PYMOL API

cmd.transform_selection(string selection, list matrix, int state, int log, int homogenous, int transpose):

### Details

Note that when homogenous is zero, the input matrix is NOT a standard homogenous 4x4 transformation matrix. Instead it is something PyMOL-specific which consists of the following:

- a 3x3 matrix containing the rotation in the upper-left quadrant
- a 1x3 translation to be applied
**before**rotation in the bottom row (matrix[12],matrix[13],matrix[14]). - a 3x1 translation to be applied
**after**rotation in the right-hand column (matrix[3],matrix[7],matrix[11])

So, you can translate+rotate+translate with this one matrix.

In other words, if the matrix is:

[ m0 m1 m2 m3 \ m4 m5 m6 m7 \ m8 m9 m10 m11 \ m12 m13 m14 m15 ]

Atoms will be transformed as follows

Y = M X y0 = m0*(x0+m12) + m1*(x1+m13) + m2*(x2+m14) + m3 \ y1 = m4*(x0+m12) + m5*(x1+m13) + m6*(x2+m14) + m7 \ y2 = m8*(x0+m12) + m9*(x1+m13) + m10*(x2+m14) + m11

## Example

### Real-World Example

I wrote a structure alignment program that needs to update the coordinates of the 2nd protein by translating it, rotating it and then translating it on top of the other molecule. It's done as follows:

```
//
// C code
//
// ...after the magic is done, pack all the values into the TTT matrix.
PyObject* pyU = Py_BuildValue( "[f,f,f,f, f,f,f,f, f,f,f,f, f,f,f,f]",
bestU[0][0], bestU[1][0], bestU[2][0], bestCOM1[0],
bestU[0][1], bestU[1][1], bestU[2][1], bestCOM1[1],
bestU[0][2], bestU[1][2], bestU[2][2], bestCOM1[2],
-bestCOM2[0], -bestCOM2[1], -bestCOM2[2], 1.);
```

where bestU is the transpose of the best rotation matrix, bestCOM1 is the center of mass (COM) for molecule 1, and bestCOM2 is for molecule two. **pyU** becomes **rotMat**. The call in Python is then,

```
#
# Python code.
#
cmd.transform_selection( mol2, rotMat, homogenous=0 );
```

Were I **not** to use bestCOM1 or bestCOM2, each of those entries would be 0. The last element should always be 1.