# imucal - A Python library to calibrate 6 DOF IMUs
[](https://codecov.io/gh/mad-lab-fau/imucal)
[](https://imucal.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/psf/black)
[](https://pypi.org/project/imucal/)
[](https://joss.theoj.org/papers/3dd1a7dd5ba06ce024326eee2e9be148)
This package provides methods to calculate and apply calibrations for 6 DOF IMUs based on multiple different methods.
So far supported are:
- Ferraris Calibration ([Ferraris1994](https://www.sciencedirect.com/science/article/pii/0924424794800316) / [Ferraris1995](https://www.researchgate.net/publication/245080041_Calibration_of_three-axial_rate_gyros_without_angular_velocity_standards))
- Ferraris Calibration using a Turntable
For more information check the quickstart guide below and the [documentation](https://imucal.readthedocs.io/en/latest/).
## Installation
```
pip install imucal
```
To use the included calibration GUI you also need [matplotlib](https://pypi.org/project/matplotlib/) (version >2.2).
You can install it using:
```
pip install imucal[calplot]
```
### Supported Python versions and Platforms
`imucal` is officially tested on Python 3.7, 3.8, 3.9 and 3.10.
It should further work with all major operating systems.
## Quickstart
This package implements the IMU-infield calibration based on [Ferraris1995](https://www.researchgate.net/publication/245080041_Calibration_of_three-axial_rate_gyros_without_angular_velocity_standards).
This calibration method requires the IMU data from 6 static positions (3 axes parallel and antiparallel to the gravitation
vector) for calibrating the accelerometer and 3 rotations around the 3 main axes for calibrating the gyroscope.
In this implementation, these parts are referred to as `{acc,gyr}_{x,y,z}_{p,a}` for the static regions and
`{acc,gyr}_{x,y,z}_rot` for the rotations.
As example, `acc_y_a` would be the 3D-acceleration data measured during a static phase, where the **y-axis** was
oriented **antiparallel** to the gravitation vector.
For more information on how to perform the calibration check [our guide](https://imucal.readthedocs.io/en/latest/guides/ferraris_guide.html).
For the calibration, you need to separate your data into these individual sections.
If you already recorded them separately or know where each section starts and ends in a continuous recording, you can
use [`ferraris_regions_from_df`](https://imucal.readthedocs.io/en/latest/modules/generated/imucal.ferraris_regions_from_df.html)
and [`ferraris_regions_from_section_list`](https://imucal.readthedocs.io/en/latest/modules/generated/imucal.ferraris_regions_from_section_list.html),
respectively to convert the data into the correct format for the calibration (`section_data` in the snippet below).
If you don't have that information yet, we recommend to use the included GUI to annotate the data.
To annotate a Ferraris calibration session that was recorded in a single go, you can use the following code snippet.
**Note**: This will open an interactive Tkinter plot. Therefore, this will only work on your local PC and not on a server or remote hosted Jupyter instance.
```python
from imucal import ferraris_regions_from_interactive_plot
# Your data as a 6 column dataframe
data = ...
section_data, section_list = ferraris_regions_from_interactive_plot(
data, acc_cols=["acc_x", "acc_y", "acc_z"], gyr_cols=["gyr_x", "gyr_y", "gyr_z"]
)
# Save the section list as reference for the future
section_list.to_csv('./calibration_sections.csv') # This is optional, but recommended
```
Independent of how you obtained the `section_data` in the correct format, you can now calculate the calibration
parameters:
```python
from imucal import FerrarisCalibration
sampling_rate = 100 #Hz
cal = FerrarisCalibration()
cal_mat = cal.compute(section_data, sampling_rate, from_acc_unit="m/s^2", from_gyr_unit="deg/s")
# `cal_mat` is your final calibration matrix object you can use to calibrate data
cal_mat.to_json_file('./calibration.json')
```
Applying a calibration:
```python
from imucal.management import load_calibration_info
cal_mat = load_calibration_info('./calibration.json')
new_data = pd.DataFrame(...)
calibrated_data = cal_mat.calibrate_df(new_data, acc_unit="m/s^2", gyr_unit="deg/s")
```
For further information on how to perform a calibration check the
[User Guides](https://imucal.readthedocs.io/en/latest/guides/index.html) or the
[Examples](https://imucal.readthedocs.io/en/latest/auto_examples/index.html).
## Further Calibration Methods
At the moment, this package only implements calibration methods based on Ferraris1994/95, because this is what we use to
calibrate our IMUs.
We are aware that various other methods exist and would love to add them to this package as well.
Unfortunately, at the moment we can not justify the time investment.
Still, we think that this package provides a suitable framework to implement other calibration methods with relative
ease.
If you would like to contribute such a method, let us know via [GitHub Issue](https://github.com/mad-lab-fau/imucal/issues), and we will try to help you as good
as possible.
## Citation
If you are using `imucal` in your scientific work, we would appreciate if you would cite our [JOSS paper](https://joss.theoj.org/papers/3dd1a7dd5ba06ce024326eee2e9be148) or link the project.
```
Küderle, Arne, Nils Roth, Robert Richer, and Bjoern M. Eskofier.
“Imucal - A Python Library to Calibrate 6 DOF IMUs.”
Journal of Open Source Software 7, no. 73 (May 26, 2022): 4338. https://doi.org/10.21105/joss.04338.
```
## Contributing
All project management and development happens through [this GitHub project](https://github.com/mad-lab-fau/imucal).
If you have any issues, ideas, or any comments at all, just open a new issue.
We are always happy when people are interested to use our work and would like to support you in this process.
In particular, we want to welcome contributions of new calibration algorithms, to make this package even more useful for a wider audience.
## Dev Setup
We use [poetry](https://python-poetry.org) to manage our dependencies.
Therefore, you need to first install Poetry locally on you machine.
Then you can run the following command to install a local development version of this library in a dedicated venv.
```bash
git clone https://github.com/mad-lab-fau/imucal
cd imucal
poetry install --all-extras
```
To run tests/the linter/... we use [poethepoet](https://github.com/nat-n/poethepoet).
You can see all available commands by running:
```
poetry run poe list
```
This should show you all configured commands:
```
CONFIGURED TASKS
format
lint Lint all files with ruff.
ci_check Check all potential format and linting issues.
test Run Pytest with coverage.
docs Build the html docs using Sphinx.
bump_version
```
You execute any command by running
```
poetry run doit <command-name>
```
### Updating dependencies
If you update or add dependencies using (`poetry add` or `poetry update`) you will see that the `pyproject.toml` and the `poetry.lock` files are both updated.
Make sure you commit the changes to **both** files.
Otherwise, wrong versions of dependencies will be used in the CI and by other developers.
In case you update dependencies by directly editing the `pyproject.toml` file, you need to be very careful and make sure, you run `poetry lock [--no-update]` afterwards.
Otherwise, the lock file will be out of date.
In general, it is a good idea to just run `poetry update` from time to time.
This will install the latest version of all dependencies that are still allowed by the version constrains in the `pyproject.toml`.
This allows to check, if everything still works well with the newest versions of all libraries.
Raw data
{
"_id": null,
"home_page": "https://github.com/mad-lab-fau/imucal",
"name": "imucal",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "sensors,scientific,IMU,accelerometer",
"author": "Arne K\u00fcderle",
"author_email": "arne.kuederle@fau.de",
"download_url": "https://files.pythonhosted.org/packages/7c/39/143b34a55fd159f3a202ef5e76bd27d31bcbfffa7ee5fe5502647889b193/imucal-2.4.0.tar.gz",
"platform": null,
"description": "# imucal - A Python library to calibrate 6 DOF IMUs\n\n[](https://codecov.io/gh/mad-lab-fau/imucal)\n[](https://imucal.readthedocs.io/en/latest/?badge=latest)\n[](https://github.com/psf/black)\n[](https://pypi.org/project/imucal/)\n\n[](https://joss.theoj.org/papers/3dd1a7dd5ba06ce024326eee2e9be148)\n\nThis package provides methods to calculate and apply calibrations for 6 DOF IMUs based on multiple different methods.\n\nSo far supported are:\n\n- Ferraris Calibration ([Ferraris1994](https://www.sciencedirect.com/science/article/pii/0924424794800316) / [Ferraris1995](https://www.researchgate.net/publication/245080041_Calibration_of_three-axial_rate_gyros_without_angular_velocity_standards))\n- Ferraris Calibration using a Turntable\n\nFor more information check the quickstart guide below and the [documentation](https://imucal.readthedocs.io/en/latest/).\n\n## Installation\n\n```\npip install imucal\n```\n\nTo use the included calibration GUI you also need [matplotlib](https://pypi.org/project/matplotlib/) (version >2.2).\nYou can install it using:\n\n```\npip install imucal[calplot]\n```\n\n### Supported Python versions and Platforms\n\n`imucal` is officially tested on Python 3.7, 3.8, 3.9 and 3.10.\nIt should further work with all major operating systems.\n\n## Quickstart\nThis package implements the IMU-infield calibration based on [Ferraris1995](https://www.researchgate.net/publication/245080041_Calibration_of_three-axial_rate_gyros_without_angular_velocity_standards).\nThis calibration method requires the IMU data from 6 static positions (3 axes parallel and antiparallel to the gravitation\nvector) for calibrating the accelerometer and 3 rotations around the 3 main axes for calibrating the gyroscope.\nIn this implementation, these parts are referred to as `{acc,gyr}_{x,y,z}_{p,a}` for the static regions and\n`{acc,gyr}_{x,y,z}_rot` for the rotations.\nAs example, `acc_y_a` would be the 3D-acceleration data measured during a static phase, where the **y-axis** was \noriented **antiparallel** to the gravitation vector.\nFor more information on how to perform the calibration check [our guide](https://imucal.readthedocs.io/en/latest/guides/ferraris_guide.html).\n\nFor the calibration, you need to separate your data into these individual sections.\nIf you already recorded them separately or know where each section starts and ends in a continuous recording, you can \nuse [`ferraris_regions_from_df`](https://imucal.readthedocs.io/en/latest/modules/generated/imucal.ferraris_regions_from_df.html)\nand [`ferraris_regions_from_section_list`](https://imucal.readthedocs.io/en/latest/modules/generated/imucal.ferraris_regions_from_section_list.html),\nrespectively to convert the data into the correct format for the calibration (`section_data` in the snippet below).\n\nIf you don't have that information yet, we recommend to use the included GUI to annotate the data.\nTo annotate a Ferraris calibration session that was recorded in a single go, you can use the following code snippet. \n**Note**: This will open an interactive Tkinter plot. Therefore, this will only work on your local PC and not on a server or remote hosted Jupyter instance.\n\n```python\nfrom imucal import ferraris_regions_from_interactive_plot\n\n# Your data as a 6 column dataframe\ndata = ...\n\nsection_data, section_list = ferraris_regions_from_interactive_plot(\n data, acc_cols=[\"acc_x\", \"acc_y\", \"acc_z\"], gyr_cols=[\"gyr_x\", \"gyr_y\", \"gyr_z\"]\n)\n# Save the section list as reference for the future\nsection_list.to_csv('./calibration_sections.csv') # This is optional, but recommended\n```\n\nIndependent of how you obtained the `section_data` in the correct format, you can now calculate the calibration\nparameters:\n\n```python\nfrom imucal import FerrarisCalibration\n\nsampling_rate = 100 #Hz \ncal = FerrarisCalibration()\ncal_mat = cal.compute(section_data, sampling_rate, from_acc_unit=\"m/s^2\", from_gyr_unit=\"deg/s\")\n# `cal_mat` is your final calibration matrix object you can use to calibrate data\ncal_mat.to_json_file('./calibration.json')\n```\n\nApplying a calibration:\n\n```python\nfrom imucal.management import load_calibration_info\n\ncal_mat = load_calibration_info('./calibration.json')\nnew_data = pd.DataFrame(...)\ncalibrated_data = cal_mat.calibrate_df(new_data, acc_unit=\"m/s^2\", gyr_unit=\"deg/s\")\n```\n\nFor further information on how to perform a calibration check the \n[User Guides](https://imucal.readthedocs.io/en/latest/guides/index.html) or the\n[Examples](https://imucal.readthedocs.io/en/latest/auto_examples/index.html).\n\n## Further Calibration Methods\n\nAt the moment, this package only implements calibration methods based on Ferraris1994/95, because this is what we use to\ncalibrate our IMUs.\nWe are aware that various other methods exist and would love to add them to this package as well.\nUnfortunately, at the moment we can not justify the time investment.\n\nStill, we think that this package provides a suitable framework to implement other calibration methods with relative\nease.\nIf you would like to contribute such a method, let us know via [GitHub Issue](https://github.com/mad-lab-fau/imucal/issues), and we will try to help you as good\nas possible.\n\n## Citation\n\nIf you are using `imucal` in your scientific work, we would appreciate if you would cite our [JOSS paper](https://joss.theoj.org/papers/3dd1a7dd5ba06ce024326eee2e9be148) or link the project.\n\n```\nK\u00fcderle, Arne, Nils Roth, Robert Richer, and Bjoern M. Eskofier. \n\u201cImucal - A Python Library to Calibrate 6 DOF IMUs.\u201d\nJournal of Open Source Software 7, no. 73 (May 26, 2022): 4338. https://doi.org/10.21105/joss.04338.\n```\n\n## Contributing\n\nAll project management and development happens through [this GitHub project](https://github.com/mad-lab-fau/imucal).\nIf you have any issues, ideas, or any comments at all, just open a new issue.\nWe are always happy when people are interested to use our work and would like to support you in this process.\nIn particular, we want to welcome contributions of new calibration algorithms, to make this package even more useful for a wider audience.\n\n## Dev Setup\n\nWe use [poetry](https://python-poetry.org) to manage our dependencies.\nTherefore, you need to first install Poetry locally on you machine.\n\nThen you can run the following command to install a local development version of this library in a dedicated venv.\n\n```bash\ngit clone https://github.com/mad-lab-fau/imucal\ncd imucal\npoetry install --all-extras\n```\n\nTo run tests/the linter/... we use [poethepoet](https://github.com/nat-n/poethepoet).\nYou can see all available commands by running:\n\n```\npoetry run poe list\n```\n\nThis should show you all configured commands:\n\n```\nCONFIGURED TASKS\n format \n lint Lint all files with ruff.\n ci_check Check all potential format and linting issues.\n test Run Pytest with coverage.\n docs Build the html docs using Sphinx.\n bump_version \n```\n\nYou execute any command by running\n\n```\npoetry run doit <command-name>\n```\n\n### Updating dependencies\n\nIf you update or add dependencies using (`poetry add` or `poetry update`) you will see that the `pyproject.toml` and the `poetry.lock` files are both updated.\nMake sure you commit the changes to **both** files.\nOtherwise, wrong versions of dependencies will be used in the CI and by other developers.\n\nIn case you update dependencies by directly editing the `pyproject.toml` file, you need to be very careful and make sure, you run `poetry lock [--no-update]` afterwards.\nOtherwise, the lock file will be out of date.\n\nIn general, it is a good idea to just run `poetry update` from time to time.\nThis will install the latest version of all dependencies that are still allowed by the version constrains in the `pyproject.toml`.\nThis allows to check, if everything still works well with the newest versions of all libraries.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library to calibrate 6 DOF IMUs",
"version": "2.4.0",
"project_urls": {
"Documentation": "https://imcucal.readthedocs.io/en/latest/",
"Homepage": "https://github.com/mad-lab-fau/imucal",
"Repository": "https://github.com/mad-lab-fau/imucal"
},
"split_keywords": [
"sensors",
"scientific",
"imu",
"accelerometer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8921f89c1c098f7be9dc3a884f01c36798f458500bd6df2a349d3a3436e4d9d3",
"md5": "0b7b95b261ea2b22ad24b47c0b00e781",
"sha256": "eec2bca48239d86ff40c8a7993333f4eb6763e4d3827fe63c1cac37734db5174"
},
"downloads": -1,
"filename": "imucal-2.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b7b95b261ea2b22ad24b47c0b00e781",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 23422,
"upload_time": "2023-05-26T07:50:23",
"upload_time_iso_8601": "2023-05-26T07:50:23.325188Z",
"url": "https://files.pythonhosted.org/packages/89/21/f89c1c098f7be9dc3a884f01c36798f458500bd6df2a349d3a3436e4d9d3/imucal-2.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7c39143b34a55fd159f3a202ef5e76bd27d31bcbfffa7ee5fe5502647889b193",
"md5": "312f552d6c797e835c49cd4eeaa4c51e",
"sha256": "98f86706d40f280966deab89c7013c39777af3d9b71edb9ae03b88c1544b74ba"
},
"downloads": -1,
"filename": "imucal-2.4.0.tar.gz",
"has_sig": false,
"md5_digest": "312f552d6c797e835c49cd4eeaa4c51e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 23963,
"upload_time": "2023-05-26T07:50:25",
"upload_time_iso_8601": "2023-05-26T07:50:25.603695Z",
"url": "https://files.pythonhosted.org/packages/7c/39/143b34a55fd159f3a202ef5e76bd27d31bcbfffa7ee5fe5502647889b193/imucal-2.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-26 07:50:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mad-lab-fau",
"github_project": "imucal",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "imucal"
}
JSON
