Metadata-Version: 2.4
Name: navlib
Version: 1.3.0
Summary: MBARI CoMPAS Lab Utilities for Navigation Data Processing
Author: Bastián Muñoz
Author-email: srodriguez_mbari <srodriguez@mbari.org>
License: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Oceanography
Requires-Python: >=3.8
Requires-Dist: autograd<2,>=1.7.0
Requires-Dist: gsw<4,>=3.6.19
Requires-Dist: imufusion<2,>=1.2.8
Requires-Dist: lcm<2,>=1.5
Requires-Dist: numpy<1.25,>=1.22; python_version >= '3.8' and python_version < '3.9'
Requires-Dist: numpy>=1.25; python_version >= '3.9'
Requires-Dist: pymanopt==2.1.1
Requires-Dist: pyproj<3.6,>=3.3; python_version >= '3.8' and python_version < '3.9'
Requires-Dist: pyproj>=3.6; python_version >= '3.9'
Requires-Dist: scipy<1.14,>=1.11; python_version >= '3.9' and python_version < '3.10'
Requires-Dist: scipy==1.10.*; python_version >= '3.8' and python_version < '3.9'
Requires-Dist: scipy>=1.14; python_version >= '3.10'
Provides-Extra: calibration
Requires-Dist: gtsam>=4.3a0; (python_version >= '3.12') and extra == 'calibration'
Requires-Dist: jax>=0.4.14; (python_version >= '3.10') and extra == 'calibration'
Requires-Dist: jaxlib>=0.4.14; (python_version >= '3.10') and extra == 'calibration'
Description-Content-Type: text/markdown

# 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.
