Metadata-Version: 2.4
Name: dfjimu
Version: 0.2.0
Summary: Drift-free IMU-based joint kinematics estimation (Weygers & Kok, 2020)
Author: Daniel Oliver Martin Weber
License-Expression: MIT
Project-URL: Homepage, https://github.com/daniel-om-weber/dfjimu
Project-URL: Repository, https://github.com/daniel-om-weber/dfjimu
Project-URL: Issues, https://github.com/daniel-om-weber/dfjimu/issues
Keywords: IMU,joint-kinematics,MEKF,quaternion,inertial-sensors
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: examples
Requires-Dist: jupyter; extra == "examples"
Requires-Dist: matplotlib; extra == "examples"
Provides-Extra: dev
Requires-Dist: cython>=3.0; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Drift-Free Joint Kinematics from Dual IMUs

High-performance Python/Cython implementation of the drift-free joint kinematics estimation method from [Weygers & Kok (2020), "Drift-Free Inertial Sensor-Based Joint Kinematics for Long-Term Arbitrary Movements"](https://ieeexplore.ieee.org/document/9044292/).

It includes:
1.  **MAP-acc** (optimization-based smoothing): Gauss-Newton optimizer for high-accuracy offline joint kinematics.
2.  **MEKF-acc** (Multiplicative Extended Kalman Filter): Online filtering.

## Installation

```bash
pip install dfjimu
```

A C compiler is recommended for the fast Cython backend. If unavailable, the package falls back to pure Python automatically.

## Development

```bash
# Install in editable mode
uv pip install -e .

# With Jupyter and matplotlib for running the example notebook
uv pip install -e ".[examples]"

# With dev tools (Cython, pytest)
uv pip install -e ".[dev]"
```

## Usage Example

```python
from dfjimu import mekf_acc, map_acc

# MEKF-acc (online filtering)
q1, q2 = mekf_acc(gyr1, gyr2, acc1, acc2, r1, r2, Fs, q_init)

# MAP-acc (optimization-based smoothing)
q1, q2 = map_acc(gyr1, gyr2, acc1, acc2, r1, r2, Fs, q_init,
                 cov_w, cov_i, cov_lnk)
```

See [`examples/demo.ipynb`](examples/demo.ipynb) for a full walkthrough with plots.

## Running Benchmarks

Evaluate accuracy and speed of the solvers on the dataset:

```bash
uv run tests/evaluate_package.py
```

## Package Structure

-   **`dfjimu/`**: The Python package source.
    -   `map_acc()` / `MapAcc`: MAP-acc optimizer (uses Cython).
    -   `mekf_acc()` / `MekfAcc`: MEKF-acc filter (uses Cython).
    -   `_python/`: Pure Python reference implementations for educational/debugging purposes.

## Reference

Weygers, I., & Kok, M. (2020). Drift-Free Inertial Sensor-Based Joint Kinematics for Long-Term Arbitrary Movements. *IEEE Sensors Journal*, 20(14), 7969-7979.
