OrbitalSimulator/PLOTTING.md

Trajectory Plotting

This Python script can read and visualize the binary trajectory files generated by the orbital simulator.

Installation

First, install the required Python dependencies:

pip install -r requirements.txt

Usage

Basic Usage

# Plot trajectories from a simulation output file
python plot_trajectories.py trajectory_output.bin

Options

• --2d-only: Only show 2D plot (X-Y plane)
• --3d-only: Only show 3D plot
• --energy: Also show energy conservation plot
• --animate: Show animated trajectories with real-time simulation
• --save-animation <filename>: Save animation as MP4 file (requires ffmpeg)
• --static: Show static plots (default behavior)
• --interval <ms>: Animation frame interval in milliseconds (default: auto-scaled)
• --target-duration <seconds>: Target animation duration (default: 60)
• --center <body_name>: Center animation/plot on specified body (e.g., "Sun", "Earth")
• --list-bodies: List available bodies in trajectory file and exit

Examples

# Run a simulation and plot the results
cargo run --bin simulator -- --config config/planets.json --time 365d --step-size 3600 --output-file solar_system.bin
python plot_trajectories.py solar_system.bin

# List available bodies in trajectory file
python plot_trajectories.py solar_system.bin --list-bodies

# Show animated trajectories centered on the Sun
python plot_trajectories.py solar_system.bin --animate --center Sun

# Show Earth-centered view (great for seeing Moon's orbit)
python plot_trajectories.py solar_system.bin --animate --center Earth --2d-only

# Show only 2D animation with custom speed
python plot_trajectories.py solar_system.bin --animate --2d-only --interval 100

# Save animation as MP4 file (Sun-centered)
python plot_trajectories.py solar_system.bin --animate --center Sun --save-animation solar_system_animation

# Show 3D trajectories with energy plot (static, Earth-centered)
python plot_trajectories.py solar_system.bin --3d-only --energy --static --center Earth

Output

The script can display:

Static Plots

• 2D Plot: Trajectories in the X-Y plane with starting positions (circles) and ending positions (squares)
• 3D Plot: Full 3D orbital trajectories
• Energy Plot (optional): Shows kinetic and total energy over time to verify energy conservation

Animated Plots

• 2D Animation: Real-time orbital motion in the X-Y plane with time display
• 3D Animation: Full 3D animated orbital trajectories
• Time Display: Shows current simulation time in seconds/hours/days
• Trails: Recent positions shown as fading trails behind each body
• MP4 Export: Save animations as video files (requires ffmpeg)

Each celestial body is plotted in a different color with its name in the legend.

File Format

The binary trajectory file contains serialized snapshots with:

• Timestamp (f64)
• Array of bodies, each containing:
  • Name (String)
  • Mass (f64)
  • Position (3x f64)
  • Velocity (3x f64)
  • Acceleration (3x f64)