User Guide

Welcome to the arguslib user guide. This guide provides an overview of the core concepts and classes for visualizing and analyzing coincident data from cameras, radar, and other instruments.

The Core Abstractions

Arguslib is made up of geolocation and visualization components, all based around structures representing instruments. The two most fundamental concepts are the Position, which defines a location in space, and the PlottableInstrument, which defines an object that can be visualized.

The Position Class: The Foundation of Geolocation

The fundamental concept for geolocation is the Position class. It stores the longitude, latitude, and altitude of a point and provides methods for calculating distances and bearings to other points. It is the fundamental building block for locating physical instruments and annotating data.

class arguslib.instruments.instruments.Position(lon, lat, alt)

Bases: object

Represents a geographical point in longitude, latitude, and altitude.

This class provides the core functionality for geolocation within arguslib. It assumes a locally flat Earth for calculations, which is suitable for the typical ranges of ground-based instruments.

All distance and altitude units are in kilometers.

lon

Longitude in degrees.

Type:

float

lat

Latitude in degrees.

Type:

float

alt

Altitude in kilometers.

Type:

float

target_ead(target_position)

Calculates the elevation, azimuth, and distance to a target position. Vectorized to handle a list of target positions.

target_xyz(target_position)

Calculates the East-North-Up Earth-relative, Earth-fixed X, Y, Z coordinates between this and a target position. Vectorized to handle a list of target positions.

ead_to_lla(target_elevation, target_azimuth, target_distance)

Converts elevation, azimuth, and distance to a new Position using a spherical Earth model. Handles elevations > 90 degrees.

The PlottableInstrument: A Universal Drawing API

Once you have a location, you need something to visualize it on. The PlottableInstrument is an abstract class that defines a standard interface for any object that can be visualized. It guarantees that any PlottableInstrument will have show() and annotate_positions() methods.

This is a powerful concept because it applies not only to physical devices, but also to higher-level “interfaces” that combine plottables and other data sources.

class arguslib.instruments.instruments.PlottableInstrument(**attrs)

Bases: object

An abstract base class for any object that can be visualized.

This class defines the core API for visualization within arguslib. Any instrument or interface that can be displayed on a Matplotlib plot or rendered into an image should implement these methods.

attrs

A dictionary of attributes describing the instrument.

Type:

dict

show(dt, ax=None, **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

annotate_positions(positions, dt, ax, **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

The Instrument: Physical Devices

The Instrument class represents a physical device, like a camera or a radar. It extends PlottableInstrument by adding the concept of a physical location (position) and orientation (rotation) in the world. It also introduces new instrument-relative coordinate systems including the iead (instrument elevation, azimuth and distance, measured relative to some reference axes, such as the image plane and focal axes).

class arguslib.instruments.instruments.Instrument(position, rotation, **attrs)

Bases: PlottableInstrument

Represents a physical instrument with a specific location and orientation.

This class extends PlottableInstrument by adding coordinate transformation capabilities. It holds a Position and a rotation vector, allowing it to convert between its own local coordinate system (instrument-relative elevation/azimuth) and the global coordinate system (world-relative elevation/azimuth).

It also introduces the concept of a data_loader, which is responsible for fetching the instrument’s data (e.g., images, scans) for a given time.

position

The geographical location of the instrument.

Type:

Position

rotation

A list of three angles [elevation, azimuth, roll] defining the instrument’s orientation.

Type:

list

data_loader

An object responsible for loading data for this instrument. It is typically initialized on the first call to get_data_time or show.

iead_to_gead(elevation, azimuth, dist)

gead_to_iead(elevation, azimuth, dist)

target_iead(target_position)

Calculates instrument-relative EAD from a target position. Vectorized to handle a list of target positions.

iead_to_lla(elevation, azimuth, dist)

iead_to_xyzworld(elevation, azimuth, dist)

xyzworld_to_iead(target_x, target_y, target_z)

Data Loaders

Each Instrument has a data_loader attribute. This object is responsible for finding and loading the actual data (e.g., image frames or radar scans) for a given time. This separation of concerns keeps the instrument logic clean from the details of file formats and directory structures. The data loader is typically initialized automatically when data is first requested.

Concrete Instruments: The Camera

The Camera class is a concrete implementation of an Instrument. It represents a single camera, handles its specific calibration, and knows how to load and display image frames.

class arguslib.camera.camera.Camera(intrinsic_calibration, *args, scale_factor=1, camera_type='allsky', **kwargs)

Bases: Instrument

Represents a camera instrument, handling intrinsic and extrinsic calibration.

This class provides the core functionality for a single camera, including loading configuration, converting between world coordinates and pixel coordinates, and rendering the camera’s view on a plot. It supports both ‘allsky’ fisheye cameras and standard ‘perspective’ cameras.

intrinsic

The intrinsic calibration model.

Type:

Projection

scale_factor

A scaling factor applied to image dimensions.

Type:

float

camera_type

The type of camera, e.g., ‘allsky’ or ‘perspective’.

Type:

str

image_size_px

The dimensions of the camera image in pixels.

Type:

np.ndarray

classmethod from_config(campaign, camstr, **kwargs)

annotate_positions(positions, dt, ax, *args, plotting_method=None, max_range_km=90, **kwargs)

Annotates one or more geographical positions on the camera image. This version is vectorized for performance.

show(dt, ax=None, **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

Specialized Cameras

The power of this structure is that it’s easy to extend. For example, arguslib provides specialized camera classes that build upon the base Camera:

• UndistortedCamera: Inherits from Camera but overrides the data loading method to apply a fisheye undistortion to the image before displaying it.

• DirectCamera: A more advanced subclass that bypasses Matplotlib entirely, drawing annotations directly onto the image array using OpenCV. This is ideal for generating videos efficiently.

class arguslib.camera.undistorted_camera.UndistortedCamera(*args, **kwargs)

Bases: Camera

A specialized Camera that applies a fisheye undistortion to images.

This version pre-computes the undistortion mapping for high performance.

get_data_time(*args, **kwargs)

target_pix(target_position)

Calculates pixel coordinates for a target position. Vectorized to handle a list of positions.

class arguslib.camera.direct_camera.DirectCamera(intrinsic_calibration, *args, scale_factor=1, camera_type='allsky', **kwargs)

Bases: Camera

A Camera subclass that renders annotations directly onto the image array.

This class is optimized for performance, especially for creating videos. Instead of using Matplotlib for plotting, it overrides the show and annotate_positions methods to use OpenCV functions (cv2.line, cv2.putText) to draw directly on the image data.

As a result, its show and annotate_positions methods do not accept or return Matplotlib Axes objects. The final image can be accessed via the .image property or .to_image_array() method.

annotate_positions(positions, dt, ax, *args, plotting_method=None, max_range_km=90, **kwargs)

Annotates one or more geographical positions on the camera image. This version is vectorized for performance.

property image

show(dt, ax=None, **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

Combining Instruments and Data: Interfaces

Interfaces are also PlottableInstrument objects, but they are not physical devices. Instead, they compose one or more other plottable instruments to create more complex, synchronized visualizations. This is a key design pattern in arguslib.

The RadarInterface

The RadarInterface takes a Radar and another PlottableInstrument (like a Camera or even a CameraArray) and displays them side-by-side.

class arguslib.radar.radar_interface.RadarInterface(radar, camera)

Bases: PlottableInstrument, ProvidesRadarScanTime

Combines a radar and a plottable instrument (e.g., Camera) for synchronized visualization.

This class facilitates the creation of plots that show a camera’s view (or another instrument’s view) side-by-side with a corresponding radar scan. It also handles overlaying radar-derived information, such as the scan volume or individual beams, onto the camera’s display.

The core functionality is provided by the show method, which generates the combined plot.

radar

The radar instrument instance.

Type:

Radar

camera

The camera or other instrument to plot alongside the radar.

Type:

PlottableInstrument

classmethod from_campaign(campaign, camstr)

show(dt, ax=None, var='DBZ', kwargs_camera=None, kwargs_radar_scan=None, kwargs_radar_beams=None, annotate_beams=True, beam_type='start_end', ranges_km_for_beams=None, annotate_scan_box=True, kwargs_scan_box=None, show_legend=False, **kwargs)

Displays the camera view and radar scan side-by-side for a specific time.

This is the primary method for this class. It creates a figure with two subplots: one for the camera/target instrument’s view and one for the radar scan (e.g., an RHI or PPI plot). It can also orchestrate the annotation of radar beams and scan boundaries on the camera view.

Parameters:

• dt (datetime.datetime) – The datetime for the visualization. This time must correspond to an available radar scan.

• ax (tuple[Axes, Axes], optional) – A tuple of two Matplotlib axes (ax_camera, ax_radar) to plot on. If None, new axes are created. Defaults to None.

• var (str, optional) – The radar variable to plot (e.g., ‘DBZ’). Defaults to “DBZ”.

• kwargs_camera (dict, optional) – Keyword arguments passed to the camera.show() method. Defaults to None.

• kwargs_radar_scan (dict, optional) – Keyword arguments passed to the radar.show() method. Defaults to None.

• kwargs_radar_beams (dict, optional) – Keyword arguments for plotting radar beams on the camera, passed to annotate_radar_beams. Defaults to None.

• annotate_beams (bool, optional) – If True, overlays radar beams on the camera view. Defaults to True.

• beam_type (str, optional) – Type of beams to show (‘start_end’, ‘active’). Defaults to ‘start_end’.

• ranges_km_for_beams (list, optional) – Distances along the beam to plot. Defaults to None.

• annotate_scan_box (bool, optional) – If True, overlays the scan extent on the camera view. Defaults to True.

• kwargs_scan_box (dict, optional) – Keyword arguments for plotting the scan box. Defaults to None.

• show_legend (bool, optional) – If True, attempts to display a legend on the camera plot. Defaults to False.

• **kwargs – Additional keyword arguments passed to radar.show().

annotate_positions(positions, dt, ax, cam_kwargs={}, radar_kwargs={}, **kwargs)

Annotates geographical positions on both the camera and radar plots.

Parameters:

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

• dt (datetime.datetime) – The datetime for the annotation.

• ax (tuple[Axes, Axes]) – A tuple of the two axes (ax_camera, ax_radar) to plot on.

• cam_kwargs (dict, optional) – Keyword arguments passed specifically to camera.annotate_positions. Defaults to {}.

• radar_kwargs (dict, optional) – Keyword arguments passed specifically to radar.annotate_positions. Defaults to {}.

• **kwargs – Keyword arguments passed to both annotation methods.

Returns:

The updated camera and radar axes.

Return type:

tuple[Axes, Axes]

The AircraftInterface

Similarly, the AircraftInterface wraps another PlottableInstrument and adds the capability to load and display aircraft flight tracks on top of it. Because it is itself a PlottableInstrument, it can be passed to other interfaces for even more complex plots.

class arguslib.aircraft.aircraft_interface.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

classmethod from_campaign(campaign, camstr)

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

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)