WELCOME TO THE NEW PLATFORM FOR THE OPENSIM DOCUMENTATION
Remember to update your bookmarks with our new URL.
If you find missing content or broken links, let us know: opensim@stanford.edu
Part I: Computing Joint Moments with OpenSim
A common pipeline to estimate joint moments is to sequentially use the Scale Tool, Inverse Kinematics Tool, and Inverse Dynamics Tool. We’ll use OpenSim to perform these steps on a walking trial of a subject walking overground across three force plates.
1. Scaling a Model
The Scale Tool in OpenSim is used to create a subject specific model by adjusting the model parameters and markers. Two of the main uses include the following:
- The tool can adjust the mass and the lengths along the three major axes of the bodies in a model. This is often done using experimental data during a static pose trial to calculate scale factors for each body in the model based on anatomical markers. In this tutorial, we use the pre-calculated scale factors from the original work.
- The tool can move markers to a specific location based on the experimental data. This is often used to correctly place tracking markers on the model.
More information on how this is done in OpenSim can be found on the Scaling documentation page.
In this tutorial, we will use a pre-configured Scale Tool setup file to scale the generic model to generate a subject-specific model.
- Load the generic model file.
- Select File -> Open Model…
- Select the generic model file (Rajagopal2015.osim) found in the root folder of the downloaded files.
- You should see the generic model loaded in the Navigator pane named FullBodyModel_MuscleActuatedLowerLimb_TorqueActuatedUpperBody
- Scale the model using a pre-configured setup file.
- Select Tools -> Scale Model…
- Select Load…, then navigate to the subfolder Scale and choose scale_setup_walk.xml.
- Explore the Scale Tool configuration. In particular note the following:
- On the Settings tab, take note of the following:
- Under “Subject Data” and “Generic Model data”, compare the mass of the subject to the generic model
- Under “Adjust model markers”, look at the time range of data that will be used (“Average markers between times”).
- Under “Subject Data”, note that additional markers will be added to the model specified by the file under “Add markers from file”. This can be useful if your marker set does not match the marker set provided by the original model.
- On the Scale Factors tab, review the numbers provided in the Applied Scale Factors column. Scale factors can be given as 3 numbers to scale differently along each principal axis of the body. Numbers greater than 1 indicate that the scaled body will be longer along that axis.
- Click Run to scale the model.
Note that the root directory should now have a model named subject_scaled_walk.osim, which is the same scaled model that now appears in the visualizer.
Questions
- By looking at the mass of the subject and generic model, as well as the scale factors, is the subject generally larger or smaller than the generic model? Support your answer by providing the mass and a few scale factors.
- What is the time range of data that was used to adjust the model’s markers? Compared to a typical movement to capture, such as one full stride of walking, is this range short or long? Why might the time range be short or long for a static trial?
2. Visualizing input motion data
Before using the Inverse Kinematics tool to calculate joint angles, we will visualize the input marker and force plate data.
- Close the generic and scaled models: Right click each of the models and select Close.
- Load the experimental data
- Load the motion capture marker data: Select File -> Preview Experimental Data…, then navigate back to the ExpData subfolder and open motion_capture_walk.trc.
- Load the force plate data: Select File -> Preview Experimental Data…, then navigate back to the ExpData subfolder and open grf_walk.mot.
- Sync the experimental data
- In the Navigator pane, expand ExperimentalData_0 and ExperimentalData_1.
- Select both motion_capture_walk.trc and grf_walk.mot by Ctrl+Click (or Command+Click on Mac)
- Right-click one of the selected files and select Sync Motions.
- Visualize the two data streams together
- Click the play button above the visualizer.
- It can also be helpful to slow the motion down by changing the Speed to a smaller number (e.g., 0.5 for half speed).
Questions
- Over what time range is marker data provided?
- Over what time range is GRF data provided (i.e., what is the earliest time and latest time that contain non-zero forces)?
- This walking trial was collected overground (i.e., not on a treadmill) with force plates located in the middle of the motion laboratory.
- How many foot strikes have GRF data?
- Over what time range do you have complete GRF data (i.e., all external loads are accounted for)?
3. Inverse Kinematics
We will use the motion capture marker data and the scaled model to estimate joint angles using the Inverse Kinematics (IK) tool. More information about the tool can be found on its documentation page.
- Close any open models and experimental data (Right-click -> Close)
- Load the scaled model.
- Select File -> Open Model…
- Select the scaled model file (subject_scaled_walk.osim) found in the root folder of the downloaded files.
- You should see the scaled model loaded in the Navigator pane named subject_scale_walk.
- Run a pre-configured Inverse Kinematics tool setup file.
- Select Tools -> Inverse Kinematics…
- Select Load…, then navigate to the subfolder IK and choose ik_setup_walk.xml.
- Explore the settings that have been loaded
- In the Settings tab:
- IK Trial: Marker data for trial: the input motion capture marker data
- Output: Motion file: the output file where the results will be printed
- In the Weights tab:
- In the upper pane, scroll through the different markers and their associated weights.
- Note which markers have a higher or lower weight associated with them.
- You can visualize where these markers are on the model:
- In the navigator pane, expand the model and then expand Markers.
- To see an individual marker, right-click the marker name and select Display -> Show Only.
- Run the tool by clicking the Run button.
- Explore the results.
- Visualize the motion by clicking the Play button.
- More detailed information about the marker error is provided in the Messages tab.
Questions
- List a few markers with higher weights. Why do these markers have higher weights when studying a motion like walking and for a model like this one? It may be helpful to refer to the IK documentation, and specifically How Inverse Kinematics Works.
- List a few markers with lower weights. Why do these markers have lower weights when studying a motion like walking and for a model like this one?
- At what times is the overall error, as measured by RMSE, highest? What are some possible reasons why this could happen?
- Which marker(s) have particularly high errors? Why might these marker(s) be prone to higher errors?
4. Inverse Dynamics
We will use the Inverse Kinematics results, the force plate data, and the scaled model to estimate joint moments using the Inverse Dynamics (ID) tool. More information about the tool can be found on its documentation page.
- Configure and run the Inverse Dynamics tool.
- Select Tools -> Inverse Dynamics…
- Setup the Main Settings tab
- In the Input pane, select Loaded motion and use the IKResults motion from the previous step.
- Check the box to filter the coordinates and set the cutoff frequency to 6 Hz.
- In the Output section, specify an output directory (e.g., <YourWorkingDir>/ID).
- Setup the External Loads tab
- Select the External Loads tab and check the External Loads box.
- Edit the External Loads settings by clicking the pencil icon to the right of the textbox.
- For the Force data file, click the folder icon to the right, then navigate to and select the <YourWorkingDir>/ExpData/grf_walk.mot file. This file describes the force applied at the foot's center of pressure (CoP).
- Add the forces listed in the motion file for the right foot by clicking the "Add..." button.
- Provide a name (e.g., "Right_GRF").
- Apply the force to the calcn_r body.
- Check "Applies Force" and select "Point Force".
- Force Columns: select "ground_force_r_vx" from the first drop-down box; "ground_force_r_vy" and "ground_force_r_vz" will be populated automatically.
- Point Columns: select "ground_force_r_px" from the first drop-down box; the corresponding "y" and "z" entries will again be populated automatically.
- The GRF free moment is a torque, so check "Applies Torque".
- Torque Columns: select "ground_torque_r_x", "ground_torque_r_y", and "ground_torque_r_z".
- The GRF and CoP are both expressed in the ground (laboratory) frame, so click OK.
- Add the forces listed in the motion file to the left foot by clicking the “Add…” button again.
- Provide a name (e.g., "Left_GRF").
- Apply the force to the calcn_l body.
- Check "Applies Force" and select "Point Force".
- Force Columns: select "ground_force_l_vx" from the first drop-down box; "ground_force_l_vy" and "ground_force_l_vz" will be populated automatically.
- Point Columns: select "ground_force_l_px" from the first drop-down box; the corresponding "y" and "z" entries will again be populated automatically.
- The GRF free moment is a torque, so check "Applies Torque".
- Torque Columns: select "ground_torque_l_x", "ground_torque_l_y", and "ground_torque_l_z".
- The GRF and CoP are both expressed in the ground (laboratory) frame, so click OK.
- Click "Save...", navigate to where you want to save the file (e.g., <YourWorkingDir>/ID) and enter a filename for the External Force input (e.g., GRF.xml).
- Click "Save..." and enter a filename for the ID settings (e.g., Setup_ID.xml).
- Run the tool, then close the Inverse Dynamics Tool window.
Questions
- Plot the applied forces (i.e., pelvis_tx_force, pelvis_ty_force, and pelvis_tz_force) and torques (i.e., pelvis_tilt_moment, pelvis_list_moment, pelvis_rotation_moment) that act on the pelvis as functions of time. The data are in the ID/inverse_dynamics.sto file. These applied forces and torques are the residuals.
- To better understand on which degrees of freedom and along which directions each of these forces and torques act, use the coordinate sliders to investigate how each pelvis degree of freedom (pelvis_tx, pelvis_ty, pelvis_tz, pelvit_tilt, pelvis_list, and pelvis_moment) moves the model. It may be helpful to reset the pose by clicking Poses -> Default when investigating each degree of freedom. In particular, note the following:
- For each translational degree of freedom, which direction does the model move (e.g., forward/back, up/down, left/right). These directions indicate the coordinate frame of the pelvis (e.g., pelvis_tx motion will indicate the x-axis direction of the pelvis coordinate frame).
- For each rotational degree of freedom, about which axis of the pelvis frame does that degree of freedom move the model?
- When are these residuals the highest?
- Of the three forces, which residual force is the highest? Why might this be?
- Plot the experimentally measured vertical ground reaction forces (ground_force_r_vy [right leg] and ground_force_l_vy [left leg]) from the grf_walk.mot file and the pelvis_ty_force from the ID results as functions of time.
- How do the vertical ground reaction forces compare to the pelvis_ty_force residual?
- Looking at this plot, why are residuals highest at the times specified by question 1a?
- During what times is it valid to analyze the inverse dynamics data? How do these times compare to those from the questions in the section “Visualizing input motion data”?
5. Residual Reduction Algorithm
OpenSim provides the Residual Reduction Algorithm (RRA) tool to adjust the model mass properties and kinematics to improve dynamic consistency between marker and force plate data by solving a torque-driven tracking problem. Often, this step can be repeated iteratively to improve results. In this lab, we will set up and run the tool once. More information about the tool can be found on its documentation page. A tutorial with more in-depth steps for using RRA is The Strength of Simulation: Estimating Leg Muscle Forces in Stance and Swing.
- Set up and run RRA.
- Open the RRA tool: Select Tools -> Reduce Residuals…
- Configure options in the Main Settings tab.
- Select the input motion: Under the “Input” section, for “Desired kinematics”, select the IK output file (e.g., <YourWorkingDir>/IK/results_walk/ik_output_walk.mot)
- Check the “Filter Kinematics” box and set the cutoff frequency to 6 Hz.
- Select the tracking tasks file: Under the “Input” section, for “Tracking tasks”, select the file located at <YourWorkingDir>/RRA/rra_tasks_walk.xml.
- This file allows users to adjust the optimizer to track certain coordinates more than others by increasing the weight to track coordinates more closely, or decreasing the weight to track coordinates less closely.
- You can see the corresponding weights for each coordinate by opening the tracking tasks file in a text editor (e.g., Notepad, Sublime Text, Notepad++).
- One way to reduce residuals is to change the center of mass location of one of the bodies of the model.
- In the “Reduce Residuals” section, check the box for “Adjust model”, and then provide the path to where the new model will be written to file (e.g., <YourWorkingDir>/subject_scaled_walk_rra.osim)
- For “Body COM to adjust”, select torso.
- In the Time section, adjust the start and end times to times in which performing Inverse Dynamics is valid.
- Set the folder to where the output results, such as the adjust kinematics, will be saved: Under the “Output” section, choose the directory <YourWorkingDir>/RRA/results.
- Configure options in the “Actuators and External Loads” tab.
- Replace the model’s muscles with torque actuators:
- Under the “Actuators” section, for “Additional force set files”, click Edit…
- Click Add.
- Click the folder icon next to the bottom dialogue box.
- Select the actuator file: <YourWorkingDir>/RRA/rra_actuators.xml.
- Click OK.
- Apply the External Loads. Instead of creating another file as we did in ID, we will use a pre-configured file in the RRA folder.
- Click the checkbox for the “External Loads” section
- For “External loads specification file”, select <YourWorkingDir>/RRA/grf_walk.xml.
- Save the setup file as <YourWorkingDir>/RRA/Setup_RRA.xml.
- Run the tool.
Questions
- Open the Messages pane and locate the recommended overall mass adjustment from the last run of RRA (e.g., "pelvis: orig mass = xxxxx, new mass = yyyyy"). Note that the units are in kilograms (kg). What is the recommended mass adjustment?
- Investigate how the kinematics were adjusted by RRA. The positional errors between the RRA adjusted kinematics and the input IK kinematics can be found in your RRA results folder in the file ending in “pErr.sto”. Plot all of the errors for all coordinates (note: a quick way to do this is to use the plotter and choose “select all shown” and then deselect “time”).
- What are the two coordinates with the largest maximum changes?
- What is the maximum value for each of these coordinates? Rotational coordinates have units of radians, and translational coordinates have units of meters.
- Why or why not are the magnitude of these changes reasonable?
- Compare the residuals from the ID results with those from the RRA results. The RRA results can be found in your RRA results folder in the file ending in “Actuation_force.sto” under the quantities for FX, FY, FZ, MX, MY, MZ. For each of the 6 residual measures, quantify how well RRA reduced residuals.
OpenSim is supported by the Mobilize Center , an NIH Biomedical Technology Resource Center (grant P41 EB027060); the Restore Center , an NIH-funded Medical Rehabilitation Research Resource Network Center (grant P2C HD101913); and the Wu Tsai Human Performance Alliance through the Joe and Clara Tsai Foundation. See the People page for a list of the many people who have contributed to the OpenSim project over the years. ©2010-2024 OpenSim. All rights reserved.