Changes to read-the-docs

algorithms/AttParams.rst

@@ -0,0 +1,123 @@
+Attitude Parameters
+==================
+
+.. contents:: Contents
+    :local:
+
+.. role::  raw-html(raw)
+    :format: html
+
+A body's position and orientation can only be measured relative to another coordinate-frame (set of basis vectors).  In this formulation, inertial sensors provide the information to compute the attitude and position of a body in space relative to an "inertial" frame, such as the Earth-Centered, Earth-Fixed frame (ECEF) or the North/East/Down-frame (NED) .  The equations to come use the superscripts listed in Table 1 to specify the frame in which a variable is measured.
+
+.. |Perp| replace:: :raw-html:`⊥`
+.. |Perp2| replace:: :raw-html:`⊥`
+.. |H2O| replace:: H\ :sub:`⊥`\ O
+.. |xSubPerp| replace:: x\ :sub:`⊥`
+.. |ySubPerp| replace:: y\ :sub:`⊥`
+.. |zSubPerp| replace:: z\ :sub:`⊥`
+.. |xSubB| replace:: x\ :sub:`⊥`
+.. |ySubB| replace:: y\ :sub:`⊥`
+.. |zSubB| replace:: z\ :sub:`⊥`
+
++-------------+-----------------+-----------------------------------------------------------------------------------+
+|  **Frame**  | **Superscript** |  **Description**                                                                  |
++=============+=================+===================================================================================+
+| ECEF-Frame  | E               || Frame aligned with Earth's axis (z-axis parallel to axis-of-                     |
+|             |                 || rotation, x-axis exits at the equator through the prime-                         |
+|             |                 || meridian); rotates with the Earth                                                |
++-------------+-----------------+-----------------------------------------------------------------------------------+
+| NED-Frame   | N               || Frame aligned with the local tangent-frame (z-axis parallel to                   |
+|             |                 || the gravity vector) with the x-axis aligned with true or                         |
+|             |                 || magnetic north.  Red lines in *Figure 1*.                                        |
++-------------+-----------------+-----------------------------------------------------------------------------------+
+| Perp-Frame  | P               || Frame aligned with the local tangent-frame (|zSubPerp|\ -axis parallel to        |
+|             |                 || the gravity vector).  Dark blue lines in *Figure 1*                              |
++-------------+-----------------+-----------------------------------------------------------------------------------+
+| Body-Frame  | B               || Frame aligned with the body-frame.  |xSubB|\ -axis lies in the plane             |
+|             |                 || formed by the |xSubPerp| and |zSubPerp|\ -axes.  Light blues lines in *Figure 1* |
++-------------+-----------------+-----------------------------------------------------------------------------------+
+
+*Figure 1* shows the relative orientation of three of the four frames listed in *Table 1* (ECEF not shown) for a hypothetical body on the surface of the Earth with a roll of 20\ :raw-html:`°`, a pitch of 10\ :raw-html:`°`, and a heading of 30\ :raw-html:`°`.  The dashed red lines illustrate the components of the |Perp|\ -frame axes in the N-Frame while the dashed blue lines indicate the projection of the B-Frame axes onto the N-frame.
+
+
+|CoordFrames|
+
+
+
+ :raw-html:`⊥`
+  plane  |
+
+|             |                 || formed by the x :sub: :raw-html:`⊥`  and z                |
+|             |                 || :sub: :raw-html:`⊥`   |
+|             |                 || -axes.  Light blue lines in *Figure 1*.                        |
+
+
+
+The difference between t\ :sub:`ground` and t\ :sub:`sky` gives us a
+reading known as t\ :sub:`⊥`\ .
+
+
+
+|Perp|
+
+
+
+
+|Perp2|
+
+The difference between t\ :sub:`ground` and t\ :sub:`sky` gives us a
+reading known as t\ :sub:`?`\ .
+
+The power series, :math:`\frac{1}{0!}+\frac{2}{1!}x+\frac{3}{2!}x^2+\frac{4}{3!}x^3+...` states
+that...
+
+
+
+The well known quadratic formula:
+
+.. math::
+
+
+    x = -b \pm \frac{\sqrt{b^{2}-4ac}}{2a}
+
+ 
+   
+The |biohazard| symbol must be used on containers used to dispose
+of medical waste.
+
+The :sub:|biohazard| symbol must be used on containers used to dispose
+of medical waste.
+
+
+The `biohazard`:sub: symbol...
+
+
+
+
+|7430-0131_fig_15|
+
+The `Perp`:sub: symbol...
+
+The :raw-html:`⊥`:sub: symbol...
+
+
+
+
+And then you can write:
+
+This way :raw-html:`→`
+
+
+Degree :raw-html:`°`
+
+
+.. |CoordFrames| image:: ../media/CoordFrames.png
+   :width: 10.0in
+
+
+
+.. |biohazard| image:: ../media/attention.png
+   :width: 0.24in
+   :height: 0.85in
+
+

algorithms/AttitudeParameters.rst

@@ -0,0 +1,200 @@
+Attitude Parameters
+====================
+
+.. contents:: Contents
+    :local:
+
+.. role::  raw-html(raw)
+    :format: html
+
+This paper makes use of three different attitude parameters to specify the orientation of a body (B) relative to another frame (such as the N-frame).
+
+   #.  Direction Cosine Matrices
+   #.  Quaternion Elements
+   #.  Euler Angles
+
+Direction Cosine Matrices
+--------------------------
+
+The first of these, the direction cosine matrix\ [#rot_BinN]_, |R_BinN|\ , specifies the attitude of one frame relative to another by relaying how the basis-vectors of one frame relate to the basis-vectors of another.  These matrices have the property that they can, in a straightforward manner, transform vectors from one frame into another, such as from the Body to the NED-frame:
+
+.. math::
+
+    \vec{x}{^N} = {^N}{R}{^B} \cdot \vec{x}{^B}
+
+
+In the upcoming derivation, transformations based on the Body-Fixed 3-2-1 Rotation set\ [#rot_321]_ and the formulation used by Thomas Kane\ [#Kane_Ref]_  are relied upon extensively.
+
+
+Quaternion Elements
+--------------------
+
+The second parameter used to convey orientation information are quaternion elements\ [#quatElems]_ (also called Euler parameters), |q_BinN|.  Quaternions are relatively easy to propagate in time and do not possess singularities.  However, they are not intuitive.  Quaternions consist of a scalar and a vector component:
+
+
+.. math::
+
+
+
+    \hspace{5mm}{^N}{\vec{q}}{^B} = \hspace{5mm}{ \begin{bmatrix} {q_{0} \hspace{5mm} \vec{q}_{v}} \end{bmatrix} }{^T}
+
+.. math::
+
+    = { \begin{bmatrix} {q_{0} \hspace{5mm} q_{1} \hspace{5mm} q_{2} \hspace{5mm} q_{3}} \end{bmatrix} }{^T}
+
+.. math::
+
+    = { \begin{bmatrix} {\cos{\begin{pmatrix} \theta \over 2 \end{pmatrix}} \hspace{5mm} \hat{u} \cdot \sin{\begin{pmatrix} \theta \over 2 \end{pmatrix}}} \end{bmatrix} }{^T}
+
+
+Euler Angles
+-------------
+
+The final parameter used to relay attitude information are Euler angles.  These are more intuitive than quaternions but, unlike quaternions, experience singularities at certain angles (based on the selected rotation sequence).  For a 321-rotation sequence\ [#Rot_Seq_Usage]_, the singularity is at a pitch of 90°.
+
+
+Mathematical Relationships between Attitude Parameters
+-------------------------------------------------------
+
+All three parameters contain the same information.  The equations that relate the various parameters follow\ [#Quat_Ref]_.  For a 321-rotation sequence, the expression relating the rotation transformation matrix of the body-frame in the NED-frame, |R_BinN| , to the quaternion elements, |q_BinN|, is:
+
+.. math::
+
+	{{^N}{R}{^B}} = { {
+                      \begin{bmatrix} {{{{q_0}^2 + {q_1}^2 - {q_2}^2 - {q_3}^2} \\
+                                         {2 \cdot { \begin{pmatrix} {q_1 \cdot q_2 + q_0 \cdot q_3} \end{pmatrix} }} \\
+                                         {2 \cdot { \begin{pmatrix} {q_1 \cdot q_3 - q_0 \cdot q_2} \end{pmatrix} }}} \hspace{5mm}
+                                        {{2 \cdot { \begin{pmatrix} {q_1 \cdot q_2 - q_0 \cdot q_3} \end{pmatrix} }} \\
+                                         {{q_0}^2 - {q_1}^2 + {q_2}^2 - {q_3}^2} \\
+                                         {2 \cdot { \begin{pmatrix} {q_2 \cdot q_3 + q_0 \cdot q_1} \end{pmatrix} }}} \hspace{5mm}
+                                        {{2 \cdot { \begin{pmatrix} {q_1 \cdot q_3 + q_0 \cdot q_2} \end{pmatrix} }} \\
+                                         {2 \cdot { \begin{pmatrix} {q_2 \cdot q_3 - q_0 \cdot q_1} \end{pmatrix} }} \\
+                                         {{q_0}^2 - {q_1}^2 - {q_2}^2 + {q_3}^2}}
+                      } \end{bmatrix}
+                    }
+                  }
+
+|R_BinN| can also be expressed in terms of Euler-angles, :math:`{{^N}{\vec{\Theta}}{^B}} = { \begin{bmatrix} {{{^⊥}{\phi}{^B }} \hspace{5mm} {{^⊥}{\theta}{^B }} \hspace{5mm} {{^N}{\psi}{^⊥ }}} \end{bmatrix} }{^T}`\ :
+
+
+.. math::
+
+	{{^N}{R}{^B}} = { \begin{bmatrix} {{{\cos{\begin{pmatrix} {{^N}{\psi}{^⊥}} \end{pmatrix}}} \\
+                                        {\sin{\begin{pmatrix} {{^N}{\psi}{^⊥}} \end{pmatrix}}} \\
+                                        {0}} \hspace{5mm}
+                                       {{- \sin{\begin{pmatrix} {{^N}{\psi}{^⊥}} \end{pmatrix}}} \\
+                                        {\cos{\begin{pmatrix} {{^N}{\psi}{^⊥}} \end{pmatrix}}} \\
+                                        {0}} \hspace{5mm}
+									   {{0} \\
+                                        {0} \\
+                                        {1}}}
+                      \end{bmatrix} }
+                    \cdot
+                    { {\begin{bmatrix} {{{\cos{\begin{pmatrix} {{^⊥}{\theta}{^B}} \end{pmatrix}}} \\
+                                         {0} \\
+                                         {-\sin{\begin{pmatrix} {{^⊥}{\theta}{^B}} \end{pmatrix}}}} \hspace{5mm}
+                                        {{\sin{\begin{pmatrix} {{^⊥}{\theta}{^B}} \end{pmatrix}} \cdot \sin{\begin{pmatrix} {{^⊥}{\phi}{^B}} \end{pmatrix}}} \\
+                                         {\cos{\begin{pmatrix} {{^⊥}{\phi}{^B}} \end{pmatrix}}} \\
+                                         {\cos{\begin{pmatrix} {{^⊥}{\theta}{^B}} \end{pmatrix}} \cdot \sin{\begin{pmatrix} {{^⊥}{\phi}{^B}} \end{pmatrix}}}} \hspace{5mm}
+                                        {{\sin{\begin{pmatrix} {{^⊥}{\theta}{^B}} \end{pmatrix}} \cdot \cos{\begin{pmatrix} {{^⊥}{\phi}{^B}} \end{pmatrix}}} \\
+                                         {-\sin{\begin{pmatrix} {{^⊥}{\phi}{^B}} \end{pmatrix}}} \\
+                                         {\cos{\begin{pmatrix} {{^⊥}{\theta}{^B}} \end{pmatrix}} \cdot \cos{\begin{pmatrix} {{^⊥}{\phi}{^B}} \end{pmatrix}}}}}
+                       \end{bmatrix} } }
+
+
+In this case, |R_BinN| is broken up into two sequential transformations, which separate the roll and pitch calculations from the heading (this method is used later to form attitude measurements from the sensor readings):
+
+
+.. math::
+
+	{{^N}{R}{^B}} = {{^N}{R}{^⊥}} \cdot {{^⊥}{R}{^B}}
+
+
+Finally, Euler angles, |Theta_BinN|, can be expressed in terms of quaternion-elements, |q_BinN|:
+
+
+.. math::
+
+    {^⊥}{\phi}{^B}   = {atan2}{\begin{pmatrix} {2 \cdot { \begin{pmatrix} {q_2 \cdot q_3 + q_0 \cdot q_1} \end{pmatrix} }, \hspace{2mm} {{q_0}^2 - {q_1}^2 - {q_2}^2 + {q_3}^2}} \end{pmatrix}}
+
+    {^⊥}{\theta}{^B} = -{asin}{\begin{pmatrix} {2 \cdot { \begin{pmatrix} {q_1 \cdot q_3 - q_0 \cdot q_2} \end{pmatrix} }} \end{pmatrix}}
+
+    {^N}{\psi}{^⊥}   = {atan2}{\begin{pmatrix} {2 \cdot { \begin{pmatrix} {q_1 \cdot q_2 + q_0 \cdot q_3} \end{pmatrix} }, \hspace{2mm} {{q_0}^2 + {q_1}^2 - {q_2}^2 - {q_3}^2}} \end{pmatrix}}
+
+
+Note: due to the way the roll and pitch are separated from the heading, the Euler angles, |phi_Bin⊥|, |theta_Bin⊥|, and |psi_⊥inN| are the same if written as |phi_BinN|, |theta_BinN|, and |psi_BinN|.
+
+
+Example
+--------
+
+
+Using the direction cosine matrix formulation, the transformation to get from the body to inertial-frame (ECEF) is composed of multiple transformations (*Figure 1*):
+
+   #.  Transformation from the (light-blue) body-frame to the (dark blue) local perpendicular-frame (⊥), |R_Bin⊥|
+   #.  Transformation from the (dark blue) ⊥-frame to the (red) local NED-frame, |R_⊥inN|
+   #.  Transformation from the (red) NED-frame to the ECEF-frame, |R_NinE| (ECEF-Frame not shown; black line are latitude and longitude lines).  |R_NinE| is based on the WGS84 model.
+
+
+This notation not only makes the formulation easier by simplifying the full complexity of the transformation but it helps avoid confusion by explicitly specifying the frame used in each calculation:
+
+.. math::
+
+    {^E}{R}{^B} = {^E}{R}{^N} \cdot {^N}{R}{^⊥} \cdot {^⊥}{R}{^B}
+
+
+Some additional information about these frames:
+
+   #.  |R_NinE|, the transformation between the NED and Earth-frame (used in the INS formulation), is solely a function of ECEF location, :math:`{^E}{R}{^N} = f({\vec{r}}{^E})`\ , and is based on the WGS84 model.
+   #.  |R_BinN|, the transformation between the NED and body-frame is solely a function of the attitude of the body-frame (roll, pitch, and heading angles of the body) and can be measured by the local gravity and magnetic-field vectors (or GPS heading), :math:`{^N}{R}{^B} = f({\vec{g}}, {\vec{b}})`
+
+
+
+.. |Perp| replace:: :raw-html:`⊥`
+.. |Perp2| replace:: :raw-html:`⊥`
+.. |H2O| replace:: H\ :sub:`⊥`\ O
+.. |xSubPerp| replace:: x\ :sub:`⊥`
+.. |ySubPerp| replace:: y\ :sub:`⊥`
+.. |zSubPerp| replace:: z\ :sub:`⊥`
+.. |xSubB| replace:: x\ :sub:`⊥`
+.. |ySubB| replace:: y\ :sub:`⊥`
+.. |zSubB| replace:: z\ :sub:`⊥`
+
+
+
+
+.. |R_BinN| replace:: :math:`{^N}{R}{^B}`
+.. |q_BinN| replace:: :math:`{^N}{\vec{q}}{^B}`
+
+.. |R_LinN| replace:: :math:`{^N}{R}{^L}`
+
+.. |RSub321| replace:: :math:`{R}_{321}`
+
+.. |Theta_BinN| replace:: :math:`{^N}{\vec{\Theta}}{^B}`
+
+.. |phi_Bin⊥| replace:: :math:`{^⊥}{\phi}{^B}`
+.. |theta_Bin⊥| replace:: :math:`{^⊥}{\theta}{^B}`
+.. |psi_⊥inN| replace:: :math:`{^N}{\psi}{^⊥}`
+
+.. |phi_BinN| replace:: :math:`{^N}{\phi}{^B}`
+.. |theta_BinN| replace:: :math:`{^N}{\theta}{^B}`
+.. |psi_BinN| replace:: :math:`{^N}{\psi}{^B}`
+
+.. |R_Bin⊥| replace:: :math:`{^⊥}{R}{^B}`
+.. |R_⊥inN| replace:: :math:`{^N}{R}{^⊥}`
+.. |R_NinE|  replace:: :math:`{^E}{R}{^N}`
+
+.. [#rot_BinN] Pronounced “R B-in-N” and refers to the orientation of the B-Frame in the N-Frame.  Also referred to as a rotation transformation matrix.
+
+.. [#rot_321] A 3-2-1 rotation set defines the attitude of one set of basis-vectors (local-frame) relative to another by specifying the angles of rotation required to get from the inertial (N) to the local-frame (L).  With the local and inertial-frames initially aligned, the rotations are performed about the local z-axis (3), followed by a rotation about the local y-axis (2), and finally by a rotation about the local x-axis (1).  The resulting matrix, |R_LinN| = |RSub321|, is composed of column vectors formed from the xyz-axes of the local-frame coordinatized in the inertial-frame: |R_LinN| = :math:`\begin{bmatrix} {{{\hat{x}_{L}}{^N}} \hspace{5mm} {{\hat{y}_{L}}{^N}} \hspace{5mm} {{\hat{z}_{L}}{^N}}} \end{bmatrix}`\ .
+
+
+.. [#Kane_Ref] Kane, Thomas R.; Levinson, David A. (1985), Dynamics, Theory and Applications, McGraw-Hill series in mechanical engineering, McGraw Hill.  Note: one main difference between Kane’s approach is the DCM is the transpose of the DCM of other formulations; I think Kane’s formulation is more intuitive.
+
+
+.. [#quatElems] Commonly referred to simply as “quaternion”.  To make it easier to reference the elements in c, c++, and python, the first quaternion-element (the scalar component of the quaternion) will have the zero index and is expressed as :math:`{q}_{0}=\cos \begin{pmatrix} \theta / 2 \end{pmatrix}`.  The vector component of the quaternion,  :math:`{\vec{q}}_{v}=\hat{u} \cdot \sin \begin{pmatrix} \theta / 2 \end{pmatrix}`, occupies elements 2, 3, and 4.
+
+
+.. [#Rot_Seq_Usage] The 321-rotation sequence is the only rotation sequence considered in this paper.
+
+.. [#Quat_Ref] Based on unpublished notes by Keith Reckdahl (Direction Cosines, Rotations, and Quaternions); this paper follows Kane’s approach closely.  Any reference on the subject will work.