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: Air brakes controller functions now support 8-parameter signature [#854](https://github.com/RocketPy-Team/RocketPy/pull/854)
 - TST: Add acceptance tests for 3DOF flight simulation based on Bella Lui rocket [#914] (https://github.com/RocketPy-Team/RocketPy/pull/914_
 - ENH: Add background map auto download functionality to Monte Carlo plots [#896](https://github.com/RocketPy-Team/RocketPy/pull/896)

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,51 @@ Flight Data Plots
     # Flight path and orientation
     flight.plots.flight_path_angle_data()
 
+3D Flight Animation
+~~~~~~~~~~~~~~~~~~~
+
+RocketPy can animate the simulated flight trajectory and attitude through the
+Flight plots layer.
+
+.. note::
+
+    Install optional animation dependencies first:
+
+    .. code-block:: bash
+
+        pip install rocketpy[animation]
+
+.. code-block:: python
+
+    # Fast start using RocketPy's built-in default STL model
+    flight.plots.animate_trajectory(
+        start=0.0,
+        stop=min(flight.t_final, 20.0),
+        time_step=0.05,
+    )
+
+    # Or provide your own STL model file
+    flight.plots.animate_trajectory(
+        file_name="rocket.stl",
+        start=0.0,
+        stop=flight.t_final,
+        time_step=0.05,
+        azimuth=45,
+        elevation=20,
+    )
+
+    # Keep rocket centered and animate only attitude changes
+    flight.plots.animate_rotate(
+        file_name="rocket.stl",
+        start=0.0,
+        stop=min(flight.t_final, 20.0),
+        time_step=0.05,
+    )
+
+Both methods validate the selected time interval and STL path before rendering.
+If ``vedo`` is not installed, RocketPy raises an informative ``ImportError``
+with installation instructions.
+
 Forces and Moments
 ~~~~~~~~~~~~~~~~~~
 

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

requirements.txt

@@ -2,7 +2,7 @@ numpy>=1.13
 scipy>=1.0
 matplotlib>=3.9.0  # Released May 15th 2024
 netCDF4>=1.6.4
-requests
-pytz
+requests>=2.25.0
+pytz>=2020.1
 simplekml
 dill

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