feat: Implement 3D flight animation methods using Vedo (Issue #523)

CHANGELOG.md

@@ -32,6 +32,7 @@ Attention: The newest changes should be on top -->
 
 ### Added
 
+- ENH: Add 3D flight trajectory and attitude animations in Flight plots layer [#909](https://github.com/RocketPy-Team/RocketPy/pull/909)
 - ENH: Auto Populate Changelog [#919](https://github.com/RocketPy-Team/RocketPy/pull/919)
 - ENH: Adaptive Monte Carlo via Convergence Criteria [#922](https://github.com/RocketPy-Team/RocketPy/pull/922)
 - TST: Add acceptance tests for 3DOF flight simulation based on Bella Lui rocket [#914](https://github.com/RocketPy-Team/RocketPy/pull/914)

docs/notebooks/getting_started_colab.ipynb

@@ -596,6 +596,18 @@
     ")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "source": "## 3D Flight Animation\n\nRocketPy can render an interactive 3D animation of the rocket's trajectory and attitude using [vedo](https://vedo.embl.es/). This feature requires the optional `animation` extra:\n\n```bash\npip install rocketpy[animation]\n```\n\n> **Note:** The interactive animation window opens in a desktop environment. It will not display inside Google Colab or other headless notebook servers — run it locally for the best experience.\n\nTwo animation modes are available:\n\n| Method | What it shows |\n|---|---|\n| `flight.plots.animate_trajectory()` | Rocket moves through 3D space following the simulated trajectory |\n| `flight.plots.animate_rotate()` | Rocket stays centred; only attitude (rotation) is animated |\n\nBoth methods accept an optional `file_name` argument pointing to a custom `.stl` model. When omitted, RocketPy uses a built-in default rocket shape.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "source": "# Install the optional animation dependency (skip if already installed)\n!pip install \"rocketpy[animation]\"\n\n# Animate the full trajectory — rocket moves through 3D space\n# Press Escape or close the window to exit the animation\ntest_flight.plots.animate_trajectory(\n    start=0,\n    stop=test_flight.t_final,\n    time_step=0.05,\n)\n\n# Alternatively, animate only the attitude changes (rocket stays centred)\n# test_flight.plots.animate_rotate(\n#     start=0,\n#     stop=test_flight.t_final,\n#     time_step=0.05,\n# )\n\n# To use your own 3D model, pass its path via file_name:\n# test_flight.plots.animate_trajectory(file_name=\"my_rocket.stl\")",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
   {
    "attachments": {},
    "cell_type": "markdown",

docs/user/flight.rst

@@ -274,15 +274,15 @@ During the rail launch phase, RocketPy calculates reaction forces and internal b
 **Rail Button Forces (N):**
 
 - ``rail_button1_normal_force`` : Normal reaction force at upper rail button
-- ``rail_button1_shear_force`` : Shear (tangential) reaction force at upper rail button  
+- ``rail_button1_shear_force`` : Shear (tangential) reaction force at upper rail button
 - ``rail_button2_normal_force`` : Normal reaction force at lower rail button
 - ``rail_button2_shear_force`` : Shear (tangential) reaction force at lower rail button
 
 **Rail Button Bending Moments (N⋅m):**
 
 - ``rail_button1_bending_moment`` : Time-dependent bending moment at upper rail button attachment
 - ``max_rail_button1_bending_moment`` : Maximum absolute bending moment at upper rail button
-- ``rail_button2_bending_moment`` : Time-dependent bending moment at lower rail button attachment  
+- ``rail_button2_bending_moment`` : Time-dependent bending moment at lower rail button attachment
 - ``max_rail_button2_bending_moment`` : Maximum absolute bending moment at lower rail button
 
 **Calculation Method:**
@@ -454,6 +454,122 @@ Flight Data Plots
     # Flight path and orientation
     flight.plots.flight_path_angle_data()
 
+3D Flight Animation
+~~~~~~~~~~~~~~~~~~~
+
+RocketPy can produce real-time interactive 3D animations of the simulated
+flight using `vedo <https://vedo.embl.es/>`_, a scientific visualization
+library built on top of VTK.  Two complementary animation modes are provided:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Method
+     - What it shows
+   * - ``flight.plots.animate_trajectory()``
+     - The rocket 3D model moves through space following the simulated
+       trajectory; a black trail line is drawn behind it.
+   * - ``flight.plots.animate_rotate()``
+     - The rocket 3D model stays centred in the scene; only its attitude
+       (orientation derived from the quaternion solution) is animated.
+
+.. note::
+
+    The animation window opens on the desktop via VTK.  It will **not** render
+    inside headless environments such as Google Colab.  For notebook use, run
+    the cell on a local Jupyter server or JupyterLab installation.
+
+**Installation**
+
+The ``vedo`` dependency is not installed by default.  Add the optional extra
+before calling either animation method:
+
+.. code-block:: bash
+
+    pip install rocketpy[animation]
+
+If ``vedo`` is not available when an animation method is called, RocketPy
+raises an :class:`ImportError` with the above install command embedded in the
+message.
+
+**animate_trajectory — full 6-DOF trajectory animation**
+
+.. code-block:: python
+
+    # Quickstart: uses RocketPy's built-in default STL rocket model
+    flight.plots.animate_trajectory()
+
+    # Customise the time window and frame rate
+    flight.plots.animate_trajectory(
+        start=0.0,                    # start time in seconds (default: 0)
+        stop=flight.t_final,          # end time in seconds (default: t_final)
+        time_step=0.05,               # seconds per frame (default: 0.1)
+    )
+
+    # Provide your own 3D model (any STL file)
+    flight.plots.animate_trajectory(
+        file_name="my_rocket.stl",
+        start=0.0,
+        stop=flight.t_final,
+        time_step=0.05,
+    )
+
+**animate_rotate — attitude-only animation**
+
+Useful for inspecting roll, pitch, and yaw behaviour without the distraction of
+the trajectory translation.  The rocket mesh is fixed at its position at
+``start`` and only rotated according to the quaternion solution.
+
+.. code-block:: python
+
+    flight.plots.animate_rotate(
+        start=0.0,
+        stop=flight.t_final,
+        time_step=0.05,
+    )
+
+**Parameters**
+
+Both methods share the same signature:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 15 65
+
+   * - Parameter
+     - Default
+     - Description
+   * - ``file_name``
+     - ``None``
+     - Path to a ``.stl`` model file.  When ``None``, the built-in default
+       rocket shape packaged with RocketPy is used.
+   * - ``start``
+     - ``0``
+     - Animation start time in seconds.  Must be within
+       ``[0, flight.t_final]``.
+   * - ``stop``
+     - ``None``
+     - Animation end time in seconds.  ``None`` defaults to
+       ``flight.t_final``.
+   * - ``time_step``
+     - ``0.1``
+     - Duration of each frame in seconds.  Smaller values produce smoother
+       animations at the cost of longer render times.  Must be > 0.
+   * - ``**kwargs``
+     - —
+     - Additional keyword arguments forwarded to ``vedo.Plotter.show``
+       (e.g. ``viewup``, ``azimuth``, ``elevation``).
+
+**Tips**
+
+- A ``time_step`` of ``0.05`` (20 fps) is a good balance between smoothness
+  and performance for flights lasting tens of seconds.
+- Press **Escape** or close the vedo window to exit the animation loop early.
+- Both methods validate ``start``, ``stop``, ``time_step``, and the STL path
+  before any rendering begins, raising a :class:`ValueError` with a descriptive
+  message on invalid input.
+
 Forces and Moments
 ~~~~~~~~~~~~~~~~~~
 

docs/user/installation.rst

@@ -138,22 +138,40 @@ To update Scipy and install netCDF4 using Conda, the following code is used:
 Optional Packages
 ^^^^^^^^^^^^^^^^^
 
-The EnvironmentAnalysis class requires a few extra packages to be installed.
-In case you want to use this class, you will need to install the following packages:
+RocketPy has several optional feature sets that can be installed individually.
 
-- `timezonefinder` : to allow for automatic timezone detection,
-- `windrose` : to allow for windrose plots,
-- `ipywidgets` : to allow for GIFs generation,
-- `jsonpickle` : to allow for saving and loading of class instances.
+**Environment Analysis** — extra plots and tools for the
+:class:`rocketpy.EnvironmentAnalysis` class:
 
-You can install all these packages by simply running the following lines in your preferred terminal:
+- `timezonefinder` : automatic timezone detection
+- `windrose` : windrose plots
+- `ipywidgets` : GIF generation
+- `jsonpickle` : saving and loading class instances
 
 .. code-block:: shell
 
     pip install rocketpy[env_analysis]
 
+**3D Flight Animation** — interactive 3D animations of rocket trajectory and
+attitude using `vedo <https://vedo.embl.es/>`_ (requires a desktop environment):
 
-Alternatively, you can instal all extra packages by running the following line in your preferred terminal:
+.. code-block:: shell
+
+    pip install rocketpy[animation]
+
+Once installed, you can render animations from a :class:`rocketpy.Flight` object:
+
+.. code-block:: python
+
+    # Animate rocket moving through 3D space
+    flight.plots.animate_trajectory(start=0, stop=flight.t_final, time_step=0.05)
+
+    # Animate attitude changes only (rocket stays centred)
+    flight.plots.animate_rotate(start=0, stop=flight.t_final, time_step=0.05)
+
+See :ref:`flightusage` for full details and parameter descriptions.
+
+**All extras** — install every optional dependency at once:
 
 .. code-block:: shell
 

pyproject.toml

@@ -34,6 +34,9 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools]
 packages = { find = { where = ["."], include = ["rocketpy*"] } }
 
+[tool.setuptools.package-data]
+"rocketpy.plots" = ["assets/*.stl"]
+
 
 [tool.setuptools.dynamic]
 dependencies = { file = ["requirements.txt"] }
@@ -61,14 +64,18 @@ env-analysis = [
 ]
 
 monte-carlo = [
-    "imageio", 
+    "imageio",
     "multiprocess>=0.70",
     "statsmodels",
     "prettytable",
     "contextily>=1.0.0; python_version < '3.14'",
 ]
 
-all = ["rocketpy[env-analysis]", "rocketpy[monte-carlo]"]
+animation = [
+    "vedo>=2024.5.1"
+]
+
+all = ["rocketpy[env-analysis]", "rocketpy[monte-carlo]", "rocketpy[animation]"]
 
 
 [tool.coverage.report]

requirements-optional.txt

@@ -6,4 +6,5 @@ timezonefinder
 imageio
 multiprocess>=0.70
 statsmodels
-prettytable
+prettytable
+vedo>=2024.5.1

rocketpy/plots/assets/default_rocket.stl

@@ -0,0 +1,16 @@
+solid default_rocket
+  facet normal 0 0 1
+    outer loop
+      vertex 0 0 0
+      vertex 1 0 0
+      vertex 0 1 0
+    endloop
+  endfacet
+  facet normal 0 0 -1
+    outer loop
+      vertex 0 0 0
+      vertex 0 1 0
+      vertex 1 0 0
+    endloop
+  endfacet
+endsolid default_rocket