navlib 1.3.0

MBARI CoMPAS Lab Utilities for Navigation Data Processing

CoMPAS navlib

CoMPAS navlib is a Python library developed by the CoMPAS Lab that provides a modular and extensible toolbox for navigation-related tasks, sensor processing, and robotics research. It includes utilities for array-based math, transformations in SO(3)/SE(3), filtering, environmental data processing, geolocation, time handling, calibration, and navigation.

Features

• Math Utilities: Convenient array-based operations designed for navigation and signal processing.
• Lie Groups: Functions for working with SO(3) and SE(3) transformations.
• Filters: Various filtering methods for pre-processing navigation data.
• Environmental Processing: Tools for post-processing CTD (Conductivity, Temperature, Depth) sensor data.
• Geographic Utilities: Functions for working with geographic coordinates, including transformations to UTM and other projections.
• Time Handling: Utilities for managing time, including UTC conversions and date-time formatting.
• Calibration Tools: Functions for calibrating sensors such as AHRS/IMUs, magnetometers, and Doppler Velocity Logs (DVLs).
• Navigation Algorithms: Implementations of attitude estimation and dead reckoning algorithms for underwater vehicle navigation including an specific EKF for uncrewed underwater vehicles.
• LCM Log Utilities: Tools for parsing and working with LCM (Lightweight Communications and Marshalling) logs.
• MB-System Utilities: Functions for parsing and processing data from the MB-System software package.

Installation

Clone the repository and install in editable mode:

pip install navlib

or with uv:

uv pip install navlib

Optional: Magnetometer Calibration Dependencies

The advanced magnetometer calibration methods (MAGYC, MagFactor3) depend on jax and gtsam, which are not installed by default due to architecture and Python version constraints. To include them, install the calibration extra:

pip install navlib[calibration]

On Python >= 3.12, gtsam requires a pre-release version. Allow it explicitly with pip:

pip install navlib[calibration] --pre

or with uv:

uv pip install navlib[calibration] --prerelease=allow

Without the calibration extra, all other navlib functionality remains available. The calibration methods that require jax or gtsam will emit a warning at import time if those packages are not found.

Documentation

The documentation is hosted on CoMPAS Navlib. It includes detailed descriptions of the library's features, usage examples, and API references.

Contributing

Pull requests and issues are welcome! If you’d like to contribute, please: fork the repository, create a feature branch and submit a pull request

Development

This project uses uv for dependency management. Install all dependencies (including dev, test, and docs groups) with:

uv sync --group dev --group test --group docs

Activate the environment or prefix commands with uv run:

# run a command inside the environment
uv run pytest

# or activate the virtualenv directly
source .venv/bin/activate

Install the pre-commit hooks after the first uv sync:

uv run pre-commit install

Static Documentation

Documentation is built with mkdocs. Sync the docs group first if you have not already:

uv sync --group docs

Then build:

uv run mkdocs build

Or serve locally and navigate to http://localhost:8000/:

uv run mkdocs serve

License

MIT License — see LICENSE for details.