Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add note regarding 4.2 changes

...

Info

Welcome to the OpenSense documentation! To complete this example, you will need to download OpenSim 4.1 or later. If you try the example and software, please send any issues or feedback to opensim@stanford.edu. Note that the functionality has been improved in later versions including the introduction of visualization tools for IMU data in version 4.2.


Anchor
topofpage
topofpage

OpenSense is a new workflow for analyzing movement with inertial measurement unit (IMU) data. In the page below, we introduce you to the tool, show you how to get started, and describe how to use the software to compute and analyze gait kinematics through a hands-on example.

...

OpenSense provides an interface to associate and register each IMU sensor with a body segment of an OpenSim model (as an IMU Frame). We provide a basic calibration routine in which the first time step of IMU data is registered to the default pose of the model. You change the registration pose by changing the default coordinate values of the model. You can also write your own calibration procedures in Matlab, Python, etc. to optimize the initial pose of the model for calibration using other data sources (markers, goniometer, etc). Read more about these steps in our User's Guide chapter on the IMU Placer tool.

Computing Inverse Kinematics

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). The resulting Model and Motion can be loaded. 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. In the future, we will also provide a direct GUI-based tool to run IMU-based kinematics. Read more about this step in the User's Guide chapter on IMU Inverse Kinematics.


...

How to Setup the OpenSense Tools

...

...

  • 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. 


Back to top

...

Running OpenSense to Compute Gait Kinematics

...

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.  

...

Once you have collected and pre-processed your data, you must convert it to OpenSim's file format and associate it with an OpenSim model. Data from IMUs can be in various formats: a single file with numbered sensor names (e.g., APDM) or multiple files with sensor-specific numbering (e.g., Xsens). Upon import, OpenSim will create a single, time synced, Storage (.sto) file format for orientations, converting the rotation matrices into quaternions. 

In this example, we will be using data from an Xsens system that has been pre-processed (e.g., time-syncing and sensor fusion has been performed)  and exported to an Xsens text format. You can find this data in the IMUData folder. Each Xsens sensor is represented by a single text (.txt) file with time histories of the internal sensor data. We assume the data reported by the IMU system to include orientations (in the case of XSens these are assumed to be direction-cosine-matrices).

To read your data, you first need to create a file that lets OpenSense know which sensor is associated with which body segment in the Model. In our example, this file is called myIMUMappings.xml. You can open and edit this file in any text editor. In this settings/XML file you specify the following information:

...

Expand
titleUse the command line ...

To read your data from the command line, use the following steps.

  • Launch a terminal window (or command prompt) and navigate to the OpenSenseExample folder.
  • At the prompt, enter the following command. 
Code Block
>> opensense -ReadXReadXsens IMUData/ myIMUMappings.xml 

Since we are working with Xsens data, we use the -ReadX option (read Xsens data). We next provide the directory where the IMU sensor data is (IMUData) and then the name of the local IMU Mappings file (myIMUMappings.xml).

Running this command line call will generate an orientations file called <trial_name>_orientations.sto (<trial_name> is defined in your myIMUMappings.xml file) in your OpenSenseExample folder. 

...

Code Block
% Setup and run the IMUPlacer tool, with model visualization set to true
myIMUPlacer = IMUPlacer('myIMUPlacer_Setup.xml'); 
myIMUPlacer.run(true);  

% Write the calibrated model to file
myIMUPlacer.getCalibratedModel().print('RajagoalRajagopal_2015_calibrated.osim');

Command-line tool to calibrate a model in OpenSense

...

A visualizer window will appear, showing the calibrated model. The pose of the model is determined by the model's default pose and will not change from one calibration to the next (unless you edit the model's default pose). What will change is the orientation of the sensors attached to each body. You can zoom in on the sensors, represented as small orange bricks located at the COM of each body. 


Note: You can close the visualizer window, when selected, by using the keyboard shortcut of ctrl-Q (command-Q on Mac).

You will see a print out the calibration offset for each IMU. This is the transform between the model body and the IMU sensor. 

To continue the calibration, and print the calibrated model to file, select the visualizer window and press any key to continue. 

The Calibrated Model is written to file and will have the postfix '' added (i.e., if the input Model file is called model.osim, the output calibrated model file will be named model_calibrated.osim).

...

Using the OpenSim Application (GUI)

As of version 4.2 you can execute this step from the OpenSim application by invoking Tools→IMU Placer and loading the settings from the file myIMUPlacer_Setup.xml created above, or entering the data manually in the dialog as shown below, then hitting the Run button. After you run the tool, a new model with IMUs placed on it will appear in the application.

Image Added


Step Four: Perform IMU Sensor Tracking 
Anchor
stepfour
stepfour

Now that you have read in your data and calibrated your model, you can use OpenSense's Inverse Kinematics to track Orientation data from IMU sensors. The Inverse Kinematics step finds the pose of the model at each time-step that minimizes, in the least-squares sense, the difference between the orientation data from the IMU sensors and the IMU Frames on your calibrated model. The computed kinematics depend on both the calibrated model and the sensor data. Thus to perform inverse kinematics tracking of orientation data you need (i) a Calibrated Model (.osim), (ii) an orientations file (as quaternions), and (iii) an Inverse Kinematics Setup file (.xml). Using the calibrated model we generated in the previous section, we will track orientation data for walking that we read in during Step Two. 

In a text editor— such as Notepad++, SublimeText, Atom, or Matlab— open the myIMUIK_Setup.xml file. The setup file stores properties that tell OpenSense how to run the Inverse Kinematics simulation. In the setup file, you specify:

  • <time_range> The time range for the inverse kinematics tracking (in seconds). In our example, we use data between 7.25 and 15 seconds.

  • <sensor_to_opensim_rotations> 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). 
  • <model_file_name> The name/path to the calibrated model file (.osim) to be used in tracking. In our example, this is the calibrated_Rajagopal_2015_calibrated.osim file that was the output of Step Three.
  • <orientations_file_name> The name/path to a .sto file of sensor Frame orientations (as quaternions) that will be tracked. In our example, this is the MT_012005D6_009-001_orientations.sto we created in Step Two.
  • <results_directory> The directory where the results will be printed to file. 

An example setup file is shown below.

 

For now, leave these settings as they are. This settings file can be copied and edited for your own workflow.


...

Expand
titleUse the command line ...

To perform Inverse Kinematics with OpenSense from the command line, use the following steps.

  • Launch a terminal window (or command prompt) and navigate to the OpenSenseExample folder.
  • At the prompt, enter the following command. 
Code Block
>> opensense -IK myIMUIK_Setup.xml
The output motion file is written to file and will have the prefix 'ik_' added (i.e., if the input orientations file is called MT_012005D6_009-001_orientations.sto, the output motion file will be named IKResults/ik_MT_012005D6_009-001_orientations.mot)
  • , enter the following command. 
Code Block
>> opensense -IK myIMUIK_Setup.xml

The output motion file is written to file and will have the prefix 'ik_' added (i.e., if the input orientations file is called MT_012005D6_009-001_orientations.sto, the output motion file will be named IKResults/ik_MT_012005D6_009-001_orientations.mot)

Using the OpenSim Application (GUI)

As of version 4.2 you can execute this step from the OpenSim application by invoking Tools→IMU Inverse Kinematics and loading the settings from the file imuInverseKinematics_Setup.xml created above, or entering the data manually in the dialog as shown below, then hitting the Run button. The IK problem will be solved and the solution will be animated in the application.

Image Added

Step Five: Visualize the Results of IMU Tracking 
Anchor

...

visualizeResults

...

visualizeResults

You can view and plot the results of the simulation using the OpenSim application (GUI) visualizer. You can also use OpenSim's plotter to plot the kinematics or perform further analyses with other OpenSim pipeline tools. (Note that you will generally need to scale your model and provide ground reaction forces if you want to generate muscle driven simulations.)

To view the Inverse Kinematics results:

  • Open the OpenSim 4 application.1 application.
  • Open the model: calibrated_Rajagopal_2015.osim
  • Load the motion you created in Step Four: IKResults/ik_MT_012005D6_009-001_orientations.mot.  Since the IMUs cannot track global translations, only relative orientations, the model appears to rotate about a single place. 

...

Learn More and Future Work

Importing APDM Sensor Data 
Anchor
readapdmfiles
readapdmfiles

Typically, APDM exports a trial as a .h5 file and as a .csv ASCII text file that is comma delimited, grouped in order by sensor. The OpenSense APDM Reader can only read CSV file types.

To read the APDM CSV file, you must create a file that associates the column labels in the APDM .csv file with an OpenSim model body segment. You can open and edit this file in any text editor. In this settings/XML file you specify the following information:

  • <ExperimentalSensor name> A string to identify the specific column in the APDM sensor file. In our example, the first sensor uses the column name "Trunk".
  • <name_in_model> The corresponding name of the sensor in the OpenSim Model. The first sensor is associated with the torso_imu segment of the model.


An example Download an example APDM Settings file for APDM sensors can be Downloaded here. and a corresponding example APDM sensor dataYou can open and edit this file in any text editor. A snippet of the Settings file is shown below:

Image RemovedImage Added

Matlab commands to create an orientations file from APDM IMU sensor data

...

Code Block
% Import the OpenSim libraries
import org.opensim.modeling.*;

% Define the trial name
trialName = 'datafile2exampleAPDM_Data.csv';

% Create an APDMDataReader and supply the settings file that maps IMUs to your model
apdmSettings = XsensDataReaderSettingsAPDMDataReaderSettings('myIMUMappingsexampleAPDM_Settings.xml'); 
APDMDataReadermyAPDMDataReader = XsensDataReaderAPDMDataReader(apdmSettings);
 
% Read the quaternion data and write it to a STO file for use in OpenSense workflow
tables = APDMDataReadermyAPDMDataReader.read( trialName );
quaternionTable = APDMDataReadermyAPDMDataReader.getOrientationsTable(tables);
STOFileAdapterQuaternion.write(quaternionTable,  strrep(trialName,'.csv', '_orientations.sto') );

...

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 -ReadAReadAPDM myAPDFileexampleAPDM_Data.csv myAPDMMappingsexampleAPDM_Settings.xml 

Back to top


Future Work

...

  • Direct support for additional IMU sensors
  • More advanced approaches to calibration and interfaces to better support users developing their own calibration protocolsSupport for OpenSense inverse kinematics directly in the OpenSim application (GUI)

  • Tools to easily visualize data and results for debugging (e.g., are the sensors registered to the correct body segments?)

...