ENH: Rocket Axes Definition

CHANGELOG.md

@@ -32,7 +32,7 @@ Attention: The newest changes should be on top -->
 
 ### Added
 
-- 
+-  ENH: Rocket Axis Definition [#635](https://github.com/RocketPy-Team/RocketPy/pull/635)
 
 ### Changed
 

docs/user/index.rst

@@ -14,7 +14,7 @@ RocketPy's User Guide
 
    Positions and Coordinate Systems <positions.rst>
    Motors <motors/motors.rst>
-   Rocket <rocket.rst>
+   Rocket <rocket/rocket.rst>
    Environment <environment.rst>
 
 .. toctree::

docs/user/rocket/rocket.rst

@@ -0,0 +1,15 @@
+Rocket Usage
+============
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Rocket Class Usage
+
+    Rocket Class Usage <rocket_usage.rst>
+
+.. toctree::
+    :maxdepth: 3
+    :caption: Rocket Class Axes Definitions
+
+    Rocket Class Axes Definitions <rocket_axes.rst>
+

docs/user/rocket/rocket_axes.rst

@@ -0,0 +1,145 @@
+Rocket Class Axes Definitions
+=============================
+
+The Rocket class has two different coordinate systems:
+
+1. **User Defined Coordinate System**: Used for geometrical inputs of the 
+   aerodynamic surfaces and motor.
+2. **Body Axes Coordinate System**: Used inside the simulation to assess the 
+   governing equations of motion.
+
+All inputs from the user's coordinate system are converted to the body axes
+coordinate system for use during the simulation.
+
+1. User Defined Coordinate System
+---------------------------------
+
+Two things are set by the user in the user input coordinate system:
+
+1. **Coordinate System Origin**: The origin of the coordinate system is set at 
+   any point along the rocket's center line. This point can be arbitrarily chosen
+   and is not explicitly defined. All inputs must be given in relation to this
+   point.
+2. **Direction of Center Axis**: Specified in the ``coordinate_system_orientation``
+   argument of the class constructor :class:`rocketpy.Rocket.__init__`. This
+   argument defines the direction of the axis that follows the rocket's center
+   line. It can be either ``"nose_to_tail"`` or ``"tail_to_nose"``.
+
+.. seealso:: 
+
+    See `Positions and Coordinate Systems <positions.rst>`_ for more
+    information on how this is used in the definitions of the rocket's
+    aerodynamic surfaces and motor.
+
+The ``x`` and ``y`` axes are defined in the plane perpendicular to the center axis,
+and the ``z`` axis is defined along the center axis. Depending on the choice of
+``coordinate_system_orientation``, the ``x`` axis and ``y`` axis can be inverted.
+
+The following figure shows the two possibilities for the user input coordinate system:
+
+.. figure:: ../../static/rocket/3dcsys.png
+  :align: center
+  :alt: Rocket axes
+
+.. note::
+
+    When ``coordinate_system_orientation`` is set to ``"tail_to_nose"``, the direction
+    of the ``x``, ``y``, and ``z`` axes of the **User Defined Coordinate System** is
+    the same as the **Body Axes Coordinate System**. The orgin of the coordinate
+    system may still be different.
+
+Angular Position Inputs
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Angular position inputs (``angular_position``) refer to the roll angle position
+of that surface along the rocket's tube. The roll angle is defined as the angle 
+from the ``y`` axis to the surface. Currently, only :class:`rocketpy.RailButtons`
+use this input.  
+
+The following figure shows the roll angle
+definition for both ``coordinate_system_orientation`` options:
+
+.. figure:: ../../static/rocket/angularpos.png
+  :align: center
+  :alt: Angular position
+
+
+.. note::
+
+   The positive direction of the roll angle is defined as the direction that 
+   rotates the surface in the positive direction of the ``z`` axis.
+
+
+
+2. Body Axes Coordinate System
+------------------------------
+
+The body axes coordinate system is used inside the simulation to assess the
+governing equations of motion. The body axes coordinate system is defined as follows:
+
+- The origin is at the rocket's center of dry mass (``center_of_dry_mass_position``).
+- The ``z`` axis is defined along the rocket's centerline, pointing from the 
+  center of dry mass towards the nose.
+- The ``x`` and ``y`` axes are perpendicular.
+
+3. Relation to Flight Coordinates
+---------------------------------
+
+The ``Flight`` class uses a coordinate system defined as follows:
+
+- The origin is at the launch rail.
+- The ``Z`` axis is positive upwards.
+- The ``X`` axis is position eastwards.
+- The ``Y`` axis is positive northwards.
+
+The following figure shows the rotational relationship between the
+**Body Axes Coordinate System** and the **Flight Coordinate System**:
+
+.. figure:: ../../static/rocket/flightcsys.png
+  :align: center
+  :alt: Flight coordinate system
+
+In the figure $\bf{i}$** is the ``inclination`` and $\bf{h}$ is the
+``heading`` of the launch rail.
+
+The heading and inclination can be described in terms of Euler angles.
+The relation is given by:
+
+.. math::
+    \begin{aligned}
+        &\text{Precession:} \quad &\psi &= -\bf{h} \\
+        &\text{Nutation:} \quad &\theta &= \bf{i} - 90° \\
+   \end{aligned}
+
+A last rotation is defined by the ``angular_position`` of the rocket's rail buttons.
+This is a rotation around the rocket's centerline, and describes the last 
+Euler angle:
+
+.. math::
+    \begin{aligned}
+        &\text{Spin:} \quad &φ & \\
+    \end{aligned}
+
+If no rail buttons are present, the spin angle is set to **0°**.
+
+.. note::
+
+   With spin angle set to **0°**, if the
+   lauch rail ``heading`` is set to **0°** and rail ``inclination`` to **90°**,
+   the **Body Axes Coordinate System** is aligned with the **Flight Coordinate System**.
+
+
+This is used to calculate the initial orientation of the rocket, which is 
+expressed in Euler parameters (quaternions). The Euler parameters are defined 
+using the 3-1-3 rotation sequence:
+
+.. math::
+
+   \begin{aligned}
+      e₀ &= \cos\left(\frac{φ}{2}\right) \cos\left(\frac{θ}{2}\right) \cos\left(\frac{ψ}{2}\right) - \sin\left(\frac{φ}{2}\right) \cos\left(\frac{θ}{2}\right) \sin\left(\frac{ψ}{2}\right) \\
+      e₁ &= \cos\left(\frac{φ}{2}\right) \cos\left(\frac{ψ}{2}\right) \sin\left(\frac{θ}{2}\right) + \sin\left(\frac{φ}{2}\right) \sin\left(\frac{θ}{2}\right) \sin\left(\frac{ψ}{2}\right) \\
+      e₂ &= \cos\left(\frac{φ}{2}\right) \sin\left(\frac{θ}{2}\right) \sin\left(\frac{ψ}{2}\right) - \sin\left(\frac{φ}{2}\right) \cos\left(\frac{ψ}{2}\right) \sin\left(\frac{θ}{2}\right) \\
+      e₃ &= \cos\left(\frac{φ}{2}\right) \cos\left(\frac{θ}{2}\right) \sin\left(\frac{ψ}{2}\right) + \cos\left(\frac{θ}{2}\right) \cos\left(\frac{ψ}{2}\right) \sin\left(\frac{φ}{2}\right) \\
+   \end{aligned}
+
+

docs/user/rocket.rst → docs/user/rocket/rocket_usage.rst

@@ -210,7 +210,7 @@ to the rocket in one step:
 .. caution::
 
     Again, pay special attention to the ``position`` parameter. See
-    the :ref:`Adding Aerodynamic Surfaces <add_surfaces>` section for
+    the :ref:`Adding Aerodynamic Surfaces <addsurface>` section for
     more information.
 
 .. seealso::

rocketpy/mathutils/vector_matrix.py

@@ -955,6 +955,10 @@ def transformation(quaternion):
         -------
         Matrix
             The transformation matrix from frame B to frame A.
+
+        Reference
+        ---------
+        .. [1] https://en.wikipedia.org/wiki/Conversion_between_quaternions_and_Euler_angles
         """
         q_w, q_x, q_y, q_z = quaternion
         return Matrix(

rocketpy/rocket/aero_surface/fins/elliptical_fins.py

@@ -13,9 +13,10 @@ class EllipticalFins(Fins):
 
     Note
     ----
-    Local coordinate system: Z axis along the longitudinal axis of symmetry,
-    positive downwards (top -> bottom). Origin located at the top of the root
-    chord.
+    Local coordinate system: Origin located at the top of the root chord. Z axis
+    along the longitudinal axis of symmetry, positive downwards (top -> bottom).
+    Y axis perpendicular to the Z axis, in the span direction, positive upwards.
+    X axis completes the right-handed coordinate system.
 
     See Also
     --------

rocketpy/rocket/aero_surface/fins/fins.py

@@ -11,9 +11,10 @@ class Fins(AeroSurface):
 
     Note
     ----
-    Local coordinate system: Z axis along the longitudinal axis of symmetry,
-    positive downwards (top -> bottom). Origin located at the top of the root
-    chord.
+    Local coordinate system: Origin located at the top of the root chord. Z axis
+    along the longitudinal axis of symmetry, positive downwards (top -> bottom).
+    Y axis perpendicular to the Z axis, in the span direction, positive upwards.
+    X axis completes the right-handed coordinate system.
 
     Attributes
     ----------

rocketpy/rocket/aero_surface/fins/trapezoidal_fins.py

@@ -13,9 +13,10 @@ class TrapezoidalFins(Fins):
 
     Note
     ----
-    Local coordinate system: Z axis along the longitudinal axis of symmetry,
-    positive downwards (top -> bottom). Origin located at the top of the root
-    chord.
+    Local coordinate system: Origin located at the top of the root chord. Z axis
+    along the longitudinal axis of symmetry, positive downwards (top -> bottom).
+    Y axis perpendicular to the Z axis, in the span direction, positive upwards.
+    X axis completes the right-handed coordinate system.
 
     See Also
     --------

rocketpy/rocket/aero_surface/rail_buttons.py

@@ -1,3 +1,5 @@
+import numpy as np
+
 from rocketpy.mathutils.function import Function
 from rocketpy.prints.aero_surface_prints import _RailButtonsPrints
 
@@ -39,6 +41,7 @@ def __init__(self, buttons_distance, angular_position=45, name="Rail Buttons"):
         super().__init__(name, None, None)
         self.buttons_distance = buttons_distance
         self.angular_position = angular_position
+        self.angular_position_rad = np.radians(angular_position)
         self.name = name
 
         self.evaluate_lift_coefficient()

rocketpy/rocket/rocket.py

@@ -4,7 +4,7 @@
 
 from rocketpy.control.controller import _Controller
 from rocketpy.mathutils.function import Function
-from rocketpy.mathutils.vector_matrix import Matrix
+from rocketpy.mathutils.vector_matrix import Matrix, Vector
 from rocketpy.motors.motor import EmptyMotor
 from rocketpy.plots.rocket_plots import _RocketPlots
 from rocketpy.prints.rocket_prints import _RocketPrints
@@ -885,7 +885,7 @@ def add_motor(self, motor, position):  # pylint: disable=too-many-statements
 
         See Also
         --------
-        :ref:`add_surfaces`
+        :ref:`addsurface`
 
         Returns
         -------
@@ -950,7 +950,7 @@ def add_surfaces(self, surfaces, positions):
 
         See Also
         --------
-        :ref:`add_surfaces`
+        :ref:`addsurface`
 
         Returns
         -------
@@ -1009,10 +1009,16 @@ def add_tail(
             By tail position, understand the point belonging to the tail which
             is highest in the rocket coordinate system (i.e. the point
             closest to the nose cone).
+        radius : int, float, optional
+            Reference radius of the tail. This is used to calculate lift
+            coefficient. If None, which is default, the rocket radius will
+            be used.
+        name : string
+            Tail name. Default is "Tail".
 
         See Also
         --------
-        :ref:`add_surfaces`
+        :ref:`addsurface`
 
         Returns
         -------
@@ -1041,7 +1047,6 @@ def add_nose(
         along the rocket and its derivative of the coefficient of lift
         in respect to angle of attack.
 
-
         Parameters
         ----------
         length : int, float
@@ -1067,7 +1072,7 @@ def add_nose(
 
         See Also
         --------
-        :ref:`add_surfaces`
+        :ref:`addsurface`
 
         Returns
         -------
@@ -1132,10 +1137,6 @@ def add_trapezoidal_fins(
             By fin set position, understand the point belonging to the root
             chord which is highest in the rocket coordinate system (i.e.
             the point closest to the nose cone tip).
-
-            See Also
-            --------
-            :ref:`add_surfaces`
         cant_angle : int, float, optional
             Fins cant angle with respect to the rocket centerline. Must
             be given in degrees.
@@ -1228,10 +1229,6 @@ def add_elliptical_fins(
             set position, understand the point belonging to the root chord which
             is highest in the rocket coordinate system (i.e. the point
             closest to the nose cone tip).
-
-            See Also
-            --------
-            :ref:`add_surfaces`
         cant_angle : int, float, optional
             Fins cant angle with respect to the rocket centerline. Must be given
             in degrees.
@@ -1254,6 +1251,10 @@ def add_elliptical_fins(
             The tuple's second item is the unit of the angle of attack,
             accepting either "radians" or "degrees".
 
+        See Also
+        --------
+        :ref:`addsurface`
+
         Returns
         -------
         fin_set : EllipticalFins
@@ -1473,7 +1474,11 @@ def add_air_brakes(
             return air_brakes
 
     def set_rail_buttons(
-        self, upper_button_position, lower_button_position, angular_position=45
+        self,
+        upper_button_position,
+        lower_button_position,
+        angular_position=45,
+        radius=None,
     ):
         """Adds rail buttons to the rocket, allowing for the calculation of
         forces exerted by them when the rocket is sliding in the launch rail.
@@ -1498,20 +1503,24 @@ def set_rail_buttons(
             relative to one of the other principal axis.
             Default value is 45 degrees, generally used in rockets with
             4 fins.
+        radius : int, float, optional
+            Fuselage radius where the rail buttons are located.
 
         See Also
         --------
-        :ref:`add_surfaces`
+        :ref:`addsurface`
 
         Returns
         -------
         rail_buttons : RailButtons
             RailButtons object created
         """
+        radius = radius if radius else self.radius
         buttons_distance = abs(upper_button_position - lower_button_position)
         rail_buttons = RailButtons(
             buttons_distance=buttons_distance, angular_position=angular_position
         )
+        self.rail_buttons = Components()
         self.rail_buttons.add(rail_buttons, lower_button_position)
         return rail_buttons