Differences

This shows you the differences between two versions of the page.

--- eman2:eman2transforminpython [2025/07/04 16:00] – steveludtke
+++ eman2:eman2transforminpython [2025/07/06 02:44] (current) – steveludtke
@@ Line 1: / Line 1: @@
-====== Transforms in Python ======
+This page has [[transforminpython|moved]]
-===== The center of the image =====
-----
-The center of the image for purposes of rotations is different for odd and even sized images. For even images, the center is at $(nx/2,ny/2)$ where the first pixel is at $(0,0)$. For odd sized images, the center is at $((nx-1)/2,(ny-1)/2)$. The same concept extends to 3-D.
-{{attachment:center1.png}} {{attachment:center2.png}}
-===== What is a Transform? =====
-----
-We use the [[http://blake.bcm.edu/doxygen/classEMAN_1_1Transform.html|Transform]] class for storing/managing Euler angles,translations, scales and x mirroring. At any time a Transform object $\mathrm{Tr}$ defines a group of 4 transformations of a rigid body that are applied in a specific order, namely
-$$\mathrm{Tr} = M T S R$$
-Where $M$ is a mirroring operation about the x-axis, $T$ is a translation, $S$ is a uniform, positive, non zero scaling operation and $R$ is a rotation. The Transform object stores these transformations internally in a 3x4 matrix.
-===== Supported Rotation Conventions =====
-----
-||Convention ||Angle Names ||Matrices ||
-||EMAN ||az, alt, phi (Z,X,Z') ||$\begin{bmatrix}\cos phi&\sin phi& 0\\-\sin phi&\cos phi&0\\0&0&1\end{bmatrix}$ $\begin{bmatrix}1&0&0\\0& \cos alt& \sin alt\\0& -\sin alt& \cos alt\end{bmatrix}$ $\begin{bmatrix}\cos az&\sin az& 0\\-\sin az&\cos az&0\\0&0&1\end{bmatrix}$ ||
-||Imagic ||gamma, beta, alpha ||$\begin{bmatrix}\cos gamma&\sin gamma& 0\\-\sin gamma&\cos gamma&0\\0&0&1\end{bmatrix}$ $\begin{bmatrix}1&0&0\\0& \cos beta& \sin beta\\0& -\sin beta& \cos beta\end{bmatrix}$ $\begin{bmatrix}\cos alpha&\sin alpha& 0\\-\sin alpha&\cos alpha&0\\0&0&1\end{bmatrix}$ ||
-||Spider ||psi, theta, phi ||$\begin{bmatrix}\cos psi&\sin psi& 0\\-\sin psi&\cos psi&0\\0&0&1\end{bmatrix}$ $\begin{bmatrix}\cos theta&0&\sin theta\\0& 1& 0\\-\sin theta& 0& \cos theta\end{bmatrix}$ $\begin{bmatrix}\cos phi&\sin phi& 0\\-\sin phi&\cos phi&0\\0&0&1\end{bmatrix}$ ||
-||MRC ||phi, theta, omega ||$\begin{bmatrix}\cos phi&\sin phi& 0\\-\sin phi&\cos phi&0\\0&0&1\end{bmatrix}$ $\begin{bmatrix}\cos theta&0&\sin theta\\0& 1& 0\\-\sin theta& 0& \cos theta\end{bmatrix}$ $\begin{bmatrix}\cos omega&\sin omega& 0\\-\sin omega&\cos omega&0\\0&0&1\end{bmatrix}$ ||
-||XYZ ||z, y, x ||$\begin{bmatrix}\cos z&\sin z& 0\\-\sin z& \cos z&0\\0&0&1\end{bmatrix}$ $\begin{bmatrix}\cos y&0&\sin y\\0& 1& 0\\-\sin y& 0& \cos y\end{bmatrix}$ $\begin{bmatrix}1&0&0\\0& \cos x& \sin x\\0& -\sin x& \cos x\end{bmatrix}$ ||
-||spin ||Omega, n1, n2, n3 ||Quaternion rotation by  Omega  degrees about the vector $[n1,n2,n3]$ ||
-||sgirot ||q, n1, n2, n3 ||Quaternion rotation by q degrees about the vector $[n1,n2,n3]$ ||
-||quaternion ||e0, e1, e2, e3 ||Literal quaternion rotation using  $q = e0 + e1\mathbf{i} + e2\mathbf{j} + e2\mathbf{k}$  ||
-||2d||alpha||Rotation in 2-D only, for 3-D objects this is a rotation about Z||
-===== The Transform object in Python =====
-----
-==== Constructing a Transform ====
-There a four ways to construct a Transform object in Python
-<code python>
-t = Transform() # default constructor, t is the identity
-t = Transform({"type":"eman","az":10,"alt":150,"scale":2.0,"mirror":True,"tx":3.4}) # construction using a dictionary
-p = Transform({"type":"eman","az":10,"mirror":True,"tx":3.4}) # construction using a dictionary
-q = Transform([1,0,0,0,0,1,0,0,0,0,1,0]) # specify the 12 entries of the matrix explicitly, row wise (3 rows of 4)
-s = Transform(t) # copy construction - s is precisely the same as t
-</code>
-**NOTE:**
-All the CONVENTIONS listed on the table above can be supplied as arguments or "values" for the "type" key in the Transform's dictionary.
-For example:
-<code python>
-t = Tranform({"type":"spin"})
-t = Tranform({"type":"quaternion"})
-t = Tranform({"type":"imagic"})
-Etc.
-</code>
-For more information on default parameters and what happens when some parameters are not set see [[#dict_const|a more in depth look at the dictionary constructor]]
-==== Setting/getting rotations ====
-<code python>
-t = Transform()
-t.set_rotation({"type":"spider","phi":32,"theta":12,"psi":-100})
-spider_rot = t.get_rotation("spider")
-eman_rot = t.get_rotation("eman")
-s = Transform(eman_rot) # works fine
-</code>
-**NOTE:**
-The **get_rotation() method can take a string as an argument, but it does NOT require one**; it is defaulted to 'eman'. That is, it will return the rotation of the transform object in 'eman' convention.
-You can supply ANY rotation CONVENTION as a string to get the rotation in the corresponding convention, irrespective of the "type" you set for the transform. For example, from an 'eman' type Transform,
-<code python>
-t = Transform({'type':'eman'})
-</code>
-You can still get the rotation in other conventions:
-<code python>
-t.get_rotation('spin') gives {'Omega': 0.0, 'n1': 0.0, 'n2': 0.0, 'n3': 0.0, 'type': 'spin'}
-t.get_rotation('quaternion') gives  {'e0': 1.0, 'e1': 0.0, 'e2': 0.0, 'e3': 0.0, 'type': 'quaternion'}
-</code>
-==== Setting/getting scale ====
-<code python>
-t = Transform()
-t.set_scale(2.0)
-scale = t.get_scale()
-s = Transform({"scale":scale}) # set scale as part of construction
-</code>
-==== Setting/getting mirror ====
-<code python>
-t = Transform()
-#  Can be set using integers
-t.set_mirror(1) # means True
-t.set_mirror(0) # means False
-t.set_mirror(False)
-t.set_mirror(True)
-mirror = t.get_mirror()
-s = Transform({"mirror":mirror}) # set mirror as part of construction
-</code>
-==== Setting/getting translation ====
-<code python>
-t = Transform()
-t.set_trans(1,2,3) # method 1
-t.set_trans(Vec3f(1,2,3)) # method 2
-t.set_trans([1,2,3]) # method 3 - the tuple is converted to a Vec3f automatically
-v = t.get_trans()
-s = Transform({"tx":v[0],"ty":v[1],"tz":v[2]}) # set translation as part of construction
-</code>
-==== Setting/getting parameters ====
-You can tell a Transform deduce any of its parameters from a dictionary. Similarly you can get the parameters of a Transform as a dictionary
-<code python>
-t = Transform()
-t.set_params({"type":"eman","az":10,"alt":150,"scale":2.0,"mirror":True,"tx":3.4})
-d = t.get_params("eman") # must specify the euler convention
-s = Transform(d) # s is the same as t
-d = t.get_params("spider")
-s = Transform(d) # s is the same as t
-d = t.get_params("matrix")
-s = Transform(d) # s is the same as t
-</code>
-For more information the behaviour of set_params see  [[#set_params|a more in depth look at set_params]]
-==== A Transform multiplied by a Vec3f ====
-The transformation of a 3D vector $$ v = (v_x,v_y,v_z)^T $$ by a Transform is defined as
-$$ Tr \mathbf{v}  = [sMR,M\mathbf{t}] (v_x,v_y,v_z,1)^T = sMR\mathbf{v}+ M\mathbf{t}  $$
-This can be done in Python using the following
-<code python>
-t = Transform()
-t.set_params({"type":"eman","az":10,"alt":150,"scale":2.0,"mirror":True,"tx":3.4})
-v = Vec3f(3,4,10)
-v_transformed = t*v
-v_transformed = t.transform(v) # can also do it this way if you prefer
-</code>
-==== Transforming a 3D image ====
-Transforming a 3D image is achieved using a single function call
-<code python>
-t = Transform()
-t.set_params({"type":"eman","az":10,"alt":150,"scale":2.0,"mirror":True,"tx":3.4})
-t.set_trans( ... )
-e = test_image_3d()
-e.transform(t)
-</code>
-You can alternatively use the EMData processing framework, for example:
-<code python>
-t = Transform()
-t.set_params({"type":"eman","az":10,"alt":150,"scale":2.0,"mirror":True,"tx":3.4})
-t.set_trans( ... )
-f = e.process("xform",{"transform":t}) # memory efficient
-e.process_inplace("xform",{"transform":t})
-</code>
-In fact <code>e.transform(t)</code> actually calls <code>e.process_inplace("xform",{"transform":t})</code> internally on the C++ side.
-===== 2D degenerate use of the Transform object in Python =====
-----
-The Transform object can be used as though it were a 2D transformation matrix. In this case the interface for setting/getting scale and mirror is unchanged. However setting the rotation should be done using the euler type "2d", and there are some accommodations for setting and getting 2d translations and parameters.
-==== Setting/getting 2D rotations ====
-Use the "2d" euler type, and the angle is specified using "alpha"
-<code python>
-t = Transform()
-t.set_rotation({"type":"2d","alpha":32})
-a = t.get_rotation("2d")
-s = Transform(a) # works fine
-</code>
-==== Setting/getting 2D translation ====
-The interface is more or less identical to the 3D case
-<code python>
-t = Transform()
-t.set_trans(1,2) # method 1
-t.set_trans(Vec2f(1,2)) # method 2
-v = t.get_trans_2d()
-s = Transform("tx":v[0],"ty",v[1]) # set translation as part of construction
-</code>
-==== Setting/getting 2D parameters ====
-For getting the parameters in 2D form use the following
-<code python>
-t = Transform()
-t.set_params({"type":"2d","alpha":10,"scale":2.0,"mirror":True,"tx":3.4,"ty":0.0}) # no special interface required for 2D, use the same as 3D
-d = t.get_params("2d")
-s = Transform(d) # s is the same as t
-</code>
-==== A Transform multiplied by a Vec2f ====
-The transformation of a 2D vector $$ v_{2D} = (v_x,v_y)^T $$ by a Transform is equivalent to setting the z component of 3D vector to 0. If $$ v = (v_x,v_y,0)^T $$  then the 2D transformation is equivalent to the following,
-$$ Tr \mathbf{v_{2D}}  = [sMR,M\mathbf{t}] (v_x,v_y,0,1)^T = sMR\mathbf{v}+ M\mathbf{t}  $$
-and the z component is ignored. Note that the internal implementation is efficient. 2D vector transformation can be done in Python using the following
-<code python>
-t = Transform()
-t.set_params({"type":"2d","alpha":10,"scale":2.0,"mirror":True,"tx":3.4})
-v = Vec2f(3,1)
-v_transformed = t*v
-v_transformed = t.transform(v) # can also do it this way if you prefer
-</code>
-==== Transforming a 2D image ====
-Transforming a 2D image is achieved using a single function call
-<code python>
-t = Transform()
-t.set_params({"type":"2d","alpha":10,"scale":2.0,"mirror":True,"tx":3.4})
-e = test_image()
-e.transform(t)
-</code>
-You can alternatively use the EMData processing framework, for example:
-<code python>
-t = Transform()
-t.set_params({"type":"2d","alpha":10,"scale":2.0,"mirror":True,"tx":3.4})
-f = e.process("xform",{"transform":t}) # memory efficient
-e.proceess_inplace("xform",{"transform":t})
-</code>
-As stated previously, <code>e.transform(t)</code> actually calls <code>e.process_inplace("xform",{"transform":t})</code> internally on the C++ side.
-Note that if you try to transform a 2D image using a Transform that contains 3D rotations or translations you will get an error:
-<code python>
-t = Transform({"type":"eman","alt":22}) # 3D rotation
-a = test_image() # 2D
-a.transform(t) # ERROR is thrown
-t = Transform({"tz":3}) # 3D translation
-a.transform(t) # ERROR is thrown
-</code>
-<<Anchor(dict_const)>>
-===== A more in depth look at the dictionary constructor =====
-----
-The dictionary constructor, which is equivalent to calling the default constructor followed by the set_params function, takes up to 9 parameters as exemplified in the following
-<code python>
-t = Transform({"type":"eman","az":10,"alt":150,"phi":20,"scale":2.0,"mirror":True,"tx":3.4,"ty":3,"tz":2})
-t = Transform({"type":"spider","phi":10,"theta":150,"psi":20,"scale":2.0,"mirror":True,"tx":3.4,"ty":3,"tz":2})
-</code>
-If any of the angles or not specified they are implicitly set to 0
-<code python>
-t = Transform({"type":"spider","phi":10,"scale":2.0,"mirror":True,"tx":3.4,"ty":3,"tz":2}) # spider theta and psi are both 0
-t = Transform({"type":"spider","scale":2.0,"mirror":True,"tx":3.4,"ty":3,"tz":2}) # spider phi, theta and psi are all 0
-</code>
-If no euler type is specified then the rotation matrix is the identity
-<code python>
-t = Transform({"scale":2.0,"mirror":True,"tx":3.4,"ty":3,"tz":2}) # Rotation matrix is the identity
-</code>
-Similarly if any of the translation parameters are not specified they are implicitly set to 0
-<code python>
-t = Transform({"scale":2.0,"mirror":True,"tx":3.4,"ty":3}) # tz is 0
-t = Transform({"scale":2.0,"mirror":True}) # tx,ty and tz are all 0
-</code>
-If scale is not specified it is by default 1.0, similarly if mirror is not specified it is be default False
-<code python>
-t = Transform({"tx":3.4,"ty":3,"tz":3}) # scale is 1.0, mirror is False
-</code>
-<<Anchor(set_params)>>
-===== A more in depth look at set_params =====
-----
-Constructing a Transform with some dictionary is the same as calling set_params on a Transform that is the identity.
-<code python>
-d = {"type":"eman","az":10,"alt":150,"phi":20,"scale":2.0,"mirror":True,"tx":3.4,"ty":3,"tz":2}
-t = Transform(d) # t is initialized as the identity and then set_params(d) is called internally
-s = Transform() # s is the identity
-s.set_params(d) # s is identical to t
-</code>
-The main difference between calling set_params explicitly on a Transform as opposed to constructing a Tranform with a dictionary lies in the fact that the construction method first sets the Transform object to the identity before calling set_params. So if calling the set_params function on a Transform that has already been initialized and had many things done than you should be aware of the following...
-==== If unspecified, old parameters are retained ====
-<code python>
-t = Transform({"type":"eman","az":10,"alt":150,"phi":20,"scale":2.0,"mirror":True,"tx":3.4,"ty":3,"tz":2})
-d = {"tx":23,"ty":23,"tz":12}
-t.set_params(d) # t still has the same rotation, scale and mirror but it has an updated translation
-</code>
-==== For rotation and translation, setting one is equivalent to setting them all ====
-<code python>
-t = Transform({"tx":3.4,"ty":3,"tz":2})
-d = {"tx":23}
-t.set_params(d) # ty and tz are now 0
-#
-t = Transform({"type":"eman","az":10,"alt":150,"phi":20})
-d = {"type":"eman","phi":10}
-t.set_params(d) # alt and az are 0
-t.set_params({"type":eman}) # all angles are now 0
-</code>