imucal.FerrarisCalibration#

class imucal.FerrarisCalibration(grav: float = 9.81, expected_angle: float = -360, calibration_info_class: type[~imucal.ferraris_calibration_info.FerrarisCalibrationInfo] = <class 'imucal.ferraris_calibration_info.FerrarisCalibrationInfo'>)[source]#

Calculate a Ferraris calibration matrices based on a set of calibration movements.

The Ferraris calibration is derived based on a well defined series of data recordings:

Static Holds

Name

Explanation

x_p

positive x-axis of sensor is aligned with gravity (x-acc measures +1g)

x_a

negative x-axis of sensor is aligned with gravity (x-acc measures -1g)

y_p

positive y-axis of sensor is aligned with gravity (y-acc measures +1g)

y_a

negative y-axis of sensor is aligned with gravity (y-acc measures -1g)

z_p

positive z-axis of sensor is aligned with gravity (z-acc measures +1g)

z_a

negative z-axis of sensor is aligned with gravity (z-acc measures -1g)

Rotations

Name

Explanation

x_rot

sensor is rotated clockwise in the x_p position around the x-axis (x-gyro shows negative values) for a well known angle (typically 360 deg)

y_rot

sensor is rotated clockwise in the y_p position around the y-axis (y-gyro shows negative values) for a well known angle (typically 360 deg)

z_rot

sensor is rotated clockwise in the z_p position around the z-axis (z-gyro shows negative values) for a well known angle (typically 360 deg)

All sections need to be recorded for a sensor and then annotated. This class then takes the data of each section (represented as a FerrarisSignalRegions object) and calculates the calibration matrizes for the gyroscope and accelerometer.

As it is quite tedious to obtain the data of each section in a seperate array, you should make use of the available helper functions to turn a continous recording into annotated sections (See the See also section)

Parameters:
sampling_rate

Sampling rate of the data

expected_angle

expected rotation angle for the gyroscope rotation.

grav

The expected value of the gravitational acceleration.

calibration_info_class

The calibration Info class to use to store the final calibration information. This should be a FerrarisCalibrationInfo or a custom subclass.

See also

imucal.ferraris_regions_from_df

Generate valid sections from preannotated dataframe.

imucal.ferraris_regions_from_interactive_plot

Generate valid sections via manual annotation in an interactive GUI.

imucal.ferraris_regions_from_section_list

Generate valid sections based on raw data and start-end labels for the individual sections.

Notes

Depending on how the axis of your respective sensor coordinate system are defined and how you perform the calibration, you might need to change the grav and expected_angle parameter.

Typical situations are:

  • If you define the positive axis direction as the direction, where the acc measures -g, change grav to -9.81 m/s^2

  • If you perform a counter-clockwise rotation during the calibration, set expected_angle to +360

  • For combinations of both, both parameter might need to be adapted

Examples

>>> from imucal import FerrarisCalibration, ferraris_regions_from_interactive_plot
>>> sampling_rate = 100  # Hz
>>> data = ...  # my data as 6 col pandas dataframe
>>> # This will open an interactive plot, where you can select the start and the stop sample of each region
>>> section_data, section_list = ferraris_regions_from_interactive_plot(
...     data, sampling_rate=sampling_rate
... )
>>> section_list.to_csv(
...     "./calibration_sections.csv"
... )  # Store the annotated section list as reference for the
... # future
>>> cal = FerrarisCalibration()  # Create new calibration object
>>> calibration_info = cal.compute(  # Calculate the actual matrizes.
...     section_data,
...     sampling_rate_hz=sampling_rate,
...     from_acc_unit="a.u.",
...     from_gyr_unit="a.u.",
...     comment="my custom comment."
...)
>>> calibration_info_class
< FerrarisCalibration object at ... >

Methods

compute(signal_regions, sampling_rate_hz, ...)

Compute the calibration Information.
__init__(grav: float = 9.81, expected_angle: float = -360, calibration_info_class: type[~imucal.ferraris_calibration_info.FerrarisCalibrationInfo] = <class 'imucal.ferraris_calibration_info.FerrarisCalibrationInfo'>) → None[source]#
compute(signal_regions: FerrarisSignalRegions, sampling_rate_hz: float, from_acc_unit: str, from_gyr_unit: str, **kwargs) → CalibrationInfo[source]#

Compute the calibration Information.

This actually performs the Ferraris calibration following the original publication equation by equation.

Examples using imucal.FerrarisCalibration#

Custom Calibration Info Subclass

Custom Calibration Info Subclass

Annotate a session and perform a Ferraris Calibration

Annotate a session and perform a Ferraris Calibration