Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update v0.2.0 #4

Merged
merged 7 commits into from
Jan 2, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -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
6 changes: 6 additions & 0 deletions .github/codecov.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
coverage:
precision: 1
parsers:
cobertura:
handle_missing_conditions: true
partials_as_hits: true
59 changes: 59 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -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
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
.*/

# Python
build/
venv/
.venv
__pycache__/
Expand All @@ -13,3 +14,7 @@ __pycache__/
# IDEs
.idea/
.vscode/

# Coverage
.coverage
coverage.xml
38 changes: 38 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -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

43 changes: 25 additions & 18 deletions CITATIONS.bib
Original file line number Diff line number Diff line change
@@ -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},
}
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
34 changes: 18 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand All @@ -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.
1 change: 1 addition & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
build/
20 changes: 20 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -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)
20 changes: 20 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -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`.
39 changes: 39 additions & 0 deletions docs/build.py
Original file line number Diff line number Diff line change
@@ -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')}")
Loading