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)

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:

• t_start (datetime64)

• t_end (datetime64)

• step (timedelta64)

• auto_window (bool)

• color (str)

• linewidth (float)

• label (str | None)

• add_start_marker (bool)

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)

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')