Localization system
===================

The localization system category contains only ``localizationSystem`` elements.
A localization system is an HDF5 named group child of ``/localizationSystem`` 
with two attributes :

* ``reference`` is an HDF5 string attribute and is optional. It represents
  the reference localization system (an absolute localization
  system has no reference).

* ``dimension`` is an HDF5 integer attribute and is mandatory. It represents
  the dimension of the system.

::

    data.h5
    `-- localizationSystem/
        |-- $locsys[@dimension=3]
        `-- $locsys1[@dimension=3
                     @reference=/localizationSystem/$locsys]

A localization system comprises elementary geometric transformations, 
a transformation can be :

* Scale transformation
* Rotation
* Translation

These elementary transformations are the children of a localization system
and have a string attribute ``type`` equals ``scale``, ``rotation``, 
``translation`` or ``zxzEulerRotation``.

Example :

::

    data.h5
    `-- localizationSystem/
        |-- $locsys[@dimension=3]/
        `-- $locsys1[@dimension=3
                     @reference=/localizationSystem/$locsys1]/


.. note::

  If a localization system has no transformations child, it is equivalent
  to the reference localization system.

  Each transformation moves, rotates or scales the localization relative to
  the reference localization system in sequence.


Transformation order
--------------------

Transformations have to be ordered to give the correct result. The order is
stored in a mandatory attribute ``rank`` owned by all transformations.

::

    data.h5
    `-- localizationSystem/
        `-- $locsys[@dimension=3]/
            |-- $scale1[@type=scale
            |           @rank=2]
            |-- $rotation1[@type=rotation
            |              @rank=1]
            `-- $translation1[@type=translation
                              @$rank=3]

Transformations will then be applied in the following order :

=== ===============
 1   $rotation1
 2   $scale1     
 3   $translation1
=== ===============


Scale transformation
--------------------

A scale transformation is simply a scale factor, it is a HDF5 named 
``floatingType`` equals ``dataSet`` of one float element 
with ``type`` equals ``scale``.

Example :

::

    data.h5
    `-- localizationSystem/
        `-- $locsys[@dimension=3]/
            `-- $scale1[@type=scale]

where ``data.h5:/localizationSystem/$locsys/$scale1`` :

.. math::

    \begin{pmatrix}
    2.0 \\
    \end{pmatrix}


Rotation
--------

A rotation is defined by a 3x3 matrix :

.. math::

    A = \begin{pmatrix}
    a_{11} & a_{12} & a_{13} \\
    a_{21} & a_{22} & a_{23} \\
    a_{31} & a_{32} & a_{33}
    \end{pmatrix}

The point coodinates are calculated with :

.. math::

    \begin{pmatrix}x_1' \\ y_1' \\ z_1'\end{pmatrix} =
    \begin{pmatrix}
    a_{11} & a_{12} & a_{13} \\
    a_{21} & a_{22} & a_{23} \\
    a_{31} & a_{32} & a_{33}
    \end{pmatrix}
    \begin{pmatrix}x_1 \\ y_1 \\ z_1\end{pmatrix}

Example of a rotation of :math:`\alpha` around the x axis :

.. math::


    R_x(\alpha) = \begin{pmatrix}
    1 & 0 & 0 \\
    0 &  \cos\alpha & \sin\alpha \\
    0 & -\sin\alpha & \cos\alpha
    \end{pmatrix}


In |namespec|, a rotation is a HDF5 named 
``floatingType`` equals ``dataSet`` of 3x3 floats elements
with ``type`` equals ``rotation``.

Example :

::

    data.h5
    `-- localizationSystem/
        `-- $locsys[@dimension=3]/
            `-- $rotation1[@type=rotation]

where ``data.h5:/localizationSystem/$locsys/$rotation1`` :

.. math::

    \begin{pmatrix}
    1 & 0 & 0 \\
    0 &  \cos\alpha & \sin\alpha \\
    0 & -\sin\alpha & \cos\alpha
    \end{pmatrix}


Euler rotation
--------------


Rotation can be expressed with the zxz Euler convention.


Three consecutive rotations :math:`D, C, B` are applied :

* A rotation around the Z axis, angle :math:`\phi`
* A rotation around the X axis , angle :math:`\theta \in [0, \pi]` 
* A rotation around the z axis, angle :math:`\psi`

.. image:: images/euler_rotation.png
  :width: 60%


.. math::

    D = \begin{pmatrix}
     \cos\phi &  \sin\phi & 0 \\
    -\sin\phi &  \cos\phi & 0 \\
    0         &   0       & 1
    \end{pmatrix}

.. math::

    C = \begin{pmatrix}
    1         &  0       & 0 \\
    0         &  \cos\theta &  \sin\theta \\
    0         & -\sin\theta &  \cos\theta
    \end{pmatrix}

.. math::

    B = \begin{pmatrix}
     \cos\psi &  \sin\psi & 0 \\
    -\sin\psi &  \cos\psi & 0 \\
    0         &   0       & 1
    \end{pmatrix}

And finaly the resultant matrix :math:`A = BCD`

In |namespec|, an Euler rotation is a HDF5 named 
``floatingType`` equals ``vector`` of 3 floats elements 
:math:`(\phi, \theta, \psi)` with ``type`` equals ``zxzEulerRotation``.


Example :

::

    data.h5
    `-- localizationSystem/
        `-- $locsys[@dimension=3]/
            `-- $euler1[@type=zxzEulerRotation]

where ``data.h5:/localizationSystem/$locsys/$euler1`` :

.. math::

    \begin{pmatrix}
    \pi & \pi/2 & \pi \\
    \end{pmatrix}


Translation
-----------

A translation is defined by a vector :math:`T(T_x, T_y, T_z)`.

In |namespec|, a translation is a HDF5 named 
``floatingType`` equals ``vector`` of 3 floats elements
with ``type`` equals ``translation``.

Example :

::

    data.h5
    `-- localizationSystem/
        `-- $locsys[@dimension=3]/
            `-- $translation1[@type=translation]

where ``data.h5:/localizationSystem/$locsys/$translation1`` :

.. math::

    \begin{pmatrix}
    1 & 0 & 0 \\
    \end{pmatrix}