Update v0.2.0 (#4)

.gitattributes

@@ -1,3 +1,4 @@
 *.m3d filter=lfs diff=lfs merge=lfs -text
 *.mat filter=lfs diff=lfs merge=lfs -text
 *.npy filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

.github/codecov.yml

@@ -0,0 +1,6 @@
+coverage:
+  precision: 1
+parsers:
+  cobertura:
+    handle_missing_conditions: true
+    partials_as_hits: true

.github/workflows/tests.yml

@@ -0,0 +1,59 @@
+name: Tests
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.8", "3.9", "3.10"]
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        lfs: 'true'
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install flake8 pytest pytest-cov
+
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings
+        flake8 . --count --exit-zero --statistics
+
+    - name: Install excalibur
+      run: |
+        python -m pip install .
+
+    - name: Test with pytest
+      if: matrix.python-version != '3.8'
+      run: |
+        pytest
+
+    - name: Test with pytest and create coverage report
+      if: matrix.python-version == '3.8'
+      run: |
+        pytest --cov=excalibur --cov-report term --cov-report xml:coverage.xml --no-cov-on-fail
+        
+    - name: Upload coverage reports to Codecov
+      if: matrix.python-version == '3.8'
+      uses: codecov/codecov-action@v3
+      with:
+        token: ${{secrets.CODECOV_TOKEN}}
+        files: ${{github.workspace}}/coverage.xml
+        fail_ci_if_error: true

.gitignore

@@ -2,6 +2,7 @@
 .*/
 
 # Python
+build/
 venv/
 .venv
 __pycache__/
@@ -13,3 +14,7 @@ __pycache__/
 # IDEs
 .idea/
 .vscode/
+
+# Coverage
+.coverage
+coverage.xml

.readthedocs.yaml

@@ -0,0 +1,38 @@
+# Required
+version: 2
+
+# Dependencies
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"
+  jobs:
+    post_checkout:
+      # https://docs.readthedocs.io/en/stable/build-customization.html#support-git-lfs-large-file-storage
+      # Download and uncompress the binary
+      # https://git-lfs.github.com/
+      - wget https://github.com/git-lfs/git-lfs/releases/download/v3.1.4/git-lfs-linux-amd64-v3.1.4.tar.gz
+      - tar xvfz git-lfs-linux-amd64-v3.1.4.tar.gz
+      # Modify LFS config paths to point where git-lfs binary was downloaded
+      - git config filter.lfs.process "`pwd`/git-lfs filter-process"
+      - git config filter.lfs.smudge  "`pwd`/git-lfs smudge -- %f"
+      - git config filter.lfs.clean "`pwd`/git-lfs clean -- %f"
+      # Make LFS available in current repository
+      - ./git-lfs install
+      # Download content from remote
+      - ./git-lfs fetch
+      # Make local files to have the real content on them
+      - ./git-lfs checkout
+
+# Sphinx config
+sphinx:
+  configuration: docs/source/conf.py
+
+# Python requirements
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - develop
+

CITATIONS.bib

@@ -1,26 +1,33 @@
 @article{horn2021online,
-  author={Horn, Markus and Wodtko, Thomas and Buchholz, Michael and Dietmayer, Klaus},
-  journal={IEEE Robotics and Automation Letters},
-  title={Online Extrinsic Calibration Based on Per-Sensor Ego-Motion Using Dual Quaternions},
-  year={2021},
-  volume={6},
-  number={2},
-  pages={982-989},
-  doi={10.1109/LRA.2021.3056352}
+  author  = {Horn, Markus and Wodtko, Thomas and Buchholz, Michael and Dietmayer, Klaus},
+  title   = {Online Extrinsic Calibration Based on Per-Sensor Ego-Motion Using Dual Quaternions},
+  journal = {IEEE Robotics and Automation Letters (RA-L)},
+  year    = {2021},
+  volume  = {6},
+  number  = {2},
+  pages   = {982-989},
+  doi     = {10.1109/LRA.2021.3056352},
 }
 
 @inproceedings{wodtko2021globally,
-  author={Wodtko, Thomas and Horn, Markus and Buchholz, Michael and Dietmayer, Klaus},
-  booktitle={2021 International Conference on 3D Vision (3DV)},
-  title={Globally Optimal Multi-Scale Monocular Hand-Eye Calibration Using Dual Quaternions},
-  year={2021},
-  pages={249-257},
-  doi={10.1109/3DV53792.2021.00035}
+  author    = {Wodtko, Thomas and Horn, Markus and Buchholz, Michael and Dietmayer, Klaus},
+  title     = {Globally Optimal Multi-Scale Monocular Hand-Eye Calibration Using Dual Quaternions},
+  booktitle = {International Conference on 3D Vision (3DV)},
+  year      = {2021},
+  pages     = {249-257},
+  doi       = {10.1109/3DV53792.2021.00035},
 }
 
 @inproceedings{horn2023extrinsic,
-  author={Horn, Markus and Wodtko, Thomas and Buchholz, Michael and Dietmayer, Klaus},
-  booktitle={2023 IEEE Intelligent Vehicles Symposium (IV)},
-  title={Extrinsic Infrastructure Calibration Using the Hand-Eye Robot-World Formulation},
-  year={2023},
+  author    = {Horn, Markus and Wodtko, Thomas and Buchholz, Michael and Dietmayer, Klaus},
+  title     = {Extrinsic Infrastructure Calibration Using the Hand-Eye Robot-World Formulation},
+  booktitle = {IEEE Intelligent Vehicles Symposium (IV)},
+  year      = {2023},
+}
+
+@inproceedings{horn2023user,
+  author    = {Horn, Markus and Wodtko, Thomas and Buchholz, Michael and Dietmayer, Klaus},
+  title     = {User Feedback and Sample Weighting for Ill-Conditioned Hand-Eye Calibration},
+  booktitle = {IEEE International Conference on Intelligent Transportation Systems (ITSC)},
+  year      = {2023},
 }

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2022 Markus Horn and Thomas Wodtko
+   Copyright 2023 Ulm University, Institute of Measurement, Control and Microtechnology
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,11 +1,16 @@
 # Excalibur
 
+[![Documentation Status](https://readthedocs.org/projects/excalibur-mrm/badge/?version=latest)](https://excalibur-mrm.readthedocs.io/en/latest/?badge=latest)  
+[![Tests](https://github.com/uulm-mrm/excalibur/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/uulm-mrm/excalibur/actions/workflows/tests.yml)
+[![Codecov](https://codecov.io/gh/uulm-mrm/excalibur/graph/badge.svg?token=MPQQ1SFVNP)](https://codecov.io/gh/uulm-mrm/excalibur)
+
 An open-source Python library for **ex**trinsic sensor **calib**ration.
 We provide various solving and optimization methods for different calibration formulations:
 
  * Point set registration / point-to-point matching
  * Pose set registration / frame-to-frame matching
- * Bundle adjustment / point-to-line matching
+ * Point-to-line matching
+ * Point-to-plane matching
  * Hand-eye calibration
  * Hand-eye robot-world calibration
 
@@ -19,25 +24,14 @@ python3 -m pip install .
 ```
 
 This command should automatically install Excalibur and all requirements.
+If the installation fails, first make sure that pip is updated to the latest version.
 
+Supported Python versions: `3.8`, `3.9`, `3.10`
 
 
-## Usage
-
-Transformation data are stored and passed using our open-source Python library `motion3d` which handles, e.g., the conversion between different transformation representations or the conversion between motions and poses.
-For more information, please visit the `motion3d` repository: https://github.com/mhorn11/motion3d
-
-All supported formulations have their own base class that provides a `Factory` function, enabling string-based initialization of methods.
-Further, all methods can also be initialized directory using the respective class.
-Each class provides a method for setting the input data, e.g., `set_transformations(...)` for hand-eye calibration, and a `calibrate` method for computing the result.
-The result contains the estimated calibration, run time and other auxiliary data.
-
-We are still working on a detailed documentation.
-For now, you can check our unit tests in the `test` directory or our evaluation scripts in the `publications` directory for examples.
-
-Please be aware that the interfaces also might change between different version, as we are still trying to improve the usability.
-If you have any issues or suggestions, don't hesitate to write an issue or to contact us directly via e-mail.
+## Documentation
 
+The `doc` directory provides a detailed readme on how to create the documentation directly from the repository.
 
 
 ## Publications
@@ -64,8 +58,16 @@ The `publications` directory contains scripts and data related to the following
     M. Horn, T. Wodtko, M. Buchholz and K. Dietmayer  
     2023 IEEE Intelligent Vehicles Symposium (IV)
 
+    DOI: 10.1109/IV55152.2023.10186703  
+    IEEE Xplore: https://ieeexplore.ieee.org/document/10186703  
     ArXiv: https://arxiv.org/abs/2305.01407
 
+  * **User Feedback and Sample Weighting for Ill-Conditioned Hand-Eye Calibration**  
+    M. Horn, T. Wodtko, M. Buchholz and K. Dietmayer  
+    2023 IEEE International Conference on Intelligent Transportation Systems (ITSC)  
+
+    ArXiv: https://arxiv.org/abs/2308.06045
+
 Be aware that we have made improvements and bugfixes since the publications, so the results and run times might differ from the ones in the publications.
 Please cite the respective publication if you are using Excalibur for your own research.
 You can find the Bibtex citations in the `CITATIONS.bib` file.

docs/.gitignore

@@ -0,0 +1 @@
+build/

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,20 @@
+# Excalibur Documentation
+
+The following instructions describe how to build the documentation pages and which dependencies are required.
+In case all dependencies are available, you can also use the `build.py` script for creating the documentation automatically.
+
+The documentation is created using Sphinx (https://www.sphinx-doc.org).
+All requirements can be installed using:
+
+```bash
+bash> python3 -m pip install .[develop]
+zsh>  python3 -m pip install .\[develop\]
+```
+
+To build the documentation, run the following command from the `docs` directory:
+
+```bash
+make html
+```
+
+The documentation main page is then located at `build/html/index.html`. 

docs/build.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+import importlib
+import os.path as osp
+import subprocess
+import sys
+
+
+# utils
+script_dir = osp.dirname(osp.realpath(__file__))
+
+
+def exit_with_error(msg):
+    print(msg, file=sys.stderr)
+    sys.exit(1)
+
+
+# check dependencies
+python_packages = ['sphinx', 'sphinx_rtd_theme', 'excalibur']
+for package in python_packages:
+    try:
+        importlib.import_module(package)
+    except ModuleNotFoundError:
+        exit_with_error(f"Error: required python package '{package}' not found.\n"
+                         "Did you install the package with the [develop] option?")
+
+
+# build documentation using Sphinx
+print("\n############################################")
+print("### Building Documentation using Sphinx  ###")
+print("############################################")
+sphinx = subprocess.Popen(['make', 'html'], cwd=script_dir)
+sphinx.wait()
+if sphinx.returncode != 0:
+    exit_with_error("An error occured while building the Python documentation.")
+
+
+# print main pages
+print("\nSucessfully built the documentation:")
+print(f" - Main page:  {osp.join(script_dir, 'build', 'html', 'index.html')}")