arguslib.aircraft package

class arguslib.aircraft.AircraftInterface(camera, fleet=None)

Bases: PlottableInstrument

An interface for visualizing aircraft flight tracks on a plottable instrument.

This class acts as a wrapper around another PlottableInstrument (like a Camera or CameraArray) and a Fleet object containing flight data. Its primary role is to orchestrate the plotting of the underlying instrument’s view and then overlaying the aircraft trails and positions on top of it.

Because it inherits from PlottableInstrument, it can be used interchangeably wherever a plottable object is expected, allowing for powerful composition (e.g., wrapping an AircraftInterface inside a RadarInterface).

camera

The underlying instrument to draw on. Despite the name, this can be any PlottableInstrument.

Type:

PlottableInstrument

fleet

The object managing the aircraft data.

Type:

Fleet

annotate_positions(positions, dt, ax, *args, **kwargs)

Annotates one or more geographical positions on the instrument’s plot.

Parameters:

• positions (list[Position]) – A list of Position objects to annotate.

• dt (datetime.datetime) – The datetime for which the view is valid.

• ax (matplotlib.axes.Axes) – The axis (or axes) to plot on.

• **kwargs – Keyword arguments passed to the underlying plotting function (e.g., ax.plot or ax.scatter).

Returns:

The updated axis (or axes).

Return type:

matplotlib.axes.Axes

classmethod from_campaign(campaign, camstr)

get_trail_positions(timestamp, icao_include=None, **kwargs)

get_trails(time, **kwargs)

property image

If the underlying camera is a DirectCamera, this property accesses its image property.

load_flight_data(date_or_dt, adsb_data_dir=None)

Loads ADS-B flight data for the specified date from the given directory and assigns ERA5 wind data to the fleet.

Parameters:

• date_or_dt (Union[date, datetime]) – The date (or datetime object) for which to load data.

• adsb_data_dir (Union[str, Path]) – The directory containing the ADS-B data files (e.g., YYYYMMDD_ADS-B.nc and YYYYMMDD_ADS-B.txt).

Raises:

• TypeError – If date_or_dt is not a datetime.date or datetime.datetime object.

• FileNotFoundError – If the ADS-B data directory or necessary files are not found.

plot_trails(dt, ax, adjust_km=(0, 0), adjust_mps=(0, 0), color_icao=True, label_acft=False, icao_include=None, plot_kwargs={}, plot_trails_kwargs={}, plot_plane_kwargs={}, advection_winds='era5', **kwargs)

show(dt, ax=None, tlen=3600, color_icao=False, trail_kwargs={}, **kwargs)

Renders the instrument’s primary visualization for a given time.

Parameters:

• dt (datetime.datetime) – The timestamp for the visualization.

• ax (matplotlib.axes.Axes, optional) – The axis to plot on. If None, a new figure and axis are typically created. For some instruments that render directly to images (like DirectCamera), this may be ignored or required to be None.

• **kwargs – Additional keyword arguments specific to the instrument’s plotting implementation.

Returns:

The axis (or array of axes) on which the visualization was drawn. May be None for non-Matplotlib backends.

Return type:

matplotlib.axes.Axes

to_image_array(time=True)

If the underlying camera is a DirectCamera, this method calls its to_image_array() method. This is typically called after self.show() has prepared the image (including any trails).

class arguslib.aircraft.AutomaticADSBAircraftInterface(camera)

Bases: AircraftInterface

show(dt, *args, **kwargs)

Renders the instrument’s primary visualization for a given time.

Parameters:

• dt (datetime.datetime) – The timestamp for the visualization.

• ax (matplotlib.axes.Axes, optional) – The axis to plot on. If None, a new figure and axis are typically created. For some instruments that render directly to images (like DirectCamera), this may be ignored or required to be None.

• **kwargs – Additional keyword arguments specific to the instrument’s plotting implementation.

Returns:

The axis (or array of axes) on which the visualization was drawn. May be None for non-Matplotlib backends.

Return type:

matplotlib.axes.Axes

class arguslib.aircraft.Fleet(time_resolution=15, variables=['lon', 'lat', 'alt_geom'])

Bases: object

add_data(dtime, acdata)

assign_era5_winds(_download_attempted_this_call=False)

Pre-calculates and assigns ERA5 wind data (uwind, vwind) to all aircraft positions.

This optimized method uses vectorized NumPy operations to accelerate performance. It first stacks all flight data into a single large array, identifies all valid data points at once, and then performs a single, efficient 4D interpolation for time-grouped chunks of points. The final assignment of wind data is also vectorized, avoiding slow Python loops.

This is intended to be run once after loading data to prevent slow on-the-fly wind lookups during repeated calls to get_trail.

Raises:

• RuntimeError – If ERA5_DATA_HANDLER is not available, if data has not been loaded, or if a download was attempted but files are still missing.

• ValueError – If the date cannot be parsed from the loaded filename.

get_current(dtime, vname=None)

get_data(dtime, vname, tlen=7200)

get_tracks(dtime, tlen=7200, include_time=False)

Returns unadvected track position (lon, lat, alt, and potentially time [in seconds befor dtime]) for now and every previous 15 sec until tlen (in min)

Currently uses aircraft wind - I don’t think this is accurate when the aircraft is climbing of descending

get_trails(dtime, tlen=7200, spread_velocity=-1, wind_filter=-1, include_time=False, winds='era5', adjust_mps=(0, 0))

Returns trail position (lon, lat, and potentially time [in seconds befor dtime]) for now and every previous 15 sec until tlen (in min)

Currently uses aircraft wind - I don’t think this is accurate when the aircraft is climbing of descending

has_notnull_data(var)

list_current()

load_output(filename)

update_internal()

write_output(filename)

class arguslib.aircraft.Aircraft(icao24, atype=None, time_resolution=15, variables=['lon', 'lat', 'alt_geom'])

Bases: object

add_position(dtime, aircraft_data)

get_current(dtime, vname=None)

get_data(dtime, vname, tlen=7200)

get_track(dtime, tlen=7200, include_time=False)

get_trail(dtime, tlen=7200, spread_velocity=-1, winds='era5', wind_filter=-1, include_time=False, adjust_mps=(0, 0))

valid_points()

class arguslib.aircraft.AircraftPos(time_resolution=15, variables=['lon', 'lat', 'alt', 'geom'])

Bases: object

add_position(dtime, aircraft_data)

get_current(dtime, vname=None)

get_data(dtime, vname, tlen=7200)

get_heading(dtime)

get_track(dtime, tlen=7200, include_time=False)

get_trail(dtime, tlen=7200, spread_velocity=-1, wind_filter=-1, winds='era5', include_time=False, adjust_mps=(0, 0))

interpolate_position(dtime, alt_var='alt_geom')

valid_points()