Versions Compared

Old Version 7

changes.mady.by.user Jennifer Hicks

Saved on

compared with

New Version 8

changes.mady.by.user Jennifer Hicks

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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, visualized, and analyzed in the OpenSim GUI. In the future, we will also provide a direct GUI-based tool to run IMU-based kinematics. 


Back to top

...

How to Get the OpenSense

...

Tools

The OpenSense workflow is available as of OpenSim 4.1, onward. You can perform the OpenSense workflow from the command line and through Matlab and Python scripting on both Mac and Windows. on Mac or Windows through:

  • Matlab scripting
  • Python scripting
  • The command line.

As with OpenSim, the OpenSense tools use XML settings files to specify the details of your workflow. Whether you are running from the command line or MatlabTo 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. 

...

Back to top

Running OpenSense to Compute Gait Kinematics

Now that you've installed OpenSim, we will show you how to use the software through a hands-on example using example experimental IMU data from a study of lower extremity gait kinematics. The example data, models, scripts, and setup files can be found in your OpenSim resources directory under /Code/Matlab/OpenSenseExample. You can also download a zip of the example files _here_.

The basic steps for running an IMU-based OpenSense kinematics analysis are the To get started, follow the instructions below depending on how you plan to access OpenSense.

Matlab Scripting Setup

To use OpenSense in Matlab, you must install OpenSim version 4.1 and then follow the Matlab scripting setup instructions.

Python Scripting Setup

To use OpenSense in Python, you must install OpenSim version 4.1 and then follow the Python scripting setup instructions.

Command Line Setup (TODO: Make sure this is all up-to-date and possibly link to an external page)

Your OpenSim download includes a command line executable that can run all of the OpenSense tools. After you have installed OpenSense, you need to tell your system where to find the OpenSense tools by adding it to your system's path.

Mac

On Mac, you will need to open a Terminal window and edit your .bash_profile file.

  • Launch a Terminal window. You can find the Terminal under Applications → Utilities.
  • Type nano .bash_profile in the command prompt. This will launch a text editor where you can edit the file.
  • Add the path to your OpenSense bin folder. If you moved the downloaded folder to your Applications folder, it will be similar to the following; 
Code Block
export PATH="/Users/<username>/Applications/opensense/bin:$PATH"
  • Save the file using ctrl+o, then close nano (ctrl+x). 
  • Close and relaunch your Terminal window.
  • To test if the OpenSense libraries are now on your path, type in "opensense" at the command prompt. A set of instructions for using OpenSense should be printed to the Terminal window. 

You can learn more about your bash profile and how to edit it here. 

Windows

On Windows, you also need to add the path to OpenSense executables and dynamic libraries to your system path by performing the following steps: 

  • Go to your Settings-> Edit Environment Variables for your account (you can type "env" in the search box on Windows 10). 
  • The top half of the window that appears will show the list of user variables. Edit the variable named "Path" by choosing Path from the list of variables. To do this, Press Edit..., then add the location of the OpenSense "bin" folder (e.g., C:/OpenSense/bin) to the list of folders to search. When you are finished, hit OK.


Back to top

...

Running OpenSense to Compute Gait Kinematics

Now that you've installed OpenSim, we will show you how to use the software through a hands-on example using example experimental IMU data from a study of lower extremity gait kinematics. The example data, models, scripts, and setup files can be found in your OpenSim resources directory under /Code/Matlab/OpenSenseExample. You can also download a zip of the example files _here_.

The basic steps for running an IMU-based OpenSense kinematics analysis are the following;

...

Running OpenSense via Matlab Scripting 
Anchor
matlabscripting
matlabscripting

You can run OpenSense through the Matlab scripting environment. The Matlab interface provides additional tools to customize your workflow and also allows you to visualize the results of the inverse kinematics tool in real-time.

Setting up your Matlab scripting environment

To use OpenSense through Matlab, you must perform the following setup. 

Download and unzip OpenSense on your system. Add OpenSense to your system path with instructions here.

  1. Launch MATLAB. If you're using Windows make sure to "Run as administrator" (available by right-clicking the MATLAB application in the start menu, etc.).
  2. Find the configureOpenSim.m script in your OpenSense resources directory. This will be in your OpenSense install directory, <your_OpenSense_dir>/Resources/Code/Matlab.
  3. Run the configureOpenSim.m file from the current folder. 
  4. When the script finishes, you should see a dialog box notifying you if the script succeeded. If the script did not succeed, read the output in the command window for more information.
  5. Restart MATLAB; the OpenSim libraries will not be recognized until doing so.

To test that everything is configured correctly, run the following command:

>>> org.opensim.modeling.opensimCommon.GetVersion()    % This should print the version of OpenSim that you've configured with MATLAB (4.1)

The configureOpenSim.m file will detect any installations of OpenSim that were previously configured with MATLAB, and will "remove" them from MATLAB (the other OpenSim installations are not deleted, they are simply no longer configured with MATLAB). The configureOpenSim.m file also backs up any changes it makes to MATLAB configuration files.

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 OpenSenseExampleFiles 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, _

    IMU accelerations, magnetometer, and

    _

    gyro

     data files

    data to file. 

    Matlab scripting for calibration

    You can also perform calibration through Matlab scripting. The scripting interface is similar to the command line. You provide the model names, the orientations file, and, optionally, the base IMU name and heading. You can also specify if you want to have the calibrated model visualized.

    ...

    • Launch Matlab and navigate to the OpenSenseExampleFiles 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. 

    Matlab scripting

    ...

    The Scripting interface for the OpenSense IMUInverseKinematicsTool gives you finer control over the inverse kinematic properties. In particular, you can visualize the Inverse Kinematics tracking.

    ...

    for calibration

    You can also perform calibration through Matlab scripting. The scripting interface is similar to the command line. You provide the model names, the orientations file, and, optionally, the base IMU name and heading. You can also specify if you want to have the calibrated model visualized.

    To perform calibration, run the OpenSense_CalibrateModel.m script in Matlab. A visualizer visualization window will open, showing the kinematic tracking of the IMU orientation by the model. The results of the orientation tracking will be written to the IKResults directory. Results can be plotted in the OpenSim GUI similarly done above.

    ...

    You can run OpenSense through the Python scripting environment. The Python interface provides additional tools to customize your workflow and also allows you to visualize the results of the inverse kinematics tool in real-time.

    Setting up your Python scripting environment

    To use OpenSense in Python, you must perform the following setup. 

    Download and unzip OpenSense on your system. Add OpenSense to your system path with instructions here.

    1. Download and Setup Python 3 from Python.org. The installer will place Python on your system path for you. 
    2. Open a Command Prompt (Windows) or Terminal (MacOS) and navigate to <your_OpenSense_dir>/Resources/Code/Python. 
    3. Execute the following command 

    ...

    calibrated model, as well as the calibrated model being written to file. 

    Matlab scripting to run inverse kinematics

    The Scripting interface for the OpenSense IMUInverseKinematicsTool gives you finer control over the inverse kinematic properties. In particular, you can visualize the Inverse Kinematics tracking.

    To perform Inverse Kinematics, open and run the file OpenSense_OrientationTracking.m script in Matlab. A visualizer window will open, showing the kinematic tracking of the IMU orientation by the model. The results of the orientation tracking will be written to the IKResults directory. Results can be plotted in the OpenSim GUI similarly done above.

    Running OpenSense via Python Scripting 
    Anchor
    pythonscripting
    pythonscripting

    You can run OpenSense through the Python scripting environment. The Python interface provides additional tools to customize your workflow and also allows you to visualize the results of the inverse kinematics tool in real-time.

    Setting up your Python scripting environment

    Example Python scripts to compute gait kinematics

    ...