Spacecraft Trajectory Extraction and Visualization

This repository contains tools for extracting / visualizing the trajectory of a Spacecraft in a SPICE kernel file like somename_somedate_someversion.bsp

Setup

1. Install Dependencies

# You should probably do this in a venv!
python -m venv .venv
source .venv/bin/activate

# Upgrade pip if required
pip install --upgrade pip

# Now fetch the python libraries we need
pip install -r requirements.txt

And get the SPICE from NASA (one time only)

# Leapseconds kernel (time conversions)
wget https://naif.jpl.nasa.gov/pub/naif/generic_kernels/lsk/naif0012.tls

# Planetary constants kernel
wget https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/pck00010.tpc

# Planetary ephemeris kernel (Sun, Earth, etc. positions). Watch out thats 128mb +
wget https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/de430.bsp

2. Run Scripts

explore_kernel.py

Explore the SPICE kernel to see what trajectory data is available.

python explore_kernel.py <name_of_kernel.bsp>

Output includes:

• Spacecraft ID (NAIF ID)
• Time coverage intervals
• Duration of available data

extract_trajectory.py

Extract spacecraft trajectory data from the SPICE kernel in J2000 frame with the SUN as observer at [0,0,0].

Usage:

python extract_trajectory.py <kernel.bsp> [--start-date YYYYMMDD] [--end-date YYYYMMDD] [--interval SECONDS]

Parameters:

• <kernel.bsp>: Path to the SPICE kernel file containing trajectory information
• --start-date: Start date in YYYYMMDD format (default: 20250101)
• --end-date: End date in YYYYMMDD format (default: 20500101)
• --interval: Time interval in seconds (default: 86400 for daily)
  • Daily: 86400
  • Hourly: 3600
  • 10-day: 864000 etc.

Examples:

# Extract full available trajectory with daily data points
python extract_trajectory.py somename_somedate_someversion.bsp

# Extract specific date range in J2000 frame
python extract_trajectory.py somename_somedate_someversion.bsp --start-date 20251112 --end-date 20260228

# Extract with hourly data points
python extract_trajectory.py somename_somedate_someversion.bsp --interval 3600

Output:

• trajectory_data.json: Position data for Sun, Earth, and the spacecraft in question

plot_trajectory.py

Create png plots from extracted spacecraft trajectory data.

Usage:

python plot_trajectory.py [--start-date YYYYMMDD] [--end-date YYYYMMDD]

Parameters:

• --start-date: Start date in YYYYMMDD format (default: 20250101)
• --end-date: End date in YYYYMMDD format (default: 20500101)

Examples:

# Plot all data from trajectory_data.json
python plot_trajectory.py

# Plot specific date range and plots show the name of the spacecraft
python plot_trajectory.py --start-date 20251201 --end-date 20260301 --name "NASA IMAP"

Output:

• trajectory_details.png: 4-panel analysis (XY, XZ, YZ planes + distance-time graph)
• trajectory_simple.png: Plot with centered Sun (orange), Earth (blue), Spacecraft (black)

orbit_visualizer.html

Interactive 3D web-based visualization of the spacecraft trajectory file trajectory_data.json you have created above.

Usage:

1. Ensure trajectory_data.json is in the same directory as orbit_visualizer.html
2. Run a local web server, e.g., using Python:

   python -m http.server 8000

3. Open orbit_visualizer.html in a browser at http://localhost:8000/orbit_visualizer.html

Features:

• 3D Orbit View: Interactive 3D visualization of Sun, Earth, and spacecraft orbits
• Time Navigation: Slider to navigate through mission timeline
• Playback Controls: Play/pause animation with adjustable speed
• Camera Controls:
  • Mouse drag to rotate view
  • Mouse wheel to zoom in/out
  • Reset button to return to default view

Controls:

• Drag: Rotate the view
• Scroll: Zoom in/out