# CoMPAS navlib

[![Latest version](https://badge.fury.io/py/navlib.svg)](https://badge.fury.io/py/navlib.svg) [![PyPI Downloads](https://static.pepy.tech/badge/navlib)](https://pepy.tech/projects/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](https://github.com/dwcaress/MB-System) software package.

## Installation

Clone the repository and install in editable mode:

```bash
pip install navlib
```

or with [uv](https://docs.astral.sh/uv/):

```bash
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:

```bash
pip install navlib[calibration]
```

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

```bash
pip install navlib[calibration] --pre
```

or with uv:

```bash
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](https://compaslab.github.io/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](https://docs.astral.sh/uv/) for dependency management. Install all
dependencies (including dev, test, and docs groups) with:

```bash
uv sync --group dev --group test --group docs
```

Activate the environment or prefix commands with `uv run`:

```bash
# 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`:

```bash
uv run pre-commit install
```

### Static Documentation

Documentation is built with [mkdocs](https://www.mkdocs.org/). Sync the docs group first
if you have not already:

```bash
uv sync --group docs
```

Then build:

```bash
uv run mkdocs build
```

Or serve locally and navigate to [http://localhost:8000/](http://localhost:8000/):

```bash
uv run mkdocs serve
```

## License

MIT License — see LICENSE for details.
