py_convrot: rotation conventions, to understand and to apply

Urzhumtseva, L.; Urzhumtsev, A.

doi:10.1107/S1600576719007313

teaching and education

JOURNAL OF
APPLIED
CRYSTALLOGRAPHY

ISSN: 1600-5767

Volume 52| Part 4| August 2019| Pages 869-881

https://doi.org/10.1107/S1600576719007313

py_convrot: rotation conventions, to understand and to apply

Ludmila Urzhumtseva ^a,^b ^* and Alexandre Urzhumtsev ^c,^d ^*

^aArchitecture et Réactivité de l'ARN, UPR 9002 CNRS, IBMC (Institute of Molecular and Cellular Biology), 15 rue R. Descartes, 67084 Strasbourg, France, ^bUniversité de Strasbourg, 67000 Strasbourg, France, ^cCentre of Integrative Biology, Institut de Génétique et de Biologie Moléculaire et Cellulaire, CNRS–INSERM-UdS, 1 rue Laurent Fries, BP 10142, 67404 Illkirch, France, and ^dUniversité de Lorraine, Faculté des Sciences et Technologies, BP 239, 54506 Vandoeuvre-les-Nancy, France
^*Correspondence e-mail: l.ourjoumtseva@unistra.fr, sacha@igbmc.fr

Edited by J. M. García-Ruiz, Instituto Andaluz de Ciencias de la Tierra, Granada, Spain (Received 15 February 2019; accepted 20 May 2019; online 8 July 2019)

Rotation is a core crystallographic operation. Two sets of Cartesian coordinates of each point of a rotated object, those before and after rotation, are linearly related, and the coefficients of these linear combinations can be represented in matrix form. This 3 × 3 matrix is unique for all points and thus describes unambiguously a particular rotation. However, its nine elements are mutually dependent and are not interpretable in a straightforward way. To describe rotations by independent and comprehensible parameters, crystallographic software usually refers to Euler or to polar angles. In crystallography and cryo-electron microscopy, there exists a large choice of conventions, making direct comparison of rotation parameters difficult and sometimes confusing. The program py_convrot, written in Python, is a converter of parameters describing rotations. In particular, it deals with all possible choices of polar angles and with all kinds of Euler angles, including all choices of rotation axes and rotation directions. Using a menu, a user can build their own rotation parameterization; its action can be viewed with an interactive graphical tool, Demo. The tables in this article and the extended help pages of the program describe details of these parameterizations and the decomposition of rotation matrices into all types of parameters. The program allows orthogonalization conventions and symmetry operations to be taken into account. This makes the program and its supporting materials both an illustrative teaching material, especially for non-specialists in mathematics and computing, and a tool for practical use.

Keywords: rigid-body rotation; rotation matrices; rotation conventions; teaching tools; interactive illustrations; Euler angles; polar angles; direction cosines.

1. Introduction

Rotation in three-dimensional space is one of the principal geometric operations in crystallography and electron microscopy. By definition, rotation is an operation that conserves all distances and has a point fixed, differently from translation. This operation is linear, meaning that for each point its Cartesian coordinates after rotation are linear combinations of its coordinates before rotation. The coefficients of these linear combinations are the same for all points and can be represented in matrix form. Such a rotation matrix describes the corresponding rotation unambiguously. However, the elements of such 3 × 3 matrices are mutually dependent; not every matrix describes a rotation. Also, interpreting a rotation matrix in terms of motions is not easy, except for trivial cases. For these reasons, in order to manipulate different objects and models and to define their spatial positions, it is convenient to describe rotations in terms of `physical' parameters, independent if possible. Euler (1776 ; translation in English by J. Sten, https://www.17centurymaths.com/contents/euler/e478tr.pdf) showed that

(1) `in whatever way a sphere is turned about its centre, it is always possible to assign a diameter, whose direction in the translated state agrees with that of the initial state', and

(2) `everything [rigid-body rotation] can be defined using three angles'.

In other words, each rotation in three-dimensional space keeps not only a point but a whole line fixed, and each rotation can be realized as a suite of three consecutive elemental rotations about coordinate axes. These two results are at the origin of the rotation descriptions given by so-called polar angles¹ and Euler angles, respectively. The large choice of ways to define the position of the rotation axis (for the former description) and to define the three rotation axes and relevant rotation angles (for the latter description) is the principal reason for frequent misunderstanding and confusion. This variability is not only theoretical; in particular, a very large list of conventions is used in structural biology. The reason for this is that different problems may be better solved using different sets of parameters; there is also the matter of habits in a given research field and its historical development. This large choice requires understanding and conversion of one group of parameters to another.

The literature describing rotation theory is vast and often matches to the features of particular fields and problems. In structural biology, it varies from formal general descriptions, e.g. Diamond & Cranswick (2010 ), barely accessible to non-mathematicians, to textbooks and fundamental articles describing details of a particular choice of parameters, for example Giacovazzo et al. (1992 ), Heymann et al. (2005 , 2006 ) and Rupp (2010 ). At the same time, comprehensive material explaining the variety of rotation conventions and their relations (e.g. Goldstein, 1950 ) is practically nonexistent to our knowledge. This leads not only to insufficient understanding of the particular procedures but also to a number of errors in the existing descriptions that sometimes disagree with actual program code.

Previously, a program convrot (Urzhumtseva & Urzhumtsev, 1997 ) was developed to convert one set of rotation parameters to another for a large list of crystallographic conventions known at that time. This program has now become obsolete. Tulloue (2001 ) has created an excellent illustrative site of rotations defined by Euler angles, but only for a single choice of axes. EulerAngles (Bigras & Bonev, 2012 ) uses all possible sets of Euler angles for rotations about moving coordinate axes and illustrates them. However, it refers neither to rotation conventions in polar angles nor to rotations about fixed coordinate axes. Pan (Morawiec, 2015 ) defines a given rotation simultaneously by quaternions, direction cosines and some particular set of Euler angles. The program 3D Rotation Converter (Gaschler, 2016 ) is more general but also does not address some major rotation conventions. The site https://www.geometrictools.com/Documentation/EulerAngles.pdf by D. Eberly gives rotation matrices for different sets of Euler angles and expressions for the respective angles.

In summary, these programs and sites cover a limited range of conventions while missing some used in structural biology. Only a few of them are illustrative; practically none of them deal with symmetries and orthogonalization conventions that are important in crystallographic projects.

To address these problems, we have developed a new rotation converter, py_convrot, and describe it herein, with the following considerations:

(a) The program should not simply convert one set of numbers into another but be capable of graphically illustrating what the respective numbers mean; it should have an interactive illustrator of different rotation conventions.

(b) The program needs to be in an open form and not to only refer to conventions used nowadays.

(c) The program and the complementary material should be self-contained, so that users can reproduce all calculations without requiring external information.

(d) The material should be accessible to readers without advanced training in mathematics and informatics.

(e) The description of parameters should be non-confusing, especially in cases of contradicting notations and comments in existing literature and software descriptions. The main text should contain only the principal relations while appendices give all minimally necessary technical details and demonstrations.

(f) The software should be as compatible as possible with widely used crystallographic packages and program suites, such as CCP4 (Collaborative Computational Project, Number 4, 1994 ), PyMol (DeLano, 2002 ; https://www.pymol.org), Phenix (Adams et al., 2010 ), Coot (Emsley et al., 2010 ) and others, and be principally aimed at projects in crystallography and electron microscopy.

2. Converter purpose

2.1. Conversion of rotation parameters

The converter addresses the problem that the rotation of an object (a rigid body) in three-dimensional space can be described by different types of parameters. This variety of descriptions is large since

(a) one can describe a rotation as a single operation about an axis in a general orientation (polar angles) or by three consecutive rotations about coordinate axes (Euler angles),

(b) both polar and Euler angles may be defined with respect to different coordinate axes,

(d) a positive direction of each rotation may be defined in two opposite ways, and

(e) some conventions consider the object rotating with respect to a fixed coordinate system, while some do it inversely.

Note that (c) and (e) are different. In (c) there are two different choices of the rotation axes, but the object is always moved and the system is kept fixed, while in (e) there are two different choices for the fixed and rotating items.

The program py_convrot considers all possible choices listed above. For each of these conventions, the program first calculates the rotation matrix corresponding to the given values of parameters. At the next step this matrix is interpreted in terms of parameters corresponding to any other convention, according to the user's choice. If requested, this matrix can be applied to a list of atomic coordinates in order to get a list of respective coordinates after rotation (rotated atomic model). The program can operate either with a single set of parameter values or with a list of sets.

The program also considers the rotation description by the direction cosines defining the orientation of the rotation axis and that by quaternions. Differently from convrot, it no longer considers the Lattman (1972 ) parameterization of the Euler angles used in CNS (Brünger et al., 1998 ).

Specifically for crystallographic projects, orthogonalization conventions may be taken into account when defining the rotations. If crystallographic symmetry operations (space group) are known and selected from the menu, the program gives a full list of symmetry-related angles after rotation; this option may be useful for molecular replacement to compare results of several rotation functions (Urzhumtsev & Urzhumtseva, 2002 ; Urzhumtseva & Urzhumtsev, 2002 ).

2.2. Teaching goals

Teaching is another principal purpose of the program.

Demo is an interactive graphical tool especially useful for understanding and comparing different rotation conventions. For each choice of rotation parameters, Demo shows how the position of an object changes with a variation of values of the chosen parameters. A user can choose their own combination of rotation parameters, creating and trying new conventions.

Help gives principal formulae for rotation conventions and illustrates them one by one. Help pages are available in pdf format; they are provided together with the program and can be used separately.

Section 3 and Appendices A–D provide reminders of principal definitions, basic notions and results concerning rotations. Tables 1–3 summarize basic information relevant to the choice of the rotation matrices and their parameters when using direction cosines and quaternions (Table 1) or Euler (Table 2) or polar angles (Table 3).

Table 1
Rotation matrices for the direction cosines and for quaternions and their values extracted from the matrix

For κ = π or q₀ = 0 the component without the sign function is usually that with the largest absolute value among the diagonal elements, and the other two components are defined using sign. The table gives an example when l_z is the largest component. cκ and sκ stand for the cosine and sine of the rotation angle κ. For other definitions see Section 3.3.1.

Matrix	Matrix solution
$[\left[\matrix{l_x^2(1-{\rm c}\kappa) + {\rm c}\kappa & {l_x\,l_y}\, (1-{\rm c}\kappa) -{l_z \,{\rm s}}\kappa & {l_x \,l_z} \,(1-{\rm c}\kappa) + {l_y \,{\rm s}}\kappa \cr\cr {l_x \,l_y} (1-{\rm c}\kappa) + {l_z \,{\rm s}}\kappa& l_y^2 (1-{\rm c}\kappa)+ {\rm c}\kappa& {l_y \,l_z} \,(1-{\rm c}\kappa)-{l_x \, {\rm s}}\kappa \cr\cr {l_x \,l_z} \,(1-{\rm c}\kappa) - {l_y \, {\rm s}}\kappa& {l_y \,l_z} \,(1-{\rm c}\kappa) +{l_x \,{\rm s}}\kappa & l_z^2(1-{\rm c}\kappa) + {\rm c}\kappa }\right]]$	$[\eqalign{ & \kappa = {\rm arccos}\,[\textstyle{1 \over 2}(r_{11} + r_{22} + r_{33} - 1)] \cr\cr & \kappa = 0\colon\,\, l_x = {l_y} = 0, {l_z} = 1 \cr \cr &0 \,\lt\, \kappa \,\lt\, \pi\colon\,\, \cr & \quad l_x = [(r_{32} - r_{23})/(2\,{\rm s}\kappa)] \cr & \quad{l_y} = [(r_{13} - r_{31})/(2\,{\rm s}\kappa)] \cr & \quad{l_z} = [(r_{21} - r_{12})/(2\,{\rm s}\kappa)]\cr\cr& \kappa = \pi\colon\,\, \cr & \quad l_x = {\rm sign}\,(r_{13})\cos[\textstyle{1 \over 2}\,{\rm arccos}\,(r_{11})] \cr & \quad {l_y} = {\rm sign}\,(r_{23})\cos[\textstyle{1 \over 2}\,{\rm arccos}\,(r_{22})]\cr & \quad{l_z} = \cos[\textstyle{1 \over 2}\,{\rm arccos}\,(r_{33})]}]$
$[\left[\matrix{q_0^2 +q_x^2 -q_y^2-q_z^2& 2(q_x \,q_y -q_z \,q_0) & 2(q_x \,q_z+q_y \,q_0) \cr\cr 2(q_x \,q_y+q_z \,q_0) & q_0^2+q_y^2 -q_z^2-q_x^2 & 2(q_y \,q_z-q_x \,q_0) \cr\cr 2(q_x \,q_z-q_y \,q_0) & 2(q_y \,q_z+q_x \,q_0) & q_0^2+q_z^2 -q_x^2-q_y^2} \right]]$	$[\eqalign{ & { q}_0 = \textstyle{1 \over 2}[(r_{11} + r_{22} + r_{33} + 1)]^{1/2} \cr \cr & { q}_0 \,\gt\, 0\colon \cr & \quad {q_x} = [(r_{32} - r_{23})/(4q_0)] \cr & \quad{q_y} = [(r_{13} - r_{31})/(4q_0)] \cr & \quad{q_z} = [(r_{21} - r_{12})/(4q_0)]\cr \cr & q_0 = 0\colon\cr &\quad{q_x} = {\rm sign}\,(r_{13})\cos[\textstyle{1\over 2}\,{\rm arccos}\,(r_{11})]\cr & \quad{q_y} = {\rm sign}\,(r_{23})\cos[\textstyle{1\over 2}\,{\rm arccos}\,(r_{22})]\cr & \quad{q_z} = \cos[\textstyle{1\over 2}\,{\rm arccos}\,(r_{33})] }]$

Table 2
Euler angles: rotation matrices and angles extracted from the matrices

c1 and s1 stand for cos(κ₁) and sin(κ₁); similarly for c2, s2, c3 and s3. The function atan2(y, x) defines the angle κ such that tanκ = y/x and that the signs of sin(κ) and cos(κ) coincide with the signs of y and x, respectively.

Matrix product	Resulting rotation matrix	Matrix solution
R_x(κ₃)R_y(κ₂)R_x(κ₁)	$[\left( \matrix{\rm c2 & \rm s1\, s2 & \rm c1\,s2 \cr \rm s2\,s3 & \rm -s1\,c2\,s3 + c1\,c3 &\rm -c1\, c2\,s3 - s1\,c3 \cr \rm -s2\,c3 & \rm s1\,c2\,c3 + c1\,s3 & \rm c1\,c2\,c3 - s1\,s3 }\right)]$	$[\eqalign{ & \kappa_2 = \arccos (r_{11}) \cr & {\rm s2 = 0\colon} \,\, \kappa_1 = {\rm atan2}\,(-r_{23}, r_{22}), \kappa_3 = 0 \cr & {\rm s2} \,\gt\, 0\colon \,\,\kappa_1 = {\rm atan2}\,(r_{12}, r_{13}), \kappa_3 = {\rm atan2}\,(r_{21}, -r_{31})}]$
R_y(κ₃)R_z(κ₂)R_y(κ₁)	$[\left( \matrix{\rm c1\,c2\,c3 - s1\,s3 & \rm -s2\,c3 & \rm s1\,c2\,c3 + c1\,s3 \cr \rm c1\,s2 & \rm c2 & \rm s1\,s2 \cr\rm -c1\,c2\,s3 - s1\,c3 & \rm s2\,s3 & \rm -s1\,c2\,s3 + c1\,c3} \right)]$	$[\eqalign{ & \kappa_2 = {\rm arccos}\,(r_{22}) \cr & {\rm s2} = 0\colon\,\, \kappa_1 = {\rm atan2}\,(-r_{31}, r_{33}), \kappa_3 = 0 \cr & {\rm s2} \,\gt\, 0\colon\,\, \kappa_1 = {\rm atan2}\,(r_{23}, r_{21}), \kappa_3 = {\rm atan2}\,(r_{32}, -r_{12})}]$
R_z(κ₃)R_x(κ₂)R_z(κ₁)	$[\left( \matrix{\rm -s1\,c2\,s3 + c1\,c3 & \rm -c1\,c2\,s3 - s1\,c3 & \rm s2\,s3 \cr \rm s1\,c2\,c3 + c1\,s3 & \rm c1\,c2\,c3 - s1\,s3 & \rm -s2\,c3 \cr \rm s1\,s2 & \rm c1\,s2 & \rm c2 }\right)]$	$[\eqalign{ & \kappa_2 = {\rm arccos}\,(r_{33}) \cr & {\rm s2} = 0\colon \,\,\kappa_1 = {\rm atan2}\,(-r_{12}, r_{11}), \kappa_3 = 0 \cr & {\rm s2} \,\gt\, 0\colon\,\, \kappa_1 = {\rm atan2}\,(r_{31}, r_{32}), \kappa_3 = {\rm atan2}\,(r_{13}, -r_{23})}]$
R_x(κ₃)R_z(κ₂)R_x(κ₁)	$[\left( \matrix{\rm c2 & \rm - c1\,s2 & \rm s1\,s2 \cr \rm s2\,c3 & \rm c1\,c2\,c3 - s1\,s3 & \rm -s1\,c2\,c3 - c1\,s3 \cr \rm s2\,s3 & \rm c1\,c2\,s3 +s1\,c3 & \rm -s1\,c2\,s3 +c1\,c3}\right)]$	$[\eqalign{ & \kappa_2 = {\rm arccos}\,(r_{11}) \cr & {\rm s2} = 0\colon \,\,\kappa_1 = {\rm atan2}\,(r_{32}, r_{33}), \kappa_3 = 0 \cr & {\rm s2} \,\gt\, 0\colon\,\, \kappa_1 = {\rm atan2}\,(r_{13}, -r_{12}), \kappa_3 = {\rm atan2}\,(r_{31}, r_{21})}]$
R_y(κ₃)R_x(κ₂)R_y(κ₁)	$[\left( \matrix{\rm -s1\,c2\,s3 +c1\,c3 & \rm s2\,s3 & \rm c1\,c2\,s3 +s1\,c3 \cr \rm s1\,s2 & \rm c2 & \rm - c1\,s2 \cr \rm -s1\,c2\,c3 - c1\,s3 & \rm s2\,c3 & \rm c1\,c2\,c3 - s1\,s3}\right)]$	$[\eqalign{ & \kappa_2 = {\rm arccos}\,(r_{22}) \cr & {\rm s2} = 0\colon\,\, \kappa_1 = {\rm atan2}\,(r_{13}, r_{11}), \kappa_3 = 0 \cr & {\rm s2} \,\gt\, 0\colon\,\, \kappa_1 = {\rm atan2}\,(r_{21}, -r_{23}), \kappa_3 = {\rm atan2}\,(r_{12}, r_{32})}]$
R_z(κ₃)R_y(κ₂)R_z(κ₁)	$[\left( \matrix{\rm c1\,c2\,c3 - s1\,s3 & \rm -s1\,c2\,c3 - c1\,s3 & \rm s2\,c3 \cr \rm c1\,c2\,s3 +s1\,c3 & \rm -s1\,c2\,s3 +c1\,c3 & \rm s2\,s3 \cr \rm - c1\,s2 & \rm s1\,s2 & \rm c2}\right)]$	$[\eqalign{ & \kappa_2 = {\rm arccos}(r_{33}) \cr & {\rm s2} = 0\colon\,\, \kappa_1 = {\rm atan2}\,(r_{21}, r_{22}), \kappa_3 = 0 \cr & {\rm s2} \,\gt\, 0\colon\,\, \kappa_1 = {\rm atan2}\,(r_{32}, -r_{31}), \kappa_3 = {\rm atan2}\,(r_{23}, r_{13})}]$
R_z(κ₃)R_y(κ₂)R_x(κ₁)	$[\left( \matrix{\rm c2\,c3 & \rm s1\,s2\,c3 - c1\,s3 & \rm c1\,s2\,c3 +s1\,s3 \cr \rm c2\,s3 & \rm s1\,s2\,s3 +c1\,c3 & \rm c1\,s2\,s3 - s1\,c3 \cr \rm -s2 & \rm s1\,c2 & \rm c1\,c2}\right)]$	$[\eqalign{& \kappa_2 = -{\rm arcsin}\,(r_{31}) \cr & {\rm c2} = 0\colon\,\, \kappa_1 = {\rm atan2}\,(-r_{23}, r_{22}), \kappa_3 = 0 \cr &{\rm c2} \,\gt\, 0\colon\,\, \kappa_1 = {\rm atan2}\,(r_{32}, r_{33}), \kappa_3 = {\rm atan2}\,(r_{21}, r_{11})} ]$
R_x(κ₃)R_z(κ₂)R_y(κ₁)	$[ \left( \matrix{\rm c1\,c2 & \rm -s2 & \rm s1\,c2 \cr \rm c1\,s2\,c3 +s1\,s3 & \rm c2\,c3 & \rm s1\,s2\,c3 - c1\,s3 \cr \rm c1\,s2\,s3 - s1\,c3 & \rm c2\,s3 & \rm s1\,s2\,s3 +c1\,c3}\right)]$	$[\eqalign{ & \kappa_2 = -{\rm arcsin}\,(r_{12}) \cr & {\rm c2} = 0\colon\,\, \kappa_1 = {\rm atan2}\,(-r_{31}, r_{33}), \kappa_3 = 0 \cr & {\rm c2} \,\gt\, 0\colon\,\, \kappa_1 = {\rm atan2}\,(r_{13}, r_{11}), \kappa_3 = {\rm atan2}\,(r_{32}, r_{22})}]$
R_y(κ₃)R_x(κ₂)R_z(κ₁)	$[\left( \matrix{\rm s1\,s2\,s3 +c1\,c3 & \rm c1\,s2\,s3 - s1\,c3 & \rm c2\,s3 \cr \rm s1\,c2 & \rm c1\,c2 & \rm -s2 \cr \rm s1\,s2\,c3 - c1\,s3 & \rm c 1\,s2\,c3 +s1\,s3 & \rm c2\,c3}\right)]$	$[\eqalign{ & \kappa_2 = -{\rm arcsin}\,(r_{23}) \cr & {\rm c2} = 0\colon \,\,\kappa_1 = {\rm atan2}\,(-r_{12}, r_{11}), \kappa_3 = 0 \cr & {\rm c2} \,\gt\, 0\colon \,\,\kappa_1 = {\rm atan2}\,(r_{21}, r_{22}), \kappa_3 = {\rm atan2}\,(r_{13}, r_{33})}]$
R_y(κ₃)R_z(κ₂)R_x(κ₁)	$[\left( \matrix{\rm c2\,c3& \rm -c1\,s2\,c3 +s1\,s3 & \rm s1\,s2\,c3 +c1\,s3 \cr \rm s2 & \rm c1\,c2 & \rm - s1\,c2 \cr \rm -c2\,s3 & \rm c1\,s2\,s3 +s1\,c3 & \rm -s1\,s2\,s3 +c1\,c3}\right)]$	$[\eqalign{ & \kappa_2 = {\rm arcsin}\,(r_{21}) \cr & {\rm c2} = 0\colon\,\, \kappa_1 = {\rm atan2}\,(r_{32}, r_{33}), \kappa_3 = 0 \cr &{\rm c2} \,\gt\, 0\colon\,\, \kappa_1 = {\rm atan2}\,(-r_{23}, r_{22}), \kappa_3 = {\rm atan2}\,(-r_{31}, r_{11})}]$
R_z(κ₃)R_x(κ₂)R_y(κ₁)	$[\left( \matrix{\rm -s1\,s2\,s3 +c1\,c3 & \rm -c2\,s3 & \rm c1\,s2\,s3 +s1\,c3 \cr \rm s1\,s2\,c3 +c1\,s3 & \rm c2\,c3 & \rm -c1\,s2\,c3 +s1\,s3 \cr \rm - s1\,c2 & \rm s2& \rm c1\,c2}\right)]$	$[\eqalign{ & \kappa_2 = {\rm arcsin}\,(r_{32}) \cr & {\rm c2} = 0\colon\, \kappa_1 = {\rm atan2}\,(r_{13}, r_{11}), \kappa_3 = 0 \cr & {\rm c2} \,\gt\, 0\colon \,\kappa_1 = {\rm atan2}\,(-r_{31}, r_{33}), \kappa_3 = {\rm atan2}\,(-r_{12}, r_{22})}]$
R_x(κ₃)R_y(κ₂)R_z(κ₁)	$[\left( \matrix{\rm c1\,c2 & \rm - s1\,c2 & \rm s2 \cr \rm c1\,s2\,s3 +s1\,c3 & \rm -s1\,s2\,s3 +c1\,c3 & \rm -c2\,s3 \cr \rm -c1\,s2\,c3 +s1\,s3 & \rm s1\,s2\,c3 +c1\,s3 & \rm c2\,c3}\right)]$	$[\eqalign{& \kappa_2 = {\rm arcsin}\,(r_{13}) \cr & {\rm c2} = 0\colon\,\, \kappa_1 = {\rm atan2}\,(r_{21}, r_{22}), \kappa_3 = 0 \cr & {\rm c2} \,\gt\, 0\colon\,\, \kappa_1 = {\rm atan2}\,(-r_{12}, r_{11}), \kappa_3 = {\rm atan2}\,(-r_{23}, r_{33})}]$

Table 3
Polar angles: rotation matrices and angles extracted from the matrices.

ζ is the zenith angle. cζ and sζ stand for cos(ζ) and sin(ζ); similarly for the azimuth angle η and rotation angle κ. atan2(y, x) is defined as for Table 2.

Rotation matrix product	Resulting rotation matrix	Matrix solution
$[\eqalign{ & {\rm Zenith}\colon\,\, Z \cr & {\rm Azimuth}\colon\,\, X \cr\cr & R_z(\eta)R_y(\zeta)R_z(\kappa)R_y(-\zeta)R_z(-\eta)}]$	$[\left[\matrix{({\rm s}\zeta)^2\,({\rm c}\eta)^2\,(1-{\rm c}\kappa) & ({\rm s}\zeta)^2\,{\rm s}\eta \,{\rm c}\eta \,(1-{\rm c}\kappa) & {\rm s}\zeta\,{\rm c}\zeta\,{\rm c}\eta \,(1-{\rm c}\kappa) \cr + \,{\rm c}\kappa & - \,{\rm c}\zeta\,{\rm s}\kappa & + \,{\rm s}\zeta\,{\rm s}\eta \,{\rm s}\kappa \cr\cr ({\rm s}\zeta)^2\,{\rm s}\eta \,{\rm c}\eta \,(1-{\rm c}\kappa) & ({\rm s}\zeta)^2\,({\rm s}\eta)^2\,(1-{\rm c}\kappa) & {\rm s}\zeta\,{\rm c}\zeta\,{\rm s}\eta \,(1-{\rm c}\kappa) \cr +\, {\rm c}\zeta\,{\rm s}\kappa& + \,{\rm c}\kappa & - \,{\rm s}\zeta\,{\rm c}\eta \,{\rm s}\kappa \cr \cr {\rm s}\zeta\,{\rm c}\zeta\,{\rm c}\eta \,(1-{\rm c}\kappa) & {\rm s}\zeta\,{\rm c}\zeta\,{\rm s}\eta \,(1-{\rm c}\kappa) & ({\rm c}\zeta)^2\,(1-{\rm c}\kappa) +{\rm c}\kappa\cr - \,{\rm s}\zeta\,{\rm s}\eta \,{\rm s}\kappa & + \,{\rm s}\zeta\,{\rm c}\eta \,{\rm s}\kappa & }\right]]$	$[\eqalign{& \kappa = {\rm arccos}\,[(r_{11}+r_{22}+r_{33}-1)/2] \cr\cr& \kappa = 0\colon\,\, \zeta = \eta = 0 \cr \cr & 0\,\lt\, \kappa \,\lt\, \pi\colon\,\, \zeta = {\rm arccos}\,[(r_{21}-r_{12})/(2\,{\rm s}\kappa)] \cr & \quad \zeta = 0 \,\,{\rm or}\,\, \zeta = \pi\colon\,\, \eta = 0 \cr & \quad 0 \,\lt\, \zeta \,\lt\, \pi\colon\,\, \eta = {\rm atan2} \,(r_{13}-r_{31}, r_{32}-r_{23}) \cr\cr & \kappa = \pi\colon\,\, \zeta = \textstyle{1 \over 2}{\rm arccos}\,(r_{33}) \cr & \quad \zeta = 0\colon\,\, \eta = 0 \cr &\quad \zeta = \pi/2\colon\,\, \eta = \textstyle{1 \over 2}\,{\rm atan2}\,(r_{12}+r_{21}, 2r_{11}) \cr & \quad 0 \,\lt\, \zeta \,\lt\,\pi/2\colon\,\, \eta = {\rm atan2}\,(r_{23}+r_{32}, r_{13}+r_{31})}]$
$[ \eqalign{&{\rm Zenith}\colon\,\, X \cr & {\rm Azimuth}\colon\,\, Y \cr \cr & R_x(\eta)R_z(\zeta)R_x(\kappa)R_z(-\zeta)R_x(-\eta)}]$	$[\left[\matrix{({\rm c}\zeta)^2\,(1-{\rm c}\kappa) +{\rm c}\kappa & {\rm s}\zeta\,{\rm c}\zeta\,{\rm c}\eta \,(1-{\rm c}\kappa) & {\rm s}\zeta\,{\rm c}\zeta\,{\rm s}\eta \,(1-{\rm c}\kappa) \cr & - \,{\rm s}\zeta\,{\rm s}\eta \,{\rm s}\kappa & + \,{\rm s}\zeta\,{\rm c}\eta \,{\rm s}\kappa \cr \cr {\rm s}\zeta\,{\rm c}\zeta\,{\rm c}\eta \,(1-{\rm c}\kappa) & ({\rm s}\zeta)^2\,({\rm c}\eta)^2\,(1-{\rm c}\kappa) & ({\rm s}\zeta)^2\,{\rm s}\eta \,{\rm c}\eta \,(1-{\rm c}\kappa) \cr + \,{\rm s}\zeta\,{\rm s}\eta \,{\rm s}\kappa & +\, {\rm c}\kappa & - \,{ \rm c}\zeta\,{\rm s}\kappa \cr\cr {\rm s}\zeta\,{\rm c}\zeta\,{\rm s}\eta \,(1-{\rm c}\kappa) & ({\rm s}\zeta)^2\,{\rm s}\eta \,{\rm c}\eta \,(1-{\rm c}\kappa) & ({\rm s}\zeta)^2\,({\rm s}\eta)^2\,(1-{\rm c}\kappa) \cr - \,{\rm s}\zeta\,{\rm c}\eta \,{\rm s}\kappa & + \,{\rm c}\zeta\,{\rm s}\kappa& +\, {\rm c}\kappa}\right] ]$	$[\eqalign{& \kappa = {\rm arcos}\,[(r_{11}+r_{22}+r_{33}-1)/2] \cr\cr & \kappa = 0\colon\,\, \zeta = \eta = 0 \cr \cr & 0\,\lt\, \kappa \,\lt\, \pi\colon\,\, \zeta = {\rm arccos}\,[(r_{32}-r_{23})/(2\,{\rm s}\kappa)] \cr & \quad \zeta = 0 \,\,{\rm or}\,\, \zeta = \pi\colon\,\, \eta = 0 \cr & \quad 0 \,\lt\, \zeta \,\lt\, \pi\colon\,\, \eta = {\rm atan2}\,(r_{21}-r_{12}, r_{13}-r_{31}) \cr\cr & \kappa = \pi\colon\,\, \zeta = \textstyle{1 \over 2}\,{\rm arccos}\,(r_{11}) \cr & \quad \zeta = 0\colon\,\, \eta = 0 \cr & \quad \zeta = \pi/2\colon\,\, \eta = \textstyle{1 \over 2}\,{\rm atan2}\,(r_{23}+r_{32}, 2r_{22}) \cr & \quad 0 \,\lt\, \zeta \,\lt\, \pi/2\colon\,\, \eta = {\rm atan2}\,(r_{31}+r_{13}, r_{21}+r_{12})}]$
$[ \eqalign{ & {\rm Zenith}\colon\,\, Y \cr & {\rm Azimuth}\colon\,\, Z \cr \cr& R_y(\eta)R_x(\zeta)R_y(\kappa)R_x(-\zeta)R_y(-\eta)}]$	$[\left[\matrix{({\rm s}\zeta)^2\,({\rm s}\eta)^2\,(1-{\rm c}\kappa) & {\rm s}\zeta\,{\rm c}\zeta\,{\rm s}\eta \,(1-{\rm c}\kappa) & ({\rm s}\zeta)^2\,{\rm s}\eta \,{\rm c}\eta \,(1-{\rm c}\kappa) \cr + \,{\rm c}\kappa& -\, {\rm s}\zeta\,{\rm c}\eta \,{\rm s}\kappa & +\, {\rm c}\zeta\,{\rm s}\kappa \cr \cr {\rm s}\zeta\,{\rm c}\zeta\,{\rm s}\eta \,(1-{\rm c}\kappa) & ({\rm c}\zeta)^2\,(1-{\rm c}\kappa) +{\rm c}\kappa & {\rm s}\zeta\,{\rm c}\zeta\,{\rm c}\eta \,(1-{\rm c}\kappa) \cr + \,{\rm s}\zeta\,{\rm c}\eta \,{\rm s}\kappa & & - \,{\rm s}\zeta\,{\rm s}\eta \,{\rm s}\kappa \cr\cr ({\rm s}\zeta)^2\,{\rm s}\eta \,{\rm c}\eta \,(1-{\rm c}\kappa) & {\rm s}\zeta\,{\rm c}\zeta\,{\rm c}\eta \,(1-{\rm c}\kappa) & ({\rm s}\zeta)^2\,({\rm c}\eta)^2\,(1-{\rm c}\kappa) \cr - \,{\rm c}\zeta\,{\rm s}\kappa & + \,{\rm s}\zeta\,{\rm s}\eta \,{\rm s}\kappa & + \,{\rm c}\kappa}\right]]$	$[\eqalign{& \kappa = {\rm arcos}\,[(r_{11}+r_{22}+r_{33}-1)/2] \cr\cr& \kappa = 0\colon\,\, \zeta = \eta = 0 \cr \cr & 0\,\lt\, \kappa \,\lt\, \pi\colon\,\, \zeta = {\rm arccos}\,[(r_{13}-r_{31})/(2\,{\rm s}\kappa)] \cr & \quad \zeta = 0 \,\,{\rm or}\,\, \zeta = \pi\colon\,\, \eta = 0 \cr & \quad 0 \,\lt\, \zeta \,\lt\, \pi\colon\,\, \eta = {\rm atan2}\,(r_{32}-r_{23}, r_{21}-r_{12}) \cr\cr& \kappa = \pi\colon\,\, \zeta = \textstyle{1 \over 2}\,{\rm arccos}\,(r_{22}) \cr & \quad \zeta = 0\colon\,\, \eta = 0 \cr & \quad \zeta = \pi/2\colon\,\, \eta = \textstyle{1 \over 2}\,{\rm atan2}\,(r_{31}+r_{13}, 2r_{33}) \cr & \quad 0 \,\lt\, \zeta \,\lt\, \pi/2\colon\,\, \eta = {\rm atan2}\,(r_{12}+r_{21}, r_{32}+r_{23})}]$

All of this information is classic and most of it can be found in the literature. However it is much dispersed between different sources and the notations used are very different, sometimes opposite to each other and confusing. For this reason we have tried to produce a single document presenting this variety of options in a consistent, complete and detailed way.

3. Method

3.1. Two basic options to describe rotations

Let an object be defined in some Cartesian coordinate system with unit and mutually orthogonal basis vectors e_x, e_y, e_z (orthonormal basis), making a right-hand frame (called also right-handed or right-chiral), and with the origin at O, the point around which the object is rotated. In crystallography, the default choice of the basis vectors, also referred to as coordinate axes, is defined by one of the orthogonalization agreements (Appendix D).

Euler (1776) showed that any rotation, i.e. a motion with one immobile point, O in our case, may be represented as a single rotation about some axis in a general position. Alternatively, it can be represented by rotations about particular coordinate axes, but this requires three such consecutive elemental rotations. The Cartesian coordinates of a point after rotation are expressed through its coordinates before rotation (both described in the same basis {O, e_x, e_y, e_z}) by three linear equations that can be represented in matrix form. Note that this rotation matrix R is the same for all points of the object and is unique for each rotation.

3.2. Three consecutive rotations about the coordinate axes

3.2.1. Euler angles and rotation axes

Let us consider three consecutive rotations about coordinate axes axis1, axis2, axis3 by angles κ₁, κ₂, κ₃, respectively; these angles are known as Euler angles. The order in which the rotations are applied is crucial. While in the literature one can find alternative notations for these angles (α, β, γ or ϕ, θ, ψ or other), our notation has the advantage of showing explicitly the order of rotations: first by κ₁ about axis1, then by κ₂ about axis2, then by κ₃ about axis3, whatever the axes are. Let us denote the respective rotation matrices by R_axis1(κ₁), R_axis2(κ₂) and R_axis3(κ₃); particular expressions of matrices for rotations about e_x, e_y, e_z are given in Appendix B.

If the three rotation axes are selected from the set e_x, e_y, e_z we are talking about `extrinsic rotations' or `active rotations'; for simplicity we denote the corresponding choice by x, y or z, respectively. Two consecutive rotations cannot be about the same axis, but the first and the third axes can be the same (referred to as proper Euler angles; when all three axes are different, the corresponding angles are also called Tait–Bryan angles). For example, xyz and zyz are acceptable, but not yyz. The overall rotation matrix is a product of matrices from right to left (Appendix A):

$[ R = R_{{\rm axis3}} (\kappa_3) \, R_{{\rm axis2}} (\kappa_2) \, R_{{\rm axis1}}(\kappa_1). \eqno (1)]$

For example, for axis1 = x, axis2 = y, axis3 = z the matrix (1) is R_z(κ₃)R_y(κ₂)R_x(κ₁).

Often axis1, axis2, axis3 correspond to a different, mobile coordinate system. Initially its basis vectors u_x, u_y, u_z coincide with the respective vectors e_x, e_y, e_z. However, they are associated with the rotating object and move with it. In this case we are talking about `intrinsic rotations' or `passive rotations'. Referring to the same three basic matrices as above, the rotation matrix becomes their product from left to right (Appendix B):

$[R = R_{{\rm axis1}} (\kappa_1) \, R_{{\rm axis2}} (\kappa_2) \, R_{{\rm axis3}}(\kappa_3). \eqno (2)]$

3.2.2. Direction of the rotations

The elemental matrices R_x(κ), R_y(κ), R_z(κ) given in Appendix B correspond to rotations in the trigonometrical sense, i.e. counterclockwise when looking against the rotation axis [Fig. 1(a)]. Working in three-dimensional space, the term `right-hand rotation' is frequently used. While this is the default direction in mathematics and physics, one may define a positive rotation direction in the opposite sense, i.e. clockwise when looking against the rotation axis (left-hand rotation). This does not change the form of the rotation matrix but simply reverses the sign of its argument. (This is equivalent to inversion of the corresponding matrix.) For example, inversion of the rotation direction for all three extrinsic rotations [equation (1)] simultaneously makes matrix R equal to

$[R = R_{{\rm axis3}} (-\kappa_3) \, R_{{\rm axis2}} (-\kappa_2) \, R_{{\rm axis1}}(-\kappa_1). \eqno (3)]$

For intrinsic rotations [equation (2)] it becomes

$[R = R_{{\rm axis1}} (-\kappa_1) \, R_{{\rm axis2}} (-\kappa_2) \, R_{{\rm axis3}}(-\kappa_3). \eqno (4)]$

Figure 1
Rotation axis l (in red). (a) Definition of the positive (trigonometric, right hand) direction of rotation. (b) Definition of the rotation axes by direction cosines. (c) Definition of the rotation axis by polar coordinates. (d) Example of a standard (h = e_x, n = e_y) and alternative (h′ = e_y, n′ = −e_x) choice for the azimuth axis.

3.2.3. System or object rotation

Owing to the relative character of a motion, rotation of an object with respect to a given basis may also be seen as a rotation of this basis keeping the object fixed. Such rotation automatically means that the coordinate axes (of the system) are moving ones.

In this case, three consecutive rotations of the basis about its axes axis1, axis2, axis3 by angles κ₁, κ₂, κ₃ result in the rotation matrix (Appendix B)

$[R = R_{{\rm axis3}} (-\kappa_3) \, R_{{\rm axis2}} (-\kappa_2) \, R_{{\rm axis1}}(-\kappa_1), \eqno (5)]$

coinciding with expression (3) above.

3.3. Single rotation about an axis in a general orientation

3.3.1. Direction cosines and quaternions

Now let us consider a single rotation of an object by some angle κ about an axis in a general orientation. This rotation axis can be defined by a unit vector l along it. Vector l can be represented by its Cartesian coordinates (l_x, l_y, l_z) in the same orthonormal basis {O, e_x, e_y, e_z} as above. These coordinates are cosines of the angles that l makes with the coordinate axes e_x, e_y, e_z [Fig. 1(b)]. Table 1 shows the corresponding rotation matrix.

A close description is that by quaternions. Here, the coordinates of the rotation axis are `merged' with the rotation angle, giving a set of four quaternion parameters {q₀, q_x, q_y, q_z} that are {cos(κ/2), l_xsin(κ/2), l_ysin(κ/2), l_zsin(κ/2)}. These quartets have a number of important mathematical features and are convenient for formal mathematical manipulations. The corresponding rotation matrix is also given in Table 1.

3.3.2. Polar angles and rotation axes

The normalization condition l_x² + l_y² + l_z² = 1 on vector l indicates that the parameters of direction cosines are mutually dependent; the same is true for quaternions. Instead of these parameters, one can define l by its spherical coordinates. Here one angle describes the inclination of l, i.e. the angle that the vector l makes with a chosen coordinate axis, called the `zenith' or `polar' axis and which we denote by p. By definition this angle varies from 0 to π. The plane normal to p contains two other vectors of the Cartesian basis. One of them is chosen as the `azimuth' or `horizontal' axis, and we denote it by h. Vectors p and h are completed by the third unit vector n (for normal), making a right-hand orthogonal frame phn (Appendix C).

The angle that the orthogonal projection of l into the plane hOn makes with the azimuth axis h is the second angle defining the orientation of the rotation axis. This angle is considered in the trigonometric sense looking against p. The two angles introduced above fully define the orientation of the rotation axis l [Fig. 1(c)]. We call these two angles the `zenith angle', ζ, and the `azimuth angle', η, reserving the term `polar angles' for the ensemble of three angles (ζ, η, κ) as routinely used in macromolecular crystallography. (Some sources reserve the term `polar angle' only for a rotation in a plane.) For ζ = 0 and for ζ = π the azimuth angle η is undefined and we arbitrarily assign η = 0. With this choice, the rotation matrix can be expressed as a product of the elemental matrices (Appendix C):

$[R = R_{{ p}} (\eta) \, R_{n} (\zeta) \, R_{{ p}}(\kappa) R_{{ n}} (-\zeta) R_{{ p}}(-\eta). \eqno (6)]$

All rotations in equation (6) are considered in the trigonometrical sense.

3.3.3. Rotation direction and system rotation

Both inversion of the rotation direction and consideration of the basis rotating about a fixed object result in inversion of the sign of the argument of the central matrix in (6), i.e. replacing R_p(κ) by R_p(−κ), and keeping the rest.

3.4. Conversion of rotation matrices into parameters

Previous sections have shown how to obtain the rotation matrix from different kinds of rotation parameters. Conversely, given the rotation matrix, one may wish to recover the independent rotation parameters of one's choice. Tables 1–3 provide the corresponding expressions considering a fixed system and the object rotated about fixed axes in the trigonometric sense. For alternative conventions, the final assignment is done according to the remark in §3.3.3 or by comparison of equation (1) with the respective expressions (2)–(5). These tables show that the extraction of the rotation parameters from the rotation matrix can always be done unambiguously, except for the equivalent solution. Several remarks have to be made.

First, the expressions for parameters are different for general and for some particular situations, e.g. those when κ = π for polar angles or when κ₂ = 0 for proper Euler angles etc. For these situations, usually the value of one of the parameters is assigned arbitrarily. Second, in practice these particular situations are identified with some precision and it is crucial to keep rounding errors as small as possible. Third, each solution has its equivalent; the reason for this is that each rotation can be considered also as a rotation by the complementary (or opposite) angle about the axis directed in the opposite way, i.e. inverting the vector l.

Finally, a cyclic permutation of rotation axes in the definition of the Euler or polar angles results in a cyclic permutation of rows and columns of the rotation matrices (Tables 2 and 3). In turn, this corresponds to a cyclic permutation of indices of the matrix elements in the expressions for Euler or polar angles extracted from the rotation matrix.

4. Program

4.1. Overall structure

The program core is represented by 12 modules corresponding to all possible independent assignments of rotation axes for Euler angles [see, for example, Kuipers (1999 ) or https://www.mecademic.com/resources/Euler-angles/Euler-angles] and by three modules for all possible standard choices of the zenith and azimuth axes. Each of these modules contains the part that interprets the matrices in terms of the relevant Euler or polar angles. In fact, only three modules for R_x(κ), R_y(κ) and R_z(κ) are sufficient to calculate any rotation matrix by combining them appropriately, but the interpretation of the matrix in terms of parameters would be less straightforward. There exists also a module for matrix calculation and interpretation in terms of direction cosines.

The program calls the appropriate module according to the particular choice of parameters made by the user. If necessary, the angle values are adjusted internally, for example are taken in the inverse order, taken with the inverse signs (Appendices B and C) or increased by π/2 for a nonstandard choice of azimuth axis (Appendix C). A corresponding adjustment is required when extracting the parameters from the matrix.

The program has a module to generate the parameters corresponding to symmetrically equivalent orientations for a selected space group given the rotation matrix defining the principal position of the rotated object. The orthogonalization and deorthogonalization module is included for use of the program in a crystallographic environment. Finally, there is a module to apply the rotation matrix (and the translation vector) to a list of atomic coordinates. Note that the respective anisotropic atomic displacement parameters and the TLS parameters (Schomaker & Trueblood, 1968 ) are not recalculated (Kronenburg, 2004 ).

4.2. Protocol

The program can be used in a crystallographic environment but not necessarily. The choice of a crystallographic environment means that either crystallographic symmetries will be used or the rotation elements (e.g. the polar axis) will be defined with respect to the crystallographic axes. In this optional case the user needs to first select the orthogonalization conventions; they may be different for the input and output parameters. Then, independently of this step, the user needs to choose the particular sets of the input and output rotation parameters. In a simplified mode of conversion from one known program to another, the settings above can be done automatically by selecting the program names in the list. This list is very short in comparison with that given by Urzhumtseva & Urzhumtsev (1997). One reason is that many programs have become obsolete since 1997. The second reason is that we wanted to avoid an eventual disagreement between the formal program descriptions, available comments on the choice of parameters and the actual program source.

The values of the chosen input parameters can be either entered directly by typing them or using copy/paste options or using Demo, or provided by indicating the file containing such values. The last option is convenient when converting lists of parameters, e.g. Euler angles after a molecular replacement run. The recalculation of the parameters can be followed by recalculation of coordinates; input and output files with lists of atomic coordinates and an eventual model shift have to be defined.

Any choice of the rotation parameters can be illustrated by Demo; this can be done separately for the input and output parameter selection. For input parameters, Demo is interactive; the user can vary parameter values and observe respective changes in the axes and object positions. At any time, Help is available, explaining the rotation matrices and their interpretation in terms of angles, as well as illustrating the orthogonalization conventions.

Fig. 2 shows an example of a py_convrot session.

Figure 2
py_convrot session. The principal window (top), two snapshots of the interactive Demo (lower left) and an example of a Help page (lower right).

5. Software environment and program distribution

The GUI program py_convrot is written in Python 2 and requires version 2.6 or 2.7 and the wxPython toolkit. py_convrot has been tested under Windows, Linux and MacOS systems. If the Python libraries are installed in the frame of other program packages such as PHENIX (Adams et al., 2010), the program may be started as

phenix.wxpython py_convrot.py

The program can be downloaded from the site https://www-ibmc.u-strasbg.fr/spip-arn/spip.php?rubrique2&lang = en. It is also available on request from the authors. A Python 3 version is under development.

6. Conclusions

Description of rotations in space is an old task widely addressed in the literature. The algebraic simplicity of its solution allows developers to select and adapt the description that is most appropriate to their particular project. At the same time, the variety of possible descriptions causes a lot of confusion. The present article and associated teaching program py_convrot, addressed to researchers working in crystallography, cryoEM or similar fields, are an attempt to review these descriptions and relate them to each other.

APPENDIX A

Rotation matrices in Cartesian coordinate systems

Let an object be defined in some Cartesian coordinate system with basis vectors e_x, e_y, e_z (right-hand orthonormal basis) and the origin around which the object is rotated at O. Let u_x, u_y, u_z be three other unit vectors, rigidly associated with the rotated object and such that for the initial position of the object they coincide with e_x, e_y, e_z, respectively. After rotation, these vectors can be expressed in the basis {O, e_x, e_y, e_z} as

$[\eqalign{& {\bf u}^\prime_x = r_{11}{\bf e}_x + r_{21}{\bf e}_y + r_{31}{\bf e}_z ,\quad {\bf u}^\prime_y = r_{12}{\bf e}_x + r_{22}{\bf e}_y + r_{32}{\bf e}_z, \cr & {\bf u}^\prime_z = r_{13}{\bf e}_x + r_{23}{\bf e}_y + r_{33}{\bf e}_z. }\eqno (7)]$

If we compose a matrix R with these coordinates in columns as

$[R = \left({\matrix{ {{r_{11}}} & {{r_{12}}} & {{r_{13}}} \cr {{r_{21}}} & {{r_{22}}} & {{r_{23}}} \cr {{r_{31}}} & {{r_{32}}} & {{r_{33}}} \cr } } \right) \eqno (8)]$

then the coordinates $[({x_e',y_e',z_e'} )]$ of any point of the object after its rotation are related to its coordinates (x_e, y_e, z_e) in the initial position by

$[\left({\matrix{ {x_e^\prime} \cr {y_e^\prime} \cr {z_e^\prime} \cr } } \right) = R\left({\matrix{ {{x_e}} \cr {{y_e}} \cr {{z_e}} \cr } } \right) .\eqno (9)]$

The rotation matrix R, called also the matrix of the rotation operator, is the same for all points. As a consequence, it can be considered as the reference entity for any kind of parameterization of the rotation. We should distinguish between equation (9) and the equations that relate the coordinates of a fixed point in the initial basis and in the rotated basis, (x_u, y_u, z_u), namely²

$[\left(\matrix{{x}_{u}\cr {y}_{u}\cr {z}_{u}}\right) = {R}^{-1}\left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right) \quad {\rm and}\quad \left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right) = R\left(\matrix{{x}_{u}\cr {y}_{u}\cr {z}_{u}}\right). \eqno (10)]$

It follows from equation (9) that two consecutive rotations, first by R₁ and then by R₂, are equivalent to a rotation described by the matrix R = R₂R₁ with the matrices taken from right to left (all matrices are in the same Cartesian basis):

$[\left(\matrix{{x}_{e}^{\prime \prime}\cr {y}_{e}^{\prime\prime}\cr {z}_{e}^{\prime\prime }}\right) = {R}_{2}\left(\matrix{{x}_{e}^{\prime}\cr {y}_{e}^{\prime}\cr {z}_{e}^{\prime}}\right) = {R}_{2}\left[{R}_{1}\left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right)\right] = \left({{R}_{2}R}_{1}\right)\left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right). \eqno (11)]$

APPENDIX B

Euler angles

B1. Extrinsic rotations (fixed coordinate axes)

As shown by Euler (1776), a rigid-body rotation can be described by three consecutive rotations about the coordinate axes axis1, axis2, axis3 by angles κ₁, κ₂, κ₃, respectively. In the case of extrinsic rotations (rotations about fixed coordinate axes), axis1, axis2, axis3 are selected from e_x, e_y, e_z. The same axis cannot be taken for two consecutive elemental rotations.

For elemental rotations by angle κ about axes e_x, e_y or e_z the corresponding rotation matrices [equation (8)] are

$[\eqalign{ & {R}_{x}\left(\kappa \right) = \left(\matrix{1& 0& 0\cr 0& \cos\kappa & -\sin\kappa \cr 0& \sin\kappa & \cos\kappa }\right), \cr & {R}_{y}\left(\kappa \right) = \left(\matrix{\cos\kappa & 0& \sin\kappa \cr 0& 1& 0\cr -\sin\kappa & 0& \cos\kappa }\right), \cr & {R}_{z}\left(\kappa \right) = \left(\matrix{\cos\kappa & -\sin\kappa & 0 \cr \sin\kappa & \cos\kappa & 0 \cr 0& 0& 1}\right). } \eqno (12)]$

Here each rotation is considered in its trigonometrical sense, i.e. counterclockwise when looking against the rotation axis [Fig. 1(a)]. According to equation (11) the total rotation matrix is calculated as a product [equation (1)] of the individual matrices.

B2. Intrinsic rotations (moving coordinate axes)

Alternatively, axis1, axis2, axis3 may be the axes of a coordinate system rigidly associated with the rotating object and moving with it. This is an intrinsic rotation. We denote this rotating basis u_x, u_y, u_z by U, distinguishing it from the original immobile basis e_x, e_y, e_z which we denote by E. The immobile point O is the origin for both of them. Note that for both extrinsic and intrinsic rotations, ultimately, we are interested in the coordinates of a point with respect to the initial, fixed coordinate system {O, e_x, e_y, e_z}, while {O, u_x, u_y, u_z} is simply an intermediate tool to describe the rotation.

Let R₁ correspond to a rotation of the object, together with the basis U, from its initial position. For any point of a rotating object, its coordinates in U do not change and are the same as initially in basis E: (x_u,y_u,z_u ) = (x_e,y_e,z_e ). If R₂ is the matrix describing a following rotation with respect to the rotated basis U,

$[\left(\matrix{{x}_{u}^{\prime}\cr {y}_{u}^{\prime}\cr {z}_{u}^{\prime}}\right) = {R}_{2}\left(\matrix{{x}_{u}\cr {y}_{u}\cr {z}_{u}}\right), \eqno (13)]$

the coordinates of the rotated point in E, according to equation (10), become

$[\eqalignno{ \left(\matrix{{x}_{e}^{\prime}\cr {y}_{e}^{\prime}\cr {z}_{e}^{\prime}}\right)& = {R}_{1} \left(\matrix{{x}_{u}^{\prime}\cr {y}_{u}^{\prime}\cr {z}_{u}^{\prime}}\right) = {R}_{1}\left[{R}_{2}\left(\matrix{{x}_{u}\cr {y}_{u}\cr {z}_{u}}\right)\right] = {R}_{1}\left[{R}_{2}\left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right)\right] \cr & = \left({{R}_{1}R}_{2}\right)\left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right) .& (14)}]$

In other words, for intrinsic rotations the matrix product is calculated in the reverse order to that for extrinsic ones: matrices are taken from left to right. Generalizing this, the matrix to calculate Cartesian coordinates after three consecutive rotations about moving axes axis1, axis2, axis3 is equation (2).

B3. Extrinsic versus intrinsic conventions

Table 2 shows the resulting matrix [equation (8)] for rotations about all possible triplets of fixed axes. A direct comparison of formula (2) with (1) shows that each extrinsic rotation can be easily interpreted as an intrinsic rotation and vice versa. In other words, each rotation matrix can be interpreted in terms of both conventions.

The convention most frequently used in the past few decades in macromolecular crystallography (e.g. Collaborative Computational Project, Number 4, 1994) is that described by the matrix

$[R = R_{{ z}}(\kappa_1) R_{{ y}}(\kappa_2) R_{{ z}}(\kappa_3). \eqno (15)]$

It can be interpreted³ as an intrinsic rotation zyz (moving, mobile axes) about axis1 = u_z, axis2 = u_y, axis3 = u_z by angles κ₁, κ₂, κ₃, respectively. This is equivalent to the consecutive rotations about the fixed axes (extrinsic rotations) axis1 = e_z, axis2 = e_y, axis3 = e_z by angles κ₃, κ₂, κ₁. Note that, similarly to other proper Euler angles, this convention is not optimal for rigid-body refinement since in that case the original orientation corresponding to κ₂ = 0 is singular, defining the sum κ₁ + κ₃ and not each of these angles individually (Urzhumtsev et al., 1989 ; Afonine et al., 2009 ).

B4. Other rotation conventions

Inversion of the rotation direction corresponds to taking the opposite sign for the corresponding rotation angle in equation (1) or (2). In general, for two angles from the same triplet of Euler angles, opposite directions can be considered as positive, e.g. https://spider.wadsworth.org/spider_doc/spider/docs/euler.html.

Rotating a system (basis) about the fixed object is opposite to an equivalent rotation of the object with respect to a fixed basis. Three consecutive rotations of the basis about the axes axis1, axis2, axis3 (which by construction are moving axes) by angles α₁, α₂, α₃ are described by matrix (2). However, since an opposite rotation is described by the inverse matrix, matrix (8) to recalculate the Cartesian coordinates of a fixed point with respect to the rotated basis, which is the final goal, becomes

$[\eqalignno { R & = {\left [{{R_{{\rm{axis}}1}}\left({{\kappa _1}} \right){R_{{\rm{axis}}2}}\left({{\kappa _2}} \right){R_{{\rm{axis}}3}}\left({{\kappa _3}} \right)} \right]^{ - 1}} \cr & = R_{{\rm{axis}}3}^{ - 1}\left({{\kappa _3}} \right)R_{{\rm{axis}}2}^{ - 1}\left({{\kappa _2}} \right)R_{{\rm{axis}}1}^{ - 1}\left({{\kappa _1}} \right) \cr & = {R}_{\rm axis3}\left(-{\kappa }_{3}\right){R}_{\rm axis2}\left(-{\kappa }_{2}\right){R}_{\rm axis1}\left({-\kappa }_{1}\right).&(16) }]$

APPENDIX C

Polar angles

C1. Definition of the axis direction

If we characterize a rotation in three-dimensional space by a matrix R, a unit vector l along the rotation axis is its eigenvector corresponding to its eigenvalue equal to 1. Such an eigenvalue always exists and is unique except for the degenerate rotation by 0 radians; this value is characteristic for a rotation. (The two other eigenvalues either are complex conjugates of modulus 1 in a general case or are both equal to 1 for a rotation by 0, or are both equal to −1 for a rotation by π radians.) Two independent parameters are required to define l. Frequently, they are chosen as two angles that refer to an orthonormal basis:

(a) The zenith angle ζ that l makes with a chosen basis vector p that we call the polar or zenith axis; for example, but not necessarily (e.g. Rossmann & Blow, 1962 ), p = e_z.

(b) The azimuth angle η that the orthogonal projection of l into the plane normal to p makes with one of two basis vectors that belong to this plane; we call this basis vector the azimuth axis, h.

It is more convenient to choose h so that p, h and the third basis vector, n, and not its opposite, form a right-hand frame (this means that n = p × h). For example, for p = e_z, this imposes h = e_x, resulting in n = e_y. With such a convention, the three basic possible choices for p and h are (e_z, e_x), (e_x, e_y), (e_y, e_z). In the literature, the term `polar angle' is reserved sometimes for the first, inclination angle, and sometimes for the second angle, especially when working in plane. Also one may find multiple notations for these angles, including some that are opposite to each other, e.g. (θ, ϕ) and (ϕ, θ). For these reasons we here use ζ (for `zenith') and η (for `azimuth'), differently from common notations, to avoid any confusion and showing explicitly which angle is for which axis. We use the term `polar angles' for the set (ζ, η, κ), where κ is the angle of rotation about l. Recall that the rotation angle κ is related to the trace of the rotation matrix by expression

$[2 \cos \kappa + 1 = {\rm tr}\, R = r_{11} + r_{22} + r_{33}. \eqno (17)]$

C2. Rotation about an axis in a general orientation

To find the matrix describing the rotation by angle κ about axis l in a general orientation, a moving frame (basis) V is defined with the vectors v_h, v_n, v_p, which initially coincide with h, n, p. It is rotated first by η about v_p = p and then by ζ about v_n in its new position. This superposes v_p and l; the corresponding rotation matrix is

$[R_{{ pl}} = R_{{ p}}(\eta) R_{{ n}}(\zeta). \eqno (18)]$

According to equation (10), the coordinates of a given fixed point expressed in the rotated basis V are

$[\eqalignno{ \left(\matrix{{x}_{v}\cr {y}_{v}\cr {z}_{v}}\right) & = {R}_{{ p}{ l}}^{-1}\left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right) = {\left[{{R}_{{ p}}\left(\eta \right)R}_{{ n}}\left(\zeta \right)\right]}^{-1}\left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right) \cr & = {R}_{{ n}}\left(-\zeta \right){R}_{{ p}}\left(-\eta \right)\left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right) .& (19)}]$

Rotation by κ about v_p = p in the rotated basis is described by the product of the matrix R_p(κ) and vector (19), where R_p(κ) is one of the elemental matrices (12). Finally, and also according to (10), recalculating the resulting coordinates in the original coordinate system gives the total rotation matrix (8) in the form

$[\eqalignno{ R\left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right) & = {R}_{{ p}{ l}}{R}_{{ p}}\left(\kappa \right)\left(\matrix{{x}_{v}\cr {y}_{v}\cr {z}_{v}}\right) \cr & = {{R}_{{ p}}\left(\eta \right)R}_{{ n}}\left(\zeta \right){R}_{{ p}}\left(\kappa \right){R}_{{ n}}\left(-\zeta \right){R}_{{ p}}\left(-\eta \right)\left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right). & (20)}]$

C3. Nonstandard choice for the azimuth axis

Table 3 shows the rotation matrices for all three possible standard choices for the zenith and azimuth axes. However, for the same axis p one may choose axis h coinciding with a different coordinate axis; in other words, the new azimuth and normal axes, h′ and n′, may correspond to n and −h from the previous, standard choice. One may reduce such a situation to the previous one since the angles (ζ′, η′) for a non-conventional choice are equivalent to the angles (ζ, η + π/2) defined for the standard choice [Fig. 1(d)]. The program py_convrot uses this approach even when other considerations are possible.

APPENDIX D

Orthogonalization conventions and their relation to rotations

In crystallography, three kinds of basis are used and are involved in the definition of the rotation matrices in a crystallographic environment [see for example Shmueli (2010 ) or Rupp (2010)]. First, crystallographic (fractional) coordinates are defined, representing each point (vector) r in a right-hand basis composed of vectors defining the crystal periods a, b, c:

$[{\bf r} = x_{\rm f} {\bf a} + y_{\rm f} {\bf b} + z_{\rm f} {\bf c}. \eqno (21)]$

Generally speaking, these basis vectors are not unit vectors and are not mutually orthogonal. The mixed product

$[V = ({\bf a}\times {\bf b})\cdot {\bf c} \eqno (22)]$

is the volume of the unit cell formed by the basis vectors. The second basis, dual to the previous one, is composed of the vectors

$[{\bf a}^\ast = V^{-1} {\bf b} \times {\bf c}, \quad {\bf b}^\ast = V^{-1} {\bf c} \times {\bf a}, \quad{\bf c}^\ast = V^{-1} {\bf a} \times {\bf b}. \eqno (23)]$

The third is a Cartesian orthonormal basis {O, e_x, e_y, e_z} with respect to which the rotation parameters are chosen. It is defined by one of the standard conventions (Collaborative Computational Project, Number 4, 1994) through a, b, c and a*, b*, c* [see for example Giacovazzo et al. (1992) or Rupp (2010)]. The crystallographic [equation (21)] and Cartesian coordinates

$[{\bf r} = x_e {\bf e}_x + y_e {\bf e}_y + z_e {\bf e}_z \eqno (24)]$

are related to each other by two mutually inverse matrices, orthogonalization matrix B and deorthogonalization matrix A = B⁻¹:

$[\left(\matrix{{x}_{\rm f}\cr {y}_{\rm f}\cr {z}_{\rm f}}\right) = A\left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right),\quad \left(\matrix{{x}_{e}\cr {y}_{e}\cr {z}_{e}}\right) = B\left(\matrix{{x}_{\rm f}\cr {y}_{\rm f}\cr {z}_{\rm f}}\right). \eqno (25)]$

Table 4 summarizes the expressions for matrices A and B for different conventions. Changing the orthogonalization choice changes the rotation matrix according to

$[A_{\rm in}R_{\rm in}B_{\rm in} = A_{\rm out}R_{\rm out}B_{\rm out} .\eqno (26)]$

Here both left-hand and right-hand parts of the equation present the rotation matrix in the crystallographic basis.

Table 4
Orthogonalization conventions

a, b, c, α, β, γ are cell parameters; α*, β*, γ* are angles between the vectors of the dual basis calculated as α* = arccos[(cosβcosγ − cosα)/(sinβsinγ)], β* = arccos[(cosγcosα − cosβ)/(sinγsinα)], γ* = arccos[(cosαcosβ − cosγ)/(sinαsinβ)]. For the fourth orthogonalization convention, a′ = ||a + b|| = (a² + b² + 2abcosγ)^1/2, β′ = arccos[(acosβ + bcosα)/a′], γ′ = arccos[(acosγ + b)/a′], cosβ′* = (cosγ′cosα − cosβ′)/(sinγ′sinα).

e_x, e_y, e_z along vectors	Orthogonalization matrix B	Deorthogonalization matrix A
$[\eqalign{ & {\bf a} \cr & {\bf c}^* \times {\bf a} \cr& {\bf c}^*}]$	$[\left(\matrix{ a & b\cos \gamma & c\cos\beta \cr 0 & b\sin\gamma & -c\sin\beta\cos\alpha^* \cr 0 & 0 & c\sin\beta\sin\alpha^*}\right)]$	$[\left[\matrix{ 1/a & -1/(a\tan\gamma) & \sin\alpha\cos\beta^/(a\sin\beta\sin\gamma\sin\alpha^) \cr 0 & 1/(b\sin\gamma) & 1/(b\sin\gamma\tan\alpha^) \cr 0 & 0 & 1/(c\sin\beta\sin\alpha^)}\right]]$
$[\eqalign{ &{\bf b} \cr & {\bf a}^* \times {\bf b}\cr & {\bf a}^*}]$	$[\left(\matrix{a\cos\gamma & b & c\cos\alpha \cr -a\sin\gamma\cos\beta^* & 0 & c\sin\alpha \cr a\sin\gamma\sin\beta^* & 0 & 0}\right)]$	$[\left[\matrix{0 & 0 & 1/(a\sin\gamma\sin\beta^) \cr 1/b & -1/(b\tan\alpha) & \sin\beta\cos\gamma^/(b\sin\alpha\sin\gamma\sin\beta^) \cr 0& 1/(c\sin\alpha) & 1/(c\sin\alpha\tan\beta^)}\right]]$
$[\eqalign{&{\bf c}\cr & {\bf b}^* \times {\bf c} \cr & {\bf b}^*}]$	$[\left(\matrix{ a\cos\beta & b\cos\alpha & c \cr a\sin\beta & -b\sin\alpha\cos\gamma^* & 0 \cr 0 & b\sin\alpha\sin\gamma^* & 0}\right)]$	$[\left[\matrix{0 &1/(a\sin\beta) & 1/(a\sin\beta\tan\gamma^) \cr 0 & 0 & 1/(b\sin\alpha\sin\gamma^) \cr 1/c & -1/(c\tan\beta) & \sin\gamma\cos\alpha^/(c\sin\alpha\sin\beta\sin\gamma^)}\right]]$
$[\eqalign{& ({\bf a}+{\bf b}) \cr & {\bf c}^* \times ({\bf a}+{\bf b}) \cr & {\bf c}^*}]$	$[\left(\matrix{a' & b\cos\gamma & c\cos\beta' \cr 0 & b\sin\gamma & -c\sin\beta'\cos\alpha^* \cr 0 & 0 & c\sin\beta'\sin\alpha^*}\right)]$	$[\left[\matrix{1/a' & -1/(a'\tan\gamma') &\sin\alpha\cos\beta'^/(a'\sin\beta'\sin\gamma'\sin\alpha^) \cr 0 & 1/(b\sin\gamma') & 1/(b\sin\gamma'\tan\alpha^) \cr 0 & 0 & 1/(c\sin\beta'\sin\alpha^)}\right]]$
$[\eqalign{&{\bf a}^* \cr & {\bf c} \times {\bf a}^* \cr & {\bf c}}]$	$[\left(\matrix{ a\sin\beta\sin\gamma^* & 0 & 0 \cr -a\sin\beta\cos\gamma^* & b\sin\alpha & 0 \cr a\cos\beta & b\cos\alpha & c}\right)]$	$[\left[\matrix{1/(a\sin\beta\sin\gamma^) & 0 & 0 \cr 1/(b\sin\alpha\tan\gamma^) & 1/(b\sin\alpha) & 0 \cr \sin\gamma\cos\beta^/(c\sin\alpha\sin\beta\sin\gamma^) & -1/(c\tan\alpha) & 1/c}\right]]$
$[\eqalign{&{\bf a}\cr & {\bf b}^* \cr & {\bf a} \times {\bf b}^*}]$	$[\left(\matrix{a & b\cos\gamma & c\cos\beta \cr 0 & b\sin\gamma\sin\alpha^* & 0 \cr 0 & -b\sin\gamma\cos\alpha^* & c\sin\beta}\right)]$	$[\left[\matrix{1/a & \sin\alpha\cos\gamma^/(a\sin\beta\sin\gamma\sin\alpha^) & -1/(a\tan\beta) \cr 0& 1/(b\sin\gamma\sin\alpha^) & 0 \cr 0 & 1/(c\sin\beta\tan\alpha^) & 1/(c\sin\beta)}\right]]$
$[\eqalign{& {\bf a}^* \cr & {\bf b}\cr & {\bf a}^* \times {\bf b}}]$	$[\left(\matrix{a\sin\gamma\sin\beta^* & 0 & 0 \cr a\cos\gamma & b & c\cos\alpha \cr -a\sin\gamma\cos\beta^* & 0 & c\sin\alpha}\right)]$	$[\left[\matrix{1/(a\sin\gamma\sin\beta^) & 0 & 0 \cr \sin\beta\cos\gamma^/(b\sin\alpha\sin\gamma\sin\beta^) & 1/b & -1/(b\tan\alpha) \cr 1/(c\sin\alpha\tan\beta^) & 0 & 1/(c\sin\alpha)}\right]]$

While rotations in Euler or in polar angles are defined with respect to a Cartesian basis, crystallographic transformations are naturally defined in crystallographic coordinates. For example, let a rotation described by matrix R_in in some input Cartesian basis be followed by a symmetry rotation S. According to equation (26), the matrix for the resulting rotation expressed in another, output Cartesian basis is equal to

$[{R}_{\rm out} = {A}_{\rm out}^{-1}S\left({A}_{\rm in}{R}_{\rm in}{B}_{\rm in}\right){B}_{\rm out}^{-1} = {B}_{\rm out}S\left({A}_{\rm in}{R}_{\rm in}{B}_{\rm in}\right){A}_{\rm out}. \eqno (27)]$

Footnotes

¹The term `polar angles', widely used in crystallography and especially in macromolecular crystallography, sometimes is considered as formally inappropriate; see discussion in §3.3 and in Appendix C.

²In an orthonormal basis, the inverse matrix coincides with the transposed one, R^{- 1} = R^*.

³See comments in https://www.ccp4.ac.uk/html/rotationmatrices.html#eulerian_angles, which show once more the usefulness of the matrix as a reference object to describe rotations and to avoid confusion.

Acknowledgements

The authors thank D. Tronrud, D. Kostrewa, O. Sobolev, V. Y. Lunin, R. Read and A. Brünger for useful comments and A. McEwen for his help with improving the manuscript. AU acknowledges the support and the use of resources of the French Infrastructure for Integrated Structural Biology FRISBI ANR-10-INBS-05, and of Instruct-ERIC.

References

Adams, P. D., Afonine, P. V., Bunkóczi, G., Chen, V. B., Davis, I. W., Echols, N., Headd, J. J., Hung, L.-W., Kapral, G. J., Grosse-Kunstleve, R. W., McCoy, A. J., Moriarty, N. W., Oeffner, R., Read, R. J., Richardson, D. C., Richardson, J. S., Terwilliger, T. C. & Zwart, P. H. (2010). Acta Cryst. D66, 213–221. Web of Science CrossRef CAS IUCr Journals Google Scholar
Afonine, P. V., Grosse-Kunstleve, R. W., Urzhumtsev, A. & Adams, P. D. (2009). J. Appl. Cryst. 42, 607–615. Web of Science CrossRef CAS IUCr Journals Google Scholar
Bigras, P. & Bonev, I. (2012). Simulation des Angles d'Euler, https://cours.etsmtl.ca/gpa546/Applets/Orient3D.html. Google Scholar
Brünger, A. T., Adams, P. D., Clore, G. M., DeLano, W. L., Gros, P., Grosse-Kunstleve, R. W., Jiang, J.-S., Kuszewski, J., Nilges, M., Pannu, N. S., Read, R. J., Rice, L. M., Simonson, T. & Warren, G. L. (1998). Acta Cryst. D54, 905–921. Web of Science CrossRef IUCr Journals Google Scholar
Collaborative Computational Project, Number 4 (1994). Acta Cryst. D50, 760–763. CrossRef IUCr Journals Google Scholar
DeLano, W. L. (2002). The pyMOL Molecular Graphics System. DeLano Scientific, San Carlos, CA, USA. Google Scholar
Diamond, R. & Cranswick, L. M. D. (2010). International Tables for Crystallography, Vol. B, Reciprocal Space, 2nd online ed., pp. 418–448. Chester: International Union of Crystallography. Google Scholar
Emsley, P., Lohkamp, B., Scott, W. G. & Cowtan, K. (2010). Acta Cryst. D66, 486–501. Web of Science CrossRef CAS IUCr Journals Google Scholar
Euler, L. (1776). Novi Comment. Acad. Sci. Imp. Petropol. 20, 189–207. Google Scholar
Gaschler, A. (2016). 3D Rotation Converter, https://www.andre-gaschler.com/rotationconverter/. Google Scholar
Giacovazzo, C., Monaco, H. L., Viterbo, D., Scordari, F., Gilli, G., Zanotti, G. & Catti, M. (1992). Findamentals of Crystallography. edited by G. Giacovazzo. Oxford University Press. Google Scholar
Goldstein, H. (1950). Classical Mechanics. Cambridge: Addison-Wesley. Google Scholar
Heymann, J. B., Chagoyen, M. & Belnap, D. M. (2005). J. Struct. Biol. 151, 196–207. Web of Science CrossRef PubMed Google Scholar
Heymann, J. B., Chagoyen, M. & Belnap, D. M. (2006). J. Struct. Biol. 153, 312. Web of Science CrossRef Google Scholar
Kronenburg, M. J. (2004). Acta Cryst. A60, 250–256. Web of Science CrossRef CAS IUCr Journals Google Scholar
Kuipers, J. B. (1999). Quaternions and Rotation Sequences – A Primer with Applications to Orbits, Aerospace, and Virtual Reality. Princeton University Press. Google Scholar
Lattman, E. E. (1972). Acta Cryst. B28, 1065–1068. CrossRef CAS IUCr Journals Web of Science Google Scholar
Morawiec, A. (2015). A Description of Pan v. 1.979, https://imim.pl/personal/adam.morawiec/A_Morawiec_Web_Page/Pan.pdf. Google Scholar
Rossmann, M. G. & Blow, D. M. (1962). Acta Cryst. 15, 24–31. CrossRef CAS IUCr Journals Web of Science Google Scholar
Rupp, B. (2010). Biomolecular Crystallography. Principles, Practice, and Application to Structural Biology. New York: Garland Science, Taylor & Francis Group. Google Scholar
Schomaker, V. & Trueblood, K. N. (1968). Acta Cryst. B24, 63–76. CrossRef CAS IUCr Journals Web of Science Google Scholar
Shmueli, U. (2010). International Tables for Crystallography, Vol. B, Reciprocal Space, 2nd online ed., pp. 2–9. Chester: International Union of Crystallography. Google Scholar
Tulloue, G. (2001). Coordonnées Sphériques, https://www.sciences.univ-nantes.fr/sites/genevieve_tulloue/Meca/Cinematique/coord_spheriques.php. Google Scholar
Urzhumtsev, A. G., Lunin, V. Yu. & Vernoslova, E. A. (1989). J. Appl. Cryst. 22, 500–506. CrossRef CAS Web of Science IUCr Journals Google Scholar
Urzhumtsev, A. & Urzhumtseva, L. (2002). Acta Cryst. D58, 2066–2075. Web of Science CrossRef CAS IUCr Journals Google Scholar
Urzhumtseva, L. M. & Urzhumtsev, A. G. (1997). J. Appl. Cryst. 30, 402–410. CrossRef CAS Web of Science IUCr Journals Google Scholar
Urzhumtseva, L. & Urzhumtsev, A. (2002). J. Appl. Cryst. 35, 644–647. Web of Science CrossRef CAS IUCr Journals Google Scholar

© International Union of Crystallography. Prior permission is not required to reproduce short quotations, tables and figures from this article, provided the original authors and source are cited. For more information, click here.

JOURNAL OF
APPLIED
CRYSTALLOGRAPHY

ISSN: 1600-5767

Volume 52| Part 4| August 2019| Pages 869-881

https://doi.org/10.1107/S1600576719007313

Format		BIBTeX
		EndNote
		RefMan
		Refer
		Medline
		CIF
		SGML
		Plain Text
		Text

Format		BIBTeX
		EndNote
		RefMan
		Refer
		Medline
		CIF
		SGML
		Plain Text
		Text

Search IUCr Journals		doi		Advanced search
Author		volume	page

teaching and education\(\def\hfill{\hskip 5em}\def\hfil{\hskip 3em}\def\eqno#1{\hfil {#1}}\)

py_convrot: rotation conventions, to understand and to apply

1. Introduction

2. Converter purpose

2.1. Conversion of rotation parameters

2.2. Teaching goals

3. Method

3.1. Two basic options to describe rotations

3.2. Three consecutive rotations about the coordinate axes

3.2.1. Euler angles and rotation axes

3.2.2. Direction of the rotations

3.2.3. System or object rotation

3.3. Single rotation about an axis in a general orientation

3.3.1. Direction cosines and quaternions

3.3.2. Polar angles and rotation axes

3.3.3. Rotation direction and system rotation

3.4. Conversion of rotation matrices into parameters

4. Program

4.1. Overall structure

4.2. Protocol

5. Software environment and program distribution

6. Conclusions

APPENDIX A

Rotation matrices in Cartesian coordinate systems

APPENDIX B

Euler angles

B1. Extrinsic rotations (fixed coordinate axes)

B2. Intrinsic rotations (moving coordinate axes)

B3. Extrinsic versus intrinsic conventions

B4. Other rotation conventions

APPENDIX C

Polar angles

C1. Definition of the axis direction

C2. Rotation about an axis in a general orientation

C3. Nonstandard choice for the azimuth axis

APPENDIX D

Orthogonalization conventions and their relation to rotations

Footnotes

Acknowledgements

References

teaching and education