7275
Comment:

7494

Deletions are marked like this.  Additions are marked like this. 
Line 46:  Line 46: 
'''''Relation between 3D mirror of an object and projection directions'''''. If a 3D object computed using projections with Eulerian angles phi, theta, psi, and shifts sx, sy and sz is mirrored along xaxis, Eulerian angles change as follows: {{{`(phi, 180theta, psi)`}}}. 
'''''Relation between 3D mirror of an object and projection directions'''''. If a 3D object computed using projections with Eulerian angles and shifts {{{`(phi, theta, psi, sx, sy)`}}}. is mirrored along xaxis, Eulerian angles change to {{{`(phi, 180theta, psi, sx, sy)`}}}. Another possibility is to change {{{`psi`}}} angle to {{{`(phi, theta, psi, sx, sy)`}}} and rotate the resulting structure in 3D by {{{`(phi=180., theta=180., psi=0.)`}}} to have the outcome mirrored along xaxis. 
Euler angles
Internally, SPARX shares with EMAN2 basic functionality of rotations/shifts/change of scale of multidimensional objects as provided by the transformClass Transform Class.
In practice it means that one can use the following conventions of Euler angles: SPIDER, EMAN, IMAGIC, SPIN, QUATERNION, SGIROT, MRC, XYZ, and MATRIX. However, SPARX system relies on SPIDER convention, which means that whenever user is prompted to provide Euler angles or when the system prints values of Euler angles, they are always in SPIDER convention. Also, much of the code uses internally Euler angles in SPIDER convention.
The explanation of various conventions and details of implementation are given in:
Baldwin, P.R., Penczek, P.A.: The transform class in SPARX and EMAN2. J. Struct. Biol., 157, pp.250261, 2007.
In what follows we focus on SPIDER convention.
Traditionally in EM the direction of propagation of the electron beam is thought to coincide with z axis, which in addition uniquely specifies xy as the plane in which the data is collected. Thus, it is convenient to express the rotations with respect to the z axis. By using a ZYZ convention (rotation around the z axis, followed by a rotation around y, and another around z), one benefits from the fact that the description bears a simple relation to the description of a point on a sphere; that is to say, we can think of the decomposition as the description of a point on the sphere (the first two Eulerian angles YZ) and a final inplane rotation (the final ZEulerian angle). We denote three respective Euler angles as phi `(phi)`, theta `(theta)`, psi `(psi)` and the corresponding rotation in matrix notation as a product of three matrices:
`R_Z(psi) R_Y(theta) R_Z(phi)=`
`((x'),(y'),(z'))=[[cos psi,sin psi, 0],[sin psi,cos psi,0],[0,0,1]] [[cos theta,0,sin theta],[0,1,0],[sin theta,0,cos theta]] [[cos phi,sin phi, 0],[sin phi,cos phi,0],[0,0,1]]((x),(y),(z))`
or as one `3x3` rotation matrix:
`((x'),(y'),(z'))=[[cos psi cos theta cos phi  sin psi sin phi, cos psi cos theta sin phi + sin psi cos phi, cos psi sin theta],[sin psi cos theta cos phi  cos psi sin phi, sin psi cos theta sin phi + cos psi cos phi, sin psi sin theta],[sin theta cos phi, sin theta sin phi, cos theta]]((x),(y),(z))`
This is called a ZYZ convention since the matrices appear in the order from right to left as clockwise rotations around z, y, and z, respectively. By “clockwise rotation around z", we mean that, when viewed along the positive axis, the rotation of the object looks clockwise. Recall that it is the matrix at the rightmost end that is applied first. So one might write a 3DEM rotation as `(phi, theta, psi)`, where `phi` is applied first, `theta` second and `psi` lastly.
Euler angles and projection directions
The operation of linear `3D > 2D` projection (ray transform) is given by two steps:
 Rotate the 3D structure by three Eulerian angles,
Add (integrate) densities along lines parallel to the new `z'` axis.
Thus, in this case projection of a 3D object results in a 2D image.
Based on definition of Euler angles above, it is easy to see that first two Eulerian angles `(phi, theta)` define projection direction, while `psi` defines rotation of projection inplane of projection. Thus, as far as projections are concerned `psi` is a trivial angle, as its change does not change the 'information content' of the projection.
Projection direction given by `(phi, theta)` can be thought of as a unitary vector (vector of length one) pointing from the origin of the system of coordinates to the surface of a unitary ball. A set of such points visualizes distribution of projection directions when 3D reconstruction is considered (See http://blake.bcm.edu/emanwiki/EMAN2/Symmetry.)
Relation between 3D rotation of an object and projection directions. Given Eulerian angles phi, theta, psi, and shifts sx, sy and sz, 3D rotation and shift of an object is done as: rvl = rot_shift3D(vol, phi, theta, psi, sx, sy, sz). If object vol was obtained using 3D reconstruction from a set of 2D projections, one can modify projection directions assigned to individual 2D projections using angles phi, theta, psi and shifts sx, sy, and sz such that if the 3D reconstruction is repeated, the reconstruction object will rotated accordingly and coincide with rvl:
rota = Transform({"type":"spider","phi":phi,"theta":theta,"psi":psi,"tx":sx,"ty":sy,"tz":sz}) rota = rota.inverse() for i in xrange(n): t = proj[i].get_attr( "xform.projection") t = t*rota proj[i].set_attr( "xform.projection" ,t)
Relation between 3D mirror of an object and projection directions. If a 3D object computed using projections with Eulerian angles and shifts `(phi, theta, psi, sx, sy)`. is mirrored along xaxis, Eulerian angles change to `(phi, 180theta, psi, sx, sy)`. Another possibility is to change `psi` angle to `(phi, theta, psi, sx, sy)` and rotate the resulting structure in 3D by `(phi=180., theta=180., psi=0.)` to have the outcome mirrored along xaxis.
The range of possible Eulerian angles for an asymmetric structure is `0<=phi<=360, 0<=theta<=180, 0<=psi<=360)`. However, for each projection whose direction is `(phi, theta, psi)` there exists a projection that is related to it by an inplane mirror operation along xaxis and whose direction is `(180+phi, 180theta, psi)`. Note the projection direction of the mirrored projection is also in the same range of Eulerian angles as all angles are given modulo 360 degrees (i.e., if say `phi > 360`, then `phi = phi  360`, also if `phi < 0`, then `phi = phi + 360`.
By default SPARX will not generate mirrored versions of reference projections in exhaustive searches in 3D projection alignment procedures. Whether given projection data has to be mirrored is determined computationally internal to SPARX operations (see: Penczek, P., Radermacher, R. and Frank, J.: Threedimensional reconstruction of single particles embedded in ice. Ultramicroscopy 40:3353, 1992. and also Joyeux, L. and Penczek, P.A.: Efficiency of 2D alignment methods. Ultramicroscopy 92:3346, 2002.)
For more details see:
 Vainshtein, B.K., Penczek, P.A.: Threedimensional reconstruction, in U. Shmueli (Ed.), International Tables for Crystallography 3 ed., vol. B Reciprocal Space, 2008.
Pointgroup symmetries
There are five possible pointgroup symmetries, i.e., symmetries in which one point in 3D remains unmoved. In SPARX, they are defined by a symmetry symbol:
 'cn'  cyclic
 'dn'  dihedral
 'oct'  octahedral
 'tet'  tetrahedral
 'icos'  icosahedral (main axis is fivefold)
 where 'n' stands for symmetry order, for example c3 means threefold symmetry around main axis. For all pointgroup symmetries in SPARX, the main axis coincides with 'z'axis.
Function get_sym(symmetry_symbol) returns a list of Eulerian angles corresponding to given pointgroup symmetry, i.e, 3D rotation using any of these angles rotates the object onto itself.