# Difference between revisions of "Transform selection"

## 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:

1. a 3x3 matrix containing the rotation in the upper-left quadrant
2. a 1x3 translation to be applied before rotation in the bottom row (matrix,matrix,matrix).
3. a 3x1 translation to be applied after rotation in the right-hand column (matrix,matrix,matrix)

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, bestU, bestU, bestCOM1,
bestU, bestU, bestU, bestCOM1,
bestU, bestU, bestU, bestCOM1,
-bestCOM2, -bestCOM2, -bestCOM2, 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.