Difference between revisions of "Transform selection"

From PyMOLWiki
Jump to: navigation, search
(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 ===
When '''homogenous == 0''': the matrix needed is a 4x4 matrix, where the upper-left 3x3 quadrant is a typical rotation matrix. The 4th row and 4th column specify the pre- and post-translation vectors.  So, you can translate+rotate+translate with this one matrix.
+
 
 +
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 ==
=== Basic Syntax ===
 
<source lang="python">
 
cmd.transform_selection("a", [x,x,x,x, x,x,x,x, x,x,x,x, x,x,x,x],
 
homogenous=1)
 
</source>
 
  
 
=== 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 05: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:

  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[12],matrix[13],matrix[14]).
  3. 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.

See Also

transform_odb