# IMUs

These routines facilitate the calculation of 3d movement kinematics for recordings from inertial measurement units (IMUs). Currently data from 4 systems are supported:

- XSens
- xio
- YEI
- polulu

## Functions

### Data-Handling

- `imus.import_data()` ... Read in rate and 3D parameters from different IMUs.
- `sensors.xio.get_data()` ... Read in rate and 3D parameters from xio sensors.
- `sensors.xsens.get_data()` ... Read in rate and 3D parameters from XSens sensors.
- `sensors.yei.get_data()` ... Read in rate and 3D parameters from YEI sensors.
- `sensors.polulu.get_data()` ... Read in rate and 3D parameters from polulu sensors.

### Data-Analysis

- `imus.calc_QPos()` ... Calculate orientation and position, from angular velocity and linear acceleration
- `imus.kalman_quat()` ... Calculate orientation from IMU-data using an Extended Kalman Filter

## Class

`imus.IMU`([inFile, inType, inData]) | Class for working with working with inertial measurement units (IMUs)

### Methods

`imus.IMU.calc_orientation`(R_initialOrientation) | Calculate the current orientation
`imus.IMU.calc_position`(initialPosition) | Calculate the position, assuming that the orientation is already known.
`imus.IMU.setData`(data) | Set the properties of an IMU-object.

## Classes for Sensor-Integration

`imus.MahonyAHRS`([SamplePeriod, Kp, Ki, ...]) | Madgwick’s implementation of Mayhony’s AHRS algorithm
`imus.MadgwickAHRS`([SamplePeriod, Beta, ...]) | Madgwick’s gradient descent filter.

## Details

Utilities for movements recordings with inertial measurement units (IMUs) Currently data from the following systems are supported

> - XIO
> - XSens
> - YEI
> - Polulu

class `imus.``IMU`(inFile=None, inType='XSens', inData=None)

  Class for working with working with inertial measurement units (IMUs)

  An IMU object can be initialized
    - by giving a filename
    - by providing measurement data and a samplerate
    - without giving any parameter; in that case the user is prompted to select an infile

  Parameters: | inFile (string) – path- and file-name of data file inType (string) – Description of the type of the in-file. Has to be one of the following: xio XSens yei polulu inData (dictionary) – The following fields are required: acc : (N x 3) array Linear acceleration [m/s^2], in the x-, y-, and z-direction omega : (N x 3) array Angular velocity [deg/s], about the x-, y-, and z-axis [mag] : (N x 3) array (optional) Local magnetic field, in the x-, y-, and z-direction rate: integer sample rate [Hz]

  Notes

  IMU-Properties:
    - source
    - acc
    - omega
    - mag
    - rate
    - totalSamples
    - duration
    - dataType

  Examples

      >>> myimu = IMU(r'tests/data/data_xsens.txt', inType='XSens')
      >>>
      >>> initialOrientation = np.array([[1,0,0],
      >>>                                [0,0,-1],
      >>>                                [0,1,0]])
      >>> initialPosition = np.r_[0,0,0]
      >>>
      >>> myimu.calc_orientation(initialOrientation)
      >>> q_simple = myimu.quat[:,1:]
      >>>
      >>> calcType = 'Madgwick'
      >>> myimu.calc_orientation(initialOrientation, type=calcType)
      >>> q_Kalman = myimu.quat[:,1:]

  `calc_orientation`(R_initialOrientation, type='quatInt')

    Calculate the current orientation

    Parameters: | R_initialOrientation (3x3 array) – approximate alignment of sensor-CS with space-fixed CS type (string) – ‘quatInt’ .... quaternion integration of angular velocity ‘Kalman’ ..... quaternion Kalman filter ‘Madgwick’ ... gradient descent method, efficient ‘Mahony’ .... formula from Mahony, as implemented by Madgwick

  `calc_position`(initialPosition)

    Calculate the position, assuming that the orientation is already known.

  `setData`(data)

    Set the properties of an IMU-object.

class `imus.``MadgwickAHRS`(SamplePeriod=0.00390625, Beta=1.0, Quaternion=[1, 0, 0, 0])

  Madgwick’s gradient descent filter.

  `Update`(Gyroscope, Accelerometer, Magnetometer)

    Calculate the best quaternion to the given measurement values.

class `imus.``MahonyAHRS`(SamplePeriod=0.00390625, Kp=1.0, Ki=0, Quaternion=[1, 0, 0, 0])

  Madgwick’s implementation of Mayhony’s AHRS algorithm

  `Update`(Gyroscope, Accelerometer, Magnetometer)

    Calculate the best quaternion to the given measurement values.

`imus.``calc_QPos`(R_initialOrientation, omega, initialPosition, accMeasured, rate)

  Reconstruct position and orientation, from angular velocity and linear acceleration. Assumes a start in a stationary position. No compensation for drift.

  Parameters: | omega (ndarray(N,3)) – Angular velocity, in [rad/s] accMeasured (ndarray(N,3)) – Linear acceleration, in [m/s^2] initialPosition (ndarray(3,)) – initial Position, in [m] R_initialOrientation (ndarray(3,3)) – Rotation matrix describing the initial orientation of the sensor, except a mis-orienation with respect to gravity rate (float) – sampling rate, in [Hz]
  Returns: | q (ndarray(N,3)) – Orientation, expressed as a quaternion vector pos (ndarray(N,3)) – Position in space [m]

  Example

      >>> q1, pos1 = calc_QPos(R_initialOrientation, omega, initialPosition, acc, rate)

`imus.``import_data`(inFile=None, type='XSens', paramList=['rate', 'acc', 'omega', 'mag'])

  Read in Rate and stored 3D parameters from IMUs

  Parameters: | inFile (string) – Path and name of input file type (sensor-type. Has to be either ['XSens', 'xio', 'yei', 'polulu']) – paramList (list of strings) – You can select between [‘rate’, ‘acc’, ‘omega’, ‘mag’, ‘others’]
  Returns: | List, containing rate (float) – Sampling rate [List of x/y/z Parameter Values]

  Examples

      >>> data = import_data(fullInFile, type='XSens', paramList=['rate', 'acc', 'omega'])
      >>> rate = data[0]
      >>> accValues = data[1]
      >>> Omega = data[2]

`imus.``kalman_quat`(rate, acc, omega, mag)

  Calclulate the orientation from IMU magnetometer data.

  Parameters: | rate (float) – sample rate [Hz] acc ((N,3) ndarray) – linear acceleration [m/sec^2] omega ((N,3) ndarray) – angular velocity [rad/sec] mag ((N,3) ndarray) – magnetic field orientation
  Returns: | qOut – unit quaternion, describing the orientation relativ to the coordinate system spanned by the local magnetic field, and gravity
  Return type: | (N,4) ndarray

  Notes

  Based on “Design, Implementation, and Experimental Results of a Quaternion-Based Kalman Filter for Human Body Motion Tracking” Yun, X. and Bachman, E.R., IEEE TRANSACTIONS ON ROBOTICS, VOL. 22, 1216-1227 (2006)

Import data saved with XIO-sensors

`sensors.xio.``get_data`(in_selection)

  Get the sampling rates, as well as the recorded data.

  Parameters: | in_selection (string) – Directory containing all the data-files, or filename of one file in that directory
  Returns: | out_list – Contains the following parameters: rate acceleration angular_velocity mag_field_direction packet_nr
  Return type: | list

`sensors.xio.``read_datafile`(in_file)

  Read data from an XIO “CalInertialAndMag”-file.

  Parameters: | in_file (string) – Has to be the name of the “CalInertialAndMag”-file.
  Returns: | out_list – Contains the following parameters: acceleration angular_velocity mag_field_direction packet_nr
  Return type: | list

`sensors.xio.``read_ratefile`(reg_file)

  Read send-rates from an XIO sensor. “Disabled” channels have the “rate” set to “None”.

  Parameters: | in_file (string) – Has to be the “Registers”-file.
  Returns: | rates – Contains the send-rates for the different “params”.
  Return type: | directory

Import data saved with XSens-sensors

`sensors.xsens.``get_data`(in_file)

  Get the sampling rate, as well as the recorded data.

  Parameters: | in_file (string) – Filename of the data-file
  Returns: | out_list – Contains the following parameters: rate acceleration angular_velocity mag_field_direction
  Return type: | list

Import data saved with YEI-sensors

`sensors.yei.``get_data`(in_file)

  Get the sampling rate, as well as the recorded data.

  Parameters: | in_file (string) – Filename of the data-file
  Returns: | out_list – Contains the following parameters: rate acceleration angular_velocity mag_field_direction
  Return type: | list

Import data saved with polulu-sensors https://www.pololu.com/product/2738 These are low-cost IMUS (<20 US$), where acceleration/gyroscope data are not sampled at the same time as the magnetic field data (just over 100 Hz). As a result, the interpolated sampling rate has to be set by hand.

`sensors.polulu.``get_data`(inFile, rate=125)

  Get the sampling rate, as well as the recorded data.

  Parameters: | in_file (string) – Filename of the data-file
  Returns: | out_list – Contains the following parameters: rate acceleration angular_velocity mag_field_direction
  Return type: | list