Ground Track Plotting¶

plot_groundtrack ¶

plot_groundtrack(trajectories=None, ground_stations=None, zones=None, gs_cone_altitude=500000.0, gs_min_elevation=10.0, basemap='natural_earth', show_borders=True, show_coastlines=True, border_width=0.5, show_grid=False, show_ticks=True, show_legend=False, extent=None, backend='matplotlib') -> object

Plot ground tracks with optional ground stations and polygon zones.

Parameters:

Name	Type	Description	Default
`trajectories`	`list of dict`	List of trajectory groups, each with: - trajectory: OrbitTrajectory or numpy array - color (str, optional): Line color - line_width (float, optional): Line width - track_length (float, optional): Length of track to display - track_units (str, optional): Units for track_length - "orbits" or "seconds". Default: "orbits"	`None`
`ground_stations`	`list of dict`	List of ground station groups, each with: - stations: List of PointLocation or (lat, lon) tuples - color (str, optional): Station and cone color - alpha (float, optional): Cone transparency - point_size (float, optional): Station marker size - show_ring (bool, optional): Show outer ring - ring_color (str, optional): Ring color - ring_width (float, optional): Ring line width	`None`
`zones`	`list of dict`	List of polygon zone groups, each with: - zone: PolygonLocation - fill (bool, optional): Fill interior - fill_alpha (float, optional): Fill transparency - fill_color (str, optional): Fill color - edge (bool, optional): Show edge - edge_color (str, optional): Edge color - points (bool, optional): Show vertices	`None`
`gs_cone_altitude`	`float`	Assumed satellite altitude for cone calculation (m). Default: 500e3	`500000.0`
`gs_min_elevation`	`float`	Minimum elevation angle (degrees). Default: 10.0	`10.0`
`basemap`	`str`	Basemap style - "natural_earth", "stock", or None. Default: "natural_earth"	`'natural_earth'`
`show_borders`	`bool`	Show country borders. Default: True	`True`
`show_coastlines`	`bool`	Show coastlines. Default: True	`True`
`border_width`	`float`	Border line width. Default: 0.5	`0.5`
`show_grid`	`bool`	Show lat/lon grid. Default: False	`False`
`show_ticks`	`bool`	Show lat/lon tick marks. Default: True	`True`
`show_legend`	`bool`	Show legend (plotly only). Default: False	`False`
`extent`	`list`	[lon_min, lon_max, lat_min, lat_max] to zoom. Default: None (global)	`None`
`backend`	`str`	'matplotlib' or 'plotly'. Default: 'matplotlib'	`'matplotlib'`

Returns:

Type	Description
`object`	Generated figure object

Example

import brahe as bh
import numpy as np

# Create a simple LEO trajectory
eop = bh.FileEOPProvider.from_default_standard(bh.EarthOrientationFileType.STANDARD, True)
bh.set_global_eop_provider(eop)

epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)
oe = np.array([bh.R_EARTH + 500e3, 0.01, np.radians(97.8), 0.0, 0.0, 0.0])
state = bh.state_koe_to_eci(oe, bh.AngleFormat.RADIANS)

prop = bh.KeplerianPropagator.from_eci(epoch, state, 60.0)
traj = prop.propagate(epoch, epoch + 2*bh.orbital_period(oe[0]), 60.0)

# Define ground stations
stations_aws = [
    bh.PointLocation(np.radians(40.7128), np.radians(-74.0060), 0.0),  # NYC
    bh.PointLocation(np.radians(37.7749), np.radians(-122.4194), 0.0),  # SF
]

stations_ksat = [
    bh.PointLocation(np.radians(78.2232), np.radians(15.6267), 0.0),  # Svalbard
]

# Plot with per-group configuration
fig = bh.plot_groundtrack(
    trajectories=[{"trajectory": traj, "color": "red", "track_length": 2, "track_units": "orbits"}],
    ground_stations=[
        {"stations": stations_aws, "color": "orange", "alpha": 0.3},
        {"stations": stations_ksat, "color": "blue", "alpha": 0.3},
    ],
    gs_cone_altitude=500e3,
    gs_min_elevation=10.0,
    backend='matplotlib'
)

split_ground_track_at_antimeridian ¶

split_ground_track_at_antimeridian(lons, lats, value: float = 180.0) -> List[Tuple]

Split a ground track into segments at antimeridian crossings.

When a satellite ground track crosses the antimeridian (±180° longitude), plotting libraries may draw an incorrect line across the entire map. This function detects such crossings and splits the track into separate segments that can be plotted individually.

Parameters:

Name	Type	Description	Default
`lons`	`list or ndarray`	Longitude values in degrees	required
`lats`	`list or ndarray`	Latitude values in degrees (same length as lons)	required
`value`	`float`	Longitude jump value in degrees to detect wraparound. Default: 180.0	`180.0`

Returns:

Type	Description
`List[Tuple]`	List[Tuple]: List of (lon_segment, lat_segment) tuples, where each tuple contains arrays for one continuous segment

Example

import brahe as bh
import numpy as np

# Ground track that crosses antimeridian
lons = [170, 175, 180, -175, -170]
lats = [10, 15, 20, 25, 30]

# Split into segments
segments = bh.split_ground_track_at_antimeridian(lons, lats)

# Plot each segment
import matplotlib.pyplot as plt
for lon_seg, lat_seg in segments:
    plt.plot(lon_seg, lat_seg)