Document the helmert transform

1 files changed, 366 insertions, 11 deletions

diff --git a/docs/source/usage/operations/transformations/helmert.rst b/docs/source/usage/operations/transformations/helmert.rst
index 88a3facd..001d2db1 100644
--- a/docs/source/usage/operations/transformations/helmert.rst
+++ b/docs/source/usage/operations/transformations/helmert.rst
@@ -4,15 +4,370 @@
 Helmert transform
 ================================================================================
 
-Change reference frame by Helmert shift.
-
-+-----------------+--------------------------------------------------------------------+
-| **Input type**  | Cartesian coordinates (spatial), decimalyears (temporal).          |
-+-----------------+--------------------------------------------------------------------+
-| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal).          |
-+-----------------+--------------------------------------------------------------------+
-| **Options**                                                                          |
-+-----------------+--------------------------------------------------------------------+
-| `+x`            |
-+-----------------+--------------------------------------------------------------------+
+The Helmert transformation changes coordinates from one reference frame to
+anoether by means of 3-, 4-and 7-parameter shifts, or one of their 6-, 8- and
+14-parameter kinematic counterparts.
 
++-----------------+-------------------------------------------------------------------+
+| **Input type**  | Cartesian coordinates (spatial), decimalyears (temporal).         |
++-----------------+-------------------------------------------------------------------+
+| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal).         |
++-----------------+-------------------------------------------------------------------+
+| **Options**                                                                         |
++----------------+--------------------------------------------------------------------+
+| `x`            | Translation of the x-axis [m]. *Optional*.                         |
++----------------+--------------------------------------------------------------------+
+| `y`            | Translation of the y-axis [m]. *Optional*.                         |
++----------------+--------------------------------------------------------------------+
+| `z`            | Translation of the z-axis. [m]. *Optional*.                        |
++----------------+--------------------------------------------------------------------+
+| `s`            | Scale factor [ppm]. *Optional*.                                    |
++----------------+--------------------------------------------------------------------+
+| `rx`           | X-axis rotation in the 3D Helmert [arc seconds]. *Optional*.       |
++----------------+--------------------------------------------------------------------+
+| `ry`           | Y-axis rotatoin in the 3D Helmert [arc seconds]. *Optional*.       |
++----------------+--------------------------------------------------------------------+
+| `rz`           | Z-axis rotation in the 3D Helmert [arc seconds]. *Optional*.       |
++----------------+--------------------------------------------------------------------+
+| `theta`        | Rotation angle in the 2D Helmert. [arc seconds]. *Optional*.       |
++----------------+--------------------------------------------------------------------+
+| `dx`           | Translation rate of the x-axis. [m/year]. *Optional*.              |
++----------------+--------------------------------------------------------------------+
+| `dy`           | Translation rate of the y-axis. [m/year]. *Optional*.              |
++----------------+--------------------------------------------------------------------+
+| `dz`           | Translation rate of the z-axis. [m/year]. *Optional*.              |
++----------------+--------------------------------------------------------------------+
+| `ds`           | Scale rate factor [ppm/year]. *Optional*.                          |
++----------------+--------------------------------------------------------------------+
+| `drx`          | Rotation rate of the x-axis [arc seconds/year]. *Optional*.        |
++----------------+--------------------------------------------------------------------+
+| `dry`          | Rotation rate of the y-axis [arc seconds/year]. *Optional*.        |
++----------------+--------------------------------------------------------------------+
+| `drz`          | Rotation rate of the y-axis [arc seconds/year]. *Optional*.        |
++----------------+--------------------------------------------------------------------+
+| `t_epoch`      | Central epoch of transformation. [decimalyear]. Only used in       |
+|                | spatiotemporal transformations. *Optional*.                        |
++----------------+--------------------------------------------------------------------+
+| `t_obs`        | Observation time of coordinate(s). Mostly useful in 2D and 3D      |
+|                | transformations. [decimalyear]. *Optional*.                        |
++----------------+--------------------------------------------------------------------+
+| `exact`        | Use exact transformation equations. *Optional*.                    |
++----------------+--------------------------------------------------------------------+
+| `transpose`    | Transpose rotation matrix. *Optional*.                             |
++----------------+--------------------------------------------------------------------+
+
+The Helmert transform, in all it's various incarnations, is used to perform reference
+frame shifts. The transformation operates in cartesian space. It can be used to transform
+planar coordinates from one datum to another (:ref:`2D Helmert`), transform 3D cartesian
+coordinates from one static reference frame to another or it can be used to do fully
+kinematic transformations from global reference frame to local static frames.
+
+All of the parameters described in the table above are marked as optional. This is true
+as long as at least one parameter is defined in the setup of the transformation.
+The behaviour of the transformation depends on which parameters are used in the setup.
+For instance, if a rate of change paramater is specified a kinematic version of the
+transformation is used.
+
+Examples
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Transforming coordinates from NAD72 to NAD83 using the 4 parameter 2D Helmert:
+
+::
+
+    proj=helmert ellps=GRS80 x=-9597.3572 y=.6112
+                 s=0.304794780637 theta=-1.244048
+
+Simplified transformations from ITRF2008/IGS08 to ETRS89 using 7 parameters:
+
+::
+
+    proj=helmert ellps=GRS80 x=0.67678    y=0.65495   z=-0.52827
+                rx=-0.022742 ry=0.012667 rz=0.022704  s=-0.01070
+
+Transformation from `ITRF2000@2017.0`  to `ITRF93@2017.0` using 15 parameters:
+
+::
+
+    proj=helmert ellps=GRS80
+         x=0.0127     y=0.0065     z=-0.0209  s=0.00195
+         dx=-0.0029   dy=-0.0002   dz=-0.0006 ds=0.00001
+         rx=-0.00039  ry=0.00080   rz=-0.00114
+         drx=-0.00011 dry=-0.00019 drz=0.00007
+         epoch=1988.0 tobs=2017.0    transpose
+
+Mathematical description
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+In the notation used below, :math:`\hat{P}` is the rate of change of a given transformation
+parameter :math:`P`. :math:`\dot{P}` is the kinematically adjusted version of :math:`P`,
+described by
+
+.. math::
+    :label: propagation
+
+    \dot{P}= P + \hat{P}\left(t - t_{central}\right)
+
+where :math:`t` is the observation time of the coordinate and :math:`t_{central}` is
+the central epoch of the transformation. Equation :eq:`propagation` can be used to
+propagate all transformation parameters in time.
+
+Superscripts of vectors denote the reference frame the coordinates in the vector belong to.
+
+
+2D Helmert
+-------------------------------------------------------------------------------
+
+The simplest version of the Helmert transform is the 2D case. In the 2-dimensional
+case only the horizontal coordinates are changed. The coordinates can be
+translated, rotated and scale. Translation is controlled with the `x` and `y`
+parameters. The rotation is determined by `theta` and the scale is controlled with
+the `s` paramaters.
+
+.. note::
+
+    The scaling parameter `s` is unitless for the 2D Helmert, as opposed to the
+    3D version where the scaling parameter is given in units of ppm.
+
+Mathematically the 2D Helmert is described as:
+
+.. math::
+    :label: 4param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            T_x \\
+            T_y \\
+        \end{bmatrix} +
+        s
+        \begin{bmatrix}
+            \hphantom{-}\cos \theta & \sin \theta \\
+            -\sin \theta & \cos \theta \\
+        \end{bmatrix}
+        \begin{bmatrix}
+            X \\
+            Y \\
+        \end{bmatrix}^A
+    \end{align}
+
+
+:eq:`4param` can be extended to a time-varying kinematic version by
+adjusting the parameters with :eq:`propagation` to :eq:`4param`, which yields
+the kinematic 2D Helmert transform:
+
+.. math::
+    :label: 8param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            \dot{T_x} \\
+            \dot{T_y} \\
+        \end{bmatrix} +
+        s(t)
+        \begin{bmatrix}
+             \hphantom{-}\cos \dot{\theta} & \sin \dot{\theta}  \\
+                        -\sin\ \dot{\theta} & \cos \dot{\theta} \\
+        \end{bmatrix}
+        \begin{bmatrix}
+            X \\
+            Y \\
+        \end{bmatrix}^A
+    \end{align}
+
+All parameters in :eq:`8param` are determined by the use of :eq:`propagation`,
+which applies the rate of change to each individual parameter for a given
+timespan between :math:`t` and :math:`t_{central}`.
+
+
+3D Helmert
+-------------------------------------------------------------------------------
+
+The general form of the 3D Helmert is
+
+.. math::
+    :label: general-helmert
+
+
+    \begin{align}
+        V^B = T + \left(1 + s \times 10^{-6}\right) \mathbf{R} V^A
+    \end{align}
+
+Where :math:`T` is a vector consisting of the three translation parameters, :math:`s`
+is the scaling factor and :math:`\mathbf{R}` is a rotation matrix. :math:`V^A` and
+:math:`V^B` are coordinate vectors, with :math:`V^A` being the input coordinate and
+:math:`V^B` is the output coordinate.
+
+The rotation matrix is composed of three rotation matrices, one for each axis:
+
+.. math::
+
+    \begin{align}
+        \mathbf{R}_X &= \begin{bmatrix} 1 & 0 & 0\\ 0 & \cos\phi & -\sin\phi\\ 0 & \sin\phi & \cos\phi \end{bmatrix}
+    \end{align}
+
+.. math::
+
+    \begin{align}
+        \mathbf{R}_Y &= \begin{bmatrix} \cos\theta & 0 & \sin\theta\\ 0 & 1 & 0\\ -\sin\theta & 0 & \cos\theta \end{bmatrix}
+    \end{align}
+
+.. math::
+
+    \begin{align}
+        \mathbf{R}_Z &= \begin{bmatrix} \cos\psi & -\sin\psi & 0\\ \sin\psi & \cos\psi & 0\\ 0 & 0 & 1 \end{bmatrix}
+    \end{align}
+
+The three rotation matrices can be combined in one:
+
+.. math::
+
+    \begin{align}
+        \mathbf{R} = \mathbf{R_X} \mathbf{R_Y} \mathbf{R_Y}
+    \end{align}
+
+For :math:`\mathbf{R}`, this yields:
+
+.. math::
+    :label: rot_exact
+
+    \begin{bmatrix}
+      \cos\theta \cos\psi &  -\cos\phi \sin\psi + \sin\phi \sin\theta \cos\psi &   \sin\phi \sin\psi + \cos\phi \sin\theta \cos\psi \\
+      \cos\theta\sin\psi &  \cos\phi \cos\psi + \sin\phi \sin\theta \sin\psi &  - \sin\phi \cos\psi + \cos\phi \sin\theta \sin\psi \\
+      -\sin\theta             &  \sin\phi \cos\theta                                          &   \cos\phi \cos\theta \\
+     \end{bmatrix}
+
+
+Using the small angle approxition the rotation matrix can be simplified to
+
+.. math::
+    :label: rot_approx
+
+    \begin{align} \mathbf{R} =
+        \begin{bmatrix}
+             1  & -R_z  &  R_y \\
+             Rz &  1    & -R_x \\
+            -Ry &  R_x  &  1   \\
+        \end{bmatrix}
+    \end{align}
+
+Which allow us to express the most common version of the Helmert transform,
+using the approximated rotation matrix:
+
+
+.. math::
+    :label: 7param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            T_x \\
+            T_y \\
+            T_z \\
+        \end{bmatrix} +
+        \left(1 + s \times 10^{-6}\right)
+        \begin{bmatrix}
+             1  & -R_z  &  R_y \\
+             Rz &  1    & -R_x \\
+            -Ry &  R_x  &  1   \\
+        \end{bmatrix}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^A
+    \end{align}
+
+Applying :eq:`propagation` we get the kinematic version of the approximated
+3D Helmert:
+
+.. math::
+    :label: 14param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            \dot{T_x} \\
+            \dot{T_y} \\
+            \dot{T_z} \\
+        \end{bmatrix} +
+        \left(1 + \dot{s} \times 10^{-6}\right)
+        \begin{bmatrix}
+             1         & -\dot{R_z}  &  \dot{R_y} \\
+             \dot{R_z} &  1          & -\dot{R_x} \\
+            -\dot{R_y} &  \dot{R_x}  &  1      \\
+        \end{bmatrix}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^A
+    \end{align}
+
+
+
+
+The Helmert transformation can be applied without using the rotation parameters,
+in which case it becomes a simlpe translation of the origin of the coordinate
+system. When using the Helmert in this version equation :eq:`general-helmert`
+simplies to:
+
+.. math::
+    :label: 3param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            T_x \\
+            T_y \\
+            T_z \\
+        \end{bmatrix} +
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^A
+    \end{align}
+
+That after application of :eq:`propagation` has the following kinematic
+countpart:
+
+.. math::
+    :label: 6param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            \dot{T_x} \\
+            \dot{T_y} \\
+            \dot{T_z} \\
+        \end{bmatrix} +
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^A
+    \end{align}