arguslib.instruments package

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

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

gead_to_iead(elevation, azimuth, dist)

get_data_time(dt, **kwargs)

iead_to_gead(elevation, azimuth, dist)

iead_to_lla(elevation, azimuth, dist)

iead_to_xyzworld(elevation, azimuth, dist)

initialise_data_loader()

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

target_iead(target_position)

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

xyzworld_to_iead(target_x, target_y, target_z)

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

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

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

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

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.

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.

xyz_to_lla(target_x, target_y, target_z)

Converts local ENU coordinates back to a global Position object(s).

This method inverts the target_xyz calculation using a spherical Earth model. It is vectorized to handle NumPy arrays of coordinates, in which case it will return a list of Position objects.

Parameters:

• target_x (float or np.ndarray) – East-West distance(s) in km.

• target_y (float or np.ndarray) – North-South distance(s) in km.

• target_z (float or np.ndarray) – Up-Down distance(s) in km.

Returns:

The new geographical position object, or a list of objects if the input was vectorized.

Return type:

Position or list[Position]