Plotting

missiontools.plotting

Cartopy-backed visualisation helpers.

Functions

plot_ground_track

Spacecraft groundtrack on an Earth map.

plot_coverage_map

Interpolated heatmap of per-point coverage values on an Earth map.

Notes

This subpackage requires cartopy. Install it with:

pip install missiontools[plot]
missiontools.plotting.plot_ground_track(spacecraft, t_start, t_end, step=np.timedelta64(30, 's'), *, ax=None, projection=None, auto_window=False, color='tab:blue', linewidth=1.0, label=None, add_start_marker=True)[source]

Plot the spacecraft groundtrack on an Earth map.

Parameters:

  • spacecraft (Spacecraft) – Spacecraft whose orbit to propagate.

  • t_start (np.datetime64) – Start of the analysis window.

  • t_end (np.datetime64) – End of the analysis window (inclusive).

  • step (np.timedelta64) – Propagation step (default 30 s).

  • ax (GeoAxes, optional) – Existing Cartopy GeoAxes to draw on. A new figure is created if None.

  • projection (cartopy CRS, optional) – Map projection for the new axes. Default ccrs.PlateCarree() (WGS-84 equirectangular). Ignored if ax is provided.

  • auto_window (bool) – If True, set the axes extent to 1.5× the lat/lon range of the groundtrack.

  • color (str) – Track colour (matplotlib colour spec).

  • linewidth (float) – Track line width.

  • label (str, optional) – Legend label for the track line.

  • add_start_marker (bool) – If True, draw a filled circle at the initial sub-satellite point.

Returns:

GeoAxes – The axes on which the track was drawn.

Parameters:

Examples

import numpy as np
from missiontools import Spacecraft
from missiontools.plotting import plot_ground_track

sc = Spacecraft(a=6_771_000., e=0., i=np.radians(51.6),
                raan=0., arg_p=0., ma=0.,
                epoch=np.datetime64('2025-01-01', 'us'))

t0 = np.datetime64('2025-01-01', 'us')
ax = plot_ground_track(sc, t0, t0 + np.timedelta64(5400, 's'))
missiontools.plotting.plot_coverage_map(aoi, values, *, ax=None, projection=None, auto_window=False, cmap='viridis', vmin=None, vmax=None, colorbar=True, colorbar_label='', title='', grid_resolution=200)[source]

Interpolated heatmap of per-point values from an AoI on an Earth map.

Parameters:

  • aoi (AoI) – Area of interest (provides lat/lon of ground sample points).

  • values (array_like, shape (M,)) – Per-point scalar values — e.g. coverage fraction, revisit time, or any quantity aligned with the AoI sample points.

  • ax (GeoAxes, optional) – Existing Cartopy GeoAxes. A new figure is created if None.

  • projection (cartopy CRS, optional) – Map projection for the new axes. Default ccrs.PlateCarree() (WGS-84 equirectangular). Ignored if ax is provided.

  • auto_window (bool) – If True, set the axes extent to 1.5× the AoI lat/lon bounding box.

  • cmap (str) – Matplotlib colormap name (default 'viridis').

  • vmin, vmax (float, optional) – Colormap limits. Defaults to the data min/max (ignoring NaN).

  • colorbar (bool) – Add a colorbar to the figure (default True).

  • colorbar_label (str) – Label for the colorbar axis.

  • title (str) – Axes title.

  • grid_resolution (int) – Number of grid points per axis for the interpolation grid (default 200).

Returns:

GeoAxes – The axes on which the map was drawn.

Raises:

ValueError – If len(values) != len(aoi).

Parameters:

  • values (ArrayLike)

  • auto_window (bool)

  • cmap (str)

  • vmin (float | None)

  • vmax (float | None)

  • colorbar (bool)

  • colorbar_label (str)

  • title (str)

  • grid_resolution (int)

Examples

import numpy as np
from missiontools import Spacecraft, Sensor, AoI, Coverage
from missiontools.plotting import plot_coverage_map

sc     = Spacecraft(a=6_771_000., e=0., i=np.radians(51.6),
                    raan=0., arg_p=0., ma=0.,
                    epoch=np.datetime64('2025-01-01', 'us'))
sensor = Sensor(30.0, body_vector=[0, 0, 1])
sc.add_sensor(sensor)

aoi = AoI.from_region(-60, 60, -180, 180)
cov = Coverage(aoi, [sensor])

result = cov.coverage_fraction(
    np.datetime64('2025-01-01', 'us'),
    np.datetime64('2025-01-02', 'us'),
)
ax = plot_coverage_map(aoi, result['final_cumulative'],
                       colorbar_label='Coverage fraction',
                       title='24-hour coverage')