Sky Pointing Visualization

An interactive visualization tool for spacecraft pointing visualization on a mollweide sky projection.

Features

Interactive Mollweide Projection: Full-sky view with spacecraft pointing and observations
Scheduled Observations: All planned targets marked on the sky with color-coding by priority
Constraint Regions: Shaded areas showing Sun, Moon, Earth, Anti-Sun, and Solar Panel constraints
Current Pointing: Highlighted marker showing where the spacecraft is currently pointing
Time Controls:
- Slider to jump to any time
- Previous/Next buttons to step through time
- Play button to animate through the entire DITL
Frame Export: Save individual frames for creating animations or presentations

Quick Start

from conops import DITL, MissionConfig
from conops.visualization import plot_sky_pointing
import matplotlib.pyplot as plt

# Load configuration and create DITL
config = MissionConfig.from_json('config.json')
ditl = DITL(config)

# Run simulation
ditl.calc()

# Create interactive visualization
fig, ax, controller = plot_sky_pointing(
    ditl,
    figsize=(14, 8),
    show_controls=True,
)

plt.show()

Usage

Basic Visualization

# Simple static plot at the first time step
fig, ax, _ = plot_sky_pointing(
    ditl,
    show_controls=False,  # No interactive controls
)

Interactive Visualization

# Full interactive plot with controls
%matplotlib widget  # For Jupyter notebooks

fig, ax, controller = plot_sky_pointing(
    ditl,
    figsize=(14, 8),
    n_grid_points=100,  # Higher = more accurate constraints, slower
    show_controls=True,
    constraint_alpha=0.3,  # Transparency of constraint regions
)

Customization

fig, ax, controller = plot_sky_pointing(
    ditl,
    figsize=(16, 10),           # Larger figure
    n_grid_points=50,            # Faster rendering
    time_step_seconds=120,       # Step by 2 minutes
    constraint_alpha=0.2,        # More transparent constraints
)

Saving Frames

from conops.visualization import save_sky_pointing_frames

# Save every 10th frame
saved_files = save_sky_pointing_frames(
    ditl,
    output_dir='./sky_frames',
    n_grid_points=50,
    frame_interval=10,
)

# Create animation with imageio
import imageio
frames = [imageio.imread(f) for f in saved_files]
imageio.mimsave('sky_pointing.gif', frames, fps=10)

Visualization Elements

Observation Markers

Scheduled observations are shown as colored circles:

Red (large): TOO/GRB targets (obsid >= 1,000,000)
Orange (medium): High priority targets (obsid >= 20,000)
Yellow (medium): Survey targets (obsid >= 10,000)
Light Blue (small): Standard targets

Current Pointing

Red Star: Current spacecraft pointing direction
Red Circle: Emphasizes the current pointing region

Constraint Regions

Color-coded shaded areas showing forbidden pointing regions:

Yellow: Sun constraint zone (too close to Sun)
Gray: Moon constraint zone (too close to Moon)
Blue: Earth limb constraint (pointing too close to Earth)
Orange: Anti-Sun constraint (solar panel limitations)
Green: Solar panel constraint (power generation limitations)

Celestial Bodies

Large circular markers show the current position of:

Sun (yellow with black edge)
Moon (gray with black edge)
Earth (blue with black edge)

Interactive Controls

When show_controls=True:

Time Slider: Drag to jump to any point in the simulation
< Prev Button: Step backward one time step
Next > Button: Step forward one time step
Play Button: Automatically advance through time (becomes “Pause” when playing)

Performance Tips

Lower n_grid_points (e.g., 30-50) for faster rendering during exploration
Increase n_grid_points (e.g., 100-200) for publication-quality figures
Use frame_interval > 1 when saving many frames to reduce file count
The constraint calculation is the slowest part; consider caching results for animations

Example Workflows

Interactive Exploration

# Use in Jupyter notebook for interactive exploration
%matplotlib widget

fig, ax, ctrl = plot_sky_pointing(ditl, n_grid_points=50)

# Play through the simulation
# Use the Play button or call programmatically:
# ctrl.start_animation()

Publication Figures

# High-quality static image at specific time
fig, ax, ctrl = plot_sky_pointing(
    ditl,
    show_controls=False,
    n_grid_points=150,
    figsize=(12, 8),
)

# Update to specific time
specific_time = ditl.utime[500]  # e.g., 500th timestep
ctrl.update_plot(specific_time)

# Save figure
fig.savefig('spacecraft_pointing.pdf', dpi=300, bbox_inches='tight')

Movie Export

You can export sky pointing visualizations as animated movies showing how the spacecraft pointing and constraints evolve throughout the DITL simulation. The save_sky_pointing_movie() function supports multiple output formats:

from conops.visualization import save_sky_pointing_movie

# Export as MP4 video (requires ffmpeg)
save_sky_pointing_movie(
    ditl,
    "pointing.mp4",
    fps=15,  # frames per second
    frame_interval=5,  # use every 5th time step
    n_grid_points=30,  # constraint grid resolution
    dpi=100  # output resolution
)

# Export as animated GIF (requires pillow)
save_sky_pointing_movie(
    ditl,
    "pointing.gif",
    fps=5,
    frame_interval=10
)

API Reference

plot_sky_pointing()

Main visualization function.

Parameters:

ditl: DITL or QueueDITL object (must have run calc() first)
figsize: tuple, figure size (width, height) in inches
n_grid_points: int, resolution for constraint calculations (default: 100)
show_controls: bool, add interactive controls (default: True)
time_step_seconds: float, time step for controls (default: ditl.step_size)
constraint_alpha: float, transparency for constraint regions (default: 0.3)

Returns:

fig: matplotlib Figure
ax: matplotlib Axes (mollweide projection)
controller: SkyPointingController or None

save_sky_pointing_frames()

Save individual frames to disk.