# Rotation Matrices

## Definition of rotation matrices

- `rotmat.R1()` ... 3D rotation matrix for rotation about the 1-axis
- `rotmat.R2()` ... 3D rotation matrix for rotation about the 2-axis
- `rotmat.R3()` ... 3D rotation matrix for rotation about the 3-axis

## Conversion Routines

- `rotmat.rotmat2Euler()` ... Calculation of Euler angles
- `rotmat.rotmat2Fick()` ... Calculation of Fick angles
- `rotmat.rotmat2Helmholtz()` ... Calculation of Helmholtz angles

## Symbolic matrices

- `rotmat.R1_s()` ... symbolix matrix for rotation about the 1-axis
- `rotmat.R2_s()` ... symbolix matrix for rotation about the 2-axis
- `rotmat.R3_s()` ... symbolix matrix for rotation about the 3-axis

For example, you can e.g. generate a Fick-matrix, with

> R_Fick = R3_s() * R2_s() * R1_s()

## Details

Routines for working with rotation matrices

`rotmat.``R1`(psi)

  Rotation about the 1-axis. The argument is entered in degree.

  Parameters: | psi (rotation angle about the 1-axis [deg]) –
  Returns: | R1
  Return type: | rotation matrix, for rotation about the 1-axis

  Examples

      >>> rotmat.R1(45)
      array([[ 1.        ,  0.        ,  0.        ],
             [ 0.        ,  0.70710678, -0.70710678],
             [ 0.        ,  0.70710678,  0.70710678]])

`rotmat.``R1_s`()

  Symbolic rotation matrix about the 1-axis, by an angle psi

  Returns: | R1_s
  Return type: | symbolic matrix for rotation about 1-axis

  Examples

      >>> R_Fick = R3_s() * R2_s() * R1_s()

`rotmat.``R2`(phi)

  Rotation about the 2-axis. The argument is entered in degree.

  Parameters: | phi (rotation angle about the 2-axis [deg]) –
  Returns: | R2
  Return type: | rotation matrix, for rotation about the 2-axis

  Examples

      >>> thLib.rotmat.R2(45)
      array([[ 0.70710678,  0.        ,  0.70710678],
             [ 0.        ,  1.        ,  0.        ],
             [-0.70710678,  0.        ,  0.70710678]])

`rotmat.``R2_s`()

  Symbolic rotation matrix about the 2-axis, by an angle phi

  Returns: | R2_s
  Return type: | symbolic matrix for rotation about 2-axis

  Examples

      >>> R_Fick = R3_s() * R2_s() * R1_s()

`rotmat.``R3`(theta)

  Rotation about the 3-axis. The argument is entered in degree.

  Parameters: | theta (rotation angle about the 3-axis [deg]) –
  Returns: | R3
  Return type: | rotation matrix, for rotation about the 3-axis

  Examples

      >>> thLib.rotmat.R3(45)
      array([[ 0.70710678, -0.70710678,  0.        ],
             [ 0.70710678,  0.70710678,  0.        ],
             [ 0.        ,  0.        ,  1.        ]])

`rotmat.``R3_s`()

  Symbolic rotation matrix about the 3-axis, by an angle theta

  Returns: | R3_s
  Return type: | symbolic matrix for rotation about 3-axis

  Examples

      >>> R_Fick = R3_s() * R2_s() * R1_s()

`rotmat.``rotmat2Euler`(R)

  This function takes a rotation matrix, and calculates the corresponding Euler-angles. R_Euler = R3(gamma) * R1(beta) * R3(alpha)

  Parameters: | R (rotation matrix) –
  Returns: | alpha (first rotation(about 3-axis)) beta (second rotation (about 1-axis)) gamma (third rotation (about 3-axis))

  Notes

  The following formulas are used:

  \[ \begin{align}\begin{aligned}\beta = -arcsin(\sqrt{ R_{13}^2 + R_{23}^2 }) * sign(R_{23})\\\gamma = arcsin(\frac{R_{13}}{sin\beta})\\\alpha = arcsin(\frac{R_{31}}{sin\beta})\end{aligned}\end{align} \]

`rotmat.``rotmat2Fick`(R)

  This function takes a rotation matrix, and calculates the corresponding Fick-angles.

  Parameters: | R (rotation matrix) –
  Returns: | psi (torsional position (rotation about 1-axis)) phi (vertical position (rotation about 2-axis)) theta (horizontal position (rotation about 3-axis))

  Notes

  The following formulas are used:

  \[ \begin{align}\begin{aligned}\theta = arctan(\frac{R_{21}}{R_{11}})\\\phi = arcsin(R_{31})\\\psi = arctan(\frac{R_{32}}{R_{33}})\end{aligned}\end{align} \]

  Note that it is assumed that psi < pi !

`rotmat.``rotmat2Helmholtz`(R)

  This function takes a rotation matrix, and calculates the corresponding Helmholtz-angles.

  Parameters: | R (rotation matrix) –
  Returns: | psi (torsional position (rotation about 1-axis)) phi (vertical position (rotation about 2-axis)) theta (horizontal position (rotation about 3-axis))

  Notes

  The following formulas are used:

  \[ \begin{align}\begin{aligned}\theta = arcsin(R_{21})\\\phi = -arcsin(\frac{R_{31}}{cos\theta})\\\psi = -arcsin(\frac{R_{23}}{cos\theta})\end{aligned}\end{align} \]

  Note that it is assumed that psi < pi