ASTrIX: AeroSpace Trajectory Imaging toolboX¶

Under Construction…

A Python tool package for planning and analysing aerospace imaging campaigns.

View the full documentation here. Source code is hosted on GitHub.

Features¶

Simple, object-oriented interface to reconstruct position and reference frame of moving targets, observer stations, cameras projections, and more.
Support for NumPy and Jax backends using the array api spec. Fully differentiable and JIT-compatible using Jax backend for efficient optimisation and state estimation.
Many convenience tools for interpolation, triangulation, and frame handling in ECEF coordinates.

This toolbox has three main use cases:

Planning flight paths and ground station placement for aerospace observation campaigns.
Trajectory reconstruction and state estimation from observational data (e.g. optical tracking).
Aiding analysis of scientific optical measurements (e.g. spectral data).

Install¶

The repository is not yet published to PyPI, so installation is via cloning the repository and installing using pip.

$ git clone https://github.com/andrewjlock/astrix.git
$ cd astrix

While under development editable installation is recommend

$ python3 -m pip install -e .[jax,plot]

The jax extra instals Jax which is used for optional advanced automatic differentiation and state/parameter estimation capabilities. The plot extra install basemap and cartopy for geographic plotting. For a lean install you can omit both the [jax] and [plot] extra,

$ python3 -m pip install -e .

For development, use the dev group, which includes linting and testing tools.

$ python3 -m pip install -e .[plot] --group dev

Alternatively, this project has been developed with, and is compliant with, the uv package manager. The dev group is installed by default.

$ uv pip install -e .[jax,plot]

Dependencies¶

You will need to manually install the following dependency using apt

$ sudo apt -y install libgeos-dev

The package requires, and is tested with Python 3.12 (default on Ubuntu 24.04 LTS). Such a recent version of Python is required to support recent array api specification features enabling backend switching. However, type checking implements features of the Python Array API standard which require Python 3.12. Therefore, Python 3.12 is recommended for development.

Backend Compatibility - Numpy and Jax¶

This project utilises the Array API standard to enable switching between NumPy and Jax for some core classes and functions, using their common native API. Numpy is the default, and superior for most use cases. Jax provides two extra capabilities: automatic differentiation and JIT compilation, which can be useful for optimisation and estimation problems. However, Jax is slower than Numpy for most use cases.

Classes and functions which support both backends have a backend argument, which can be set to either 'numpy'/'np' or 'jax'/'jnp', or a reference to either namespace. Those that have no need for Jax capabilities are implemented in NumPy only. The backend is specified per-instance, as there are use cases when both may be wanted simultaneously. Be careful not to mix NumPy- and Jax-backend objects unintentionally, as this can lead to hard-to-diagnose bugs.

To use the Jax backend, you will nees to ensure the SciPy environment environment variable is set, via Python before you import scipy.spatial.transform.Rotation. This is done automatically when you import astrix, but can also be done manually:

import os
os.environ['SCIPY_ARRAY_API'] = "True"

or in your shell

$ export SCIPY_ARRAY_API=True

Failure to set this environment variable will result in errors using the SciPy Rotation module with Jax backend.

Note that Jax backend is implemented on CPU only, and 64-bit precision is enforced on astrix import (Jax defaults to 32-bit, which often is insufficient).

Data Conventions¶

This package deals primarily with time series vectors. The following conventions are used:

Time series data is represented as 2D arrays of shape (N, D), where N is the number of time steps and D is the dimensionality of the vector (e.g., 3 for 3D position).
Single vectors are represented as 1D arrays of shape (D,).

Tests¶

Tests are implemented using pytest. To run the tests:

$ pytest tests/

If Jax is installed, tests will be run using both Numpy and Jax backends. If Jax is not installed, only Numpy backend tests will be run.

Documentation¶

Documentation is generated using Sphinx. To build the documentation:

Install dependencies: pip install -r docs/requirements.txt
Navigate to the docs directory: cd docs
Run the generate script python generate_docs.py
Build the docs: make html