...
An inverse kinematics method is used to compute the set of joint angles at each time step of a motion that minimizes the errors between the experimental IMU orientations and the model’s IMU Frames. The angles can then be used as inputs to other OpenSim tools and analyses or you can visualize these angles in the OpenSim GUI. The OpenSense capabilities are available through the command line and through scripting (Matlab or Python). As of OpenSim 4.2, the calibration and inverse kinematics steps are also available through the OpenSim GUI. The resulting Model and Motion can be loaded, visualized, and analyzed in the OpenSim GUI. Read more about this step in the User's Guide chapter on IMU Inverse Kinematics.
...
How to Setup the OpenSense Tools
The OpenSense workflow is available as of OpenSim 4.1. To get started, you will first need to download and install the latest OpenSim version (minimum version is 4.1). OpenSense can be downloaded from SimTK, with both Windows and Mac builds available. You can perform the OpenSense workflow on Mac or Windows through:
- Matlab scripting: To use OpenSense in Matlab, follow the Matlab scripting setup instructions.
- Python scripting: To use OpenSense in Python, follow the Python scripting setup instructions.
- Command line: To use OpenSense from the command line, read about the Command Line Utilities
- GUI: To use OpenSense tools from the application GUI (version 4.2 and later). The setup files are included under the "Models\Rajagopal_OpenSense" folder included with the distribution.
As with OpenSim, the OpenSense tools use XML settings files to specify the details of your workflow.
...
Running OpenSense to Compute Gait Kinematics
...
The basic steps for running an IMU-based OpenSense kinematics analysis are the following;
- Step One: Collect and Prepare IMU Data
- Step Two: Read Your Data into OpenSense
- Step Three: Calibrate an OpenSim Model
- Step Four: Perform IMU Sensor Tracking
- Step Five: Visualize the Results of IMU Tracking
The flowchart below shows the workflow for the example. We will import the IMU sensor data, calibrate our OpenSim model, compute inverse kinematics, and then visualize the results.
...
We use Xsens sensor data in this example, but all the steps for using APDM sensors are identical except for data reading. Read how to import APDM sensor data in the section below. Please note that the data in this example is for illustrative purposes and not intended for research use.
...
The next step is to calibrate the IMUs to an OpenSim model. The OpenSense Calibration step takes an OpenSim Model and the IMU calibration data and finds the initial orientations of the IMU Frames (i.e. offsets) relative to the OpenSim body segments. We provide a basic algorithm for calibration or you can also create your own methods of calibration by developing your own algorithms (in C++ or via scripting) to compute a default pose and/or the transforms of the IMU sensors.
To calibrate your model, you first need a setup file that stores information about the model, orientations file, and some settings to be used during the calibration procedure. In our example, this file is called myIMUPlacer_Setup.xml. You can open and edit this file in any text editor. In this settings/XML file you specify the following information:
- <model_file> To use OpenSense's calibration, you must provide an OpenSim Model in the calibration step. In our example, we are using the Rajagopal (2015) model. As noted above, on data read, your Model should have IMU Frames attached that correspond to the name_in_model specified in Step Two, or if you use our assumed naming convention (<bodyname>_imu), the calibrate step will add IMU Frames to the model as long as there is a corresponding body segment with a matching <bodyname>.
OpenSense calibration assumes that the pose of the subject in the calibration data matches the default pose of the model. In our example, the calibration pose is with the pelvis, hip, knee, and ankle at neutral, so we did not need to make any adjustments to the model's default pose. If you use a different pose, you can edit the pose of the input in the OpenSim GUI, through scripting, or in XML (see Coordinate Controls and Poses to learn how to edit the default pose through the OpenSim GUI).
<orientation_file_for_calibration> You must next provide the calibration data. OpenSense assumes the first time point corresponds to the calibration pose. If you have a trial where the calibration pose is performed at some time other than the first time row, you must edit your orientations file (or make a new one) where the first time row best corresponds to the calibration pose.
- <sensor_to_opensim_rotations> You must also provide the rotation needed to convert the IMU world Frame (typically Z up, Y to the left) to the OpenSim world Frame (Y up, Z to the right).
You can also specify optional arguments that enable OpenSense to correct or adjust for the overall difference in the heading (forward direction) of the IMU data versus that of the OpenSim model. Typically, an OpenSim model is facing in the positive X direction of the ground Frame in the initial pose, but the base IMU (e.g., on the pelvis or torso) can have any initial heading. To perform heading correction update the following settings:
- <base_imu_label> This is the label that identifies the base IMU in the provided orientation data. The default is no base_imu_label provided, and thus no heading correction will be performed.
- <base_heading_axis> This is the axis of the base IMU that represents its heading direction. The axis can be 'x', '-x', 'y', '-y', 'z' or '-z'.
An example setup file is shown below:
OpenSense will compute the angular offset between the two poses and use it to rotate all the orientation data so that the heading of the base IMU is now directed along the X-axis of the OpenSim ground reference Frame (same as the model). In our example, the pelvis_imu is set as the base IMU and z is the axis of the base IMU that corresponds to its heading, If either <base_imu_label> or <base_heading_axis> are not provided, then no heading correction is performed.
- <output_model_file> The output of the calibration step is a calibrated model, where each IMU is registered to the OpenSim model. This setting allows you to specify the output model file name.
The image below shows our example subject with IMU's on the pelvis, trunk, thighs, shanks, and feet segments and the corresponding OpenSim model with the matching pose.
...
- In the taskbar, select Tools → Plot.
- Select Y-Quantity→ Load File, and select IKResults/MT_012005D6_009-001_orientations.sto
- Select the hip_flexion_r, knee_angle_r, & ankle_angle_r coordinates.
- Select X-Quantity→ Time.
- Select Add
Customizing the OpenSense Workflow via Matlab Scripting Anchor matlabscripting matlabscripting
| matlabscripting | |
| matlabscripting |
We ran the OpenSense through the Matlab scripting environment in a simplified manner in the steps above. The Matlab interface provides additional tools to customize your workflow.
Example Matlab scripts to compute gait kinematics
We have provided a set of scripts to run through the workflow from the example above in Matlab.
Matlab scripting to create an orientations file from IMU sensor data
You can read your IMU data into OpenSense through the Matlab scripting interface. Note that, as in the example above, we will still use the myIMUMappings.xml file to define the mappings from IMU sensor to OpenSim model. A feature of the scripting interface is that you can also read and export the IMU accelerations, magnetometer, and gyro data to file.
- Launch Matlab and navigate to the OpenSenseExample folder.
- Open and run the OpenSense_IMUDataConverter.m script.
- Run the script. This will generate an orientations file, MT_012005D6_009-001_orientations.sto, as well as _acceleration, _magnetometer, and _gyro data files.
...
To use the OpenSense APDM command-line tool to read in the APDM data and export an orientations .sto file to use in OpenSense, you would use the below call.
| Code Block |
|---|
>> opensense -ReadAPDM exampleAPDM_Data.csv exampleAPDM_Settings.xml |
Future Work
The current version of OpenSense is our first step in bringing IMU-based biomechanics to the research community. We plan several additional enhancements and new features in future releases, for example:
...