dfjimu 0.1.0__tar.gz

dfjimu-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Daniel Oliver Martin Weber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dfjimu-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include src/dfjimu *.py *.pyx *.pxd *.c

dfjimu-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: dfjimu
+Version: 0.1.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: 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; 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.

dfjimu-0.1.0/README.md

@@ -0,0 +1,62 @@
+# 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.

dfjimu-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61.0", "cython", "numpy"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dfjimu"
+version = "0.1.0"
+description = "Drift-free IMU-based joint kinematics estimation (Weygers & Kok, 2020)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{name = "Daniel Oliver Martin Weber"}]
+keywords = ["IMU", "joint-kinematics", "MEKF", "quaternion", "inertial-sensors"]
+dependencies = [
+    "numpy",
+    "scipy",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Cython",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.urls]
+Homepage = "https://github.com/daniel-om-weber/dfjimu"
+Repository = "https://github.com/daniel-om-weber/dfjimu"
+Issues = "https://github.com/daniel-om-weber/dfjimu/issues"
+
+[project.optional-dependencies]
+examples = [
+    "jupyter",
+    "matplotlib",
+]
+dev = [
+    "cython",
+    "setuptools",
+    "pytest",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dfjimu = ["*.pyx", "*.pxd", "py.typed"]

dfjimu-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dfjimu-0.1.0/setup.py

@@ -0,0 +1,56 @@
+import sys
+from setuptools import setup, Extension
+from setuptools.command.build_ext import build_ext
+
+
+class OptionalBuildExt(build_ext):
+    """build_ext that warns instead of crashing when compilation fails."""
+
+    def build_extension(self, ext):
+        try:
+            super().build_extension(ext)
+        except Exception as e:
+            print(f"WARNING: Failed to build extension {ext.name}: {e}")
+            print("The package will use pure Python fallbacks (slower).")
+
+
+def get_extensions():
+    try:
+        import numpy as np
+    except ImportError:
+        print("WARNING: NumPy not available. "
+              "Skipping C extension compilation.")
+        return []
+
+    try:
+        from Cython.Build import cythonize
+        USE_CYTHON = True
+    except ImportError:
+        USE_CYTHON = False
+
+    ext = '.pyx' if USE_CYTHON else '.c'
+    extensions = [
+        Extension(
+            "dfjimu._cython.core",
+            [f"src/dfjimu/_cython/core{ext}"],
+            include_dirs=[np.get_include()],
+            define_macros=[("NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION")],
+        ),
+        Extension(
+            "dfjimu._cython.optimizer",
+            [f"src/dfjimu/_cython/optimizer{ext}"],
+            include_dirs=[np.get_include()],
+            define_macros=[("NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION")],
+        ),
+    ]
+
+    if USE_CYTHON:
+        extensions = cythonize(extensions, compiler_directives={'language_level': "3"})
+
+    return extensions
+
+
+setup(
+    ext_modules=get_extensions(),
+    cmdclass={'build_ext': OptionalBuildExt},
+)

dfjimu-0.1.0/src/dfjimu/__init__.py

@@ -0,0 +1,15 @@
+__version__ = "0.1.0"
+_CYTHON_AVAILABLE = False
+
+try:
+    from ._cython.core import run_mekf_cython
+    from ._cython.optimizer import build_system_cython, update_lin_points_cython
+    _CYTHON_AVAILABLE = True
+except ImportError:
+    from ._python.core import run_mekf_cython
+    from ._python.optimizer import build_system_cython, update_lin_points_cython
+
+from .mekf_acc import mekf_acc, MekfAcc
+from .map_acc import map_acc, MapAcc
+
+__all__ = ['mekf_acc', 'MekfAcc', 'map_acc', 'MapAcc', '_CYTHON_AVAILABLE']