Package: imucal
imucal - A Python library to calibrate 6 DOF IMUsThis package provides methods to calculate and apply calibrations for 6 DOF IMUs based on multiple different methods.So far supported are:Ferraris Calibration (Ferraris1994/Ferraris1995)Ferraris Calibration using a TurntableFor more information check the quickstart guide below and thedocumentation.Installationpip install imucalTo use the included calibration GUI you also needmatplotlib(version >2.2).
You can install it using:pip install imucal[calplot]Supported Python versions and Platformsimucalis officially tested on Python 3.7, 3.8, 3.9 and 3.10.
It should further work with all major operating systems.QuickstartThis package implements the IMU-infield calibration based onFerraris1995.
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}_rotfor the rotations.
As example,acc_y_awould be the 3D-acceleration data measured during a static phase, where they-axiswas
orientedantiparallelto the gravitation vector.
For more information on how to perform the calibration checkour guide.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
useferraris_regions_from_dfandferraris_regions_from_section_list,
respectively to convert the data into the correct format for the calibration (section_datain 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.fromimucalimportferraris_regions_from_interactive_plot# Your data as a 6 column dataframedata=...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 futuresection_list.to_csv('./calibration_sections.csv')# This is optional, but recommendedIndependent of how you obtained thesection_datain the correct format, you can now calculate the calibration
parameters:fromimucalimportFerrarisCalibrationsampling_rate=100#Hzcal=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 datacal_mat.to_json_file('./calibration.json')Applying a calibration:fromimucal.managementimportload_calibration_infocal_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 theUser Guidesor theExamples.Further Calibration MethodsAt 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 viaGitHub Issue, and we will try to help you as good
as possible.CitationIf you are usingimucalin your scientific work, we would appreciate if you would cite ourJOSS paperor 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.ContributingAll project management and development happens throughthis GitHub project.
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 SetupWe usepoetryto 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.gitclonehttps://github.com/mad-lab-fau/imucalcdimucal
poetryinstall--all-extrasTo run tests/the linter/... we usepoethepoet.
You can see all available commands by running:poetry run poe listThis 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_versionYou execute any command by runningpoetry run doit <command-name>Updating dependenciesIf you update or add dependencies using (poetry addorpoetry update) you will see that thepyproject.tomland thepoetry.lockfiles are both updated.
Make sure you commit the changes tobothfiles.
Otherwise, wrong versions of dependencies will be used in the CI and by other developers.In case you update dependencies by directly editing thepyproject.tomlfile, you need to be very careful and make sure, you runpoetry lock [--no-update]afterwards.
Otherwise, the lock file will be out of date.In general, it is a good idea to just runpoetry updatefrom time to time.
This will install the latest version of all dependencies that are still allowed by the version constrains in thepyproject.toml.
This allows to check, if everything still works well with the newest versions of all libraries.