Understanding the OpenSim Pipeline

Presented by Adam Galloy¹, Kayt Frisch PhD¹, and Dylan Schmitz²

¹Dordt College, ²University of Wisconsin-Madison

Contact: kayt.frisch@dordt.edu

Introduction

Below is an example of an OpenSim pipeline where the goal of the pipeline is to simulate the generalized forces and torques generated by subjects using Inverse Dynamics. The pipeline is kept as general as possible and can be used to answer many different research questions. One example where the pipeline might be useful is in a comparative study of the dynamics of a motion when the subject and/or motion are manipulated somehow (what kind of differences are present in the arm torques generated by high school volleyball players compared to collegiate volleyball players for example).

Yellow circles represent file inputs and outputs, grey boxes represent user actions

However, as general as the pipeline's uses are it only scratches the surface of what OpenSim is capable of. For example, this pipeline cannot be used to find out the force contributions from individual muscles like other potential OpenSim pipelines. Despite the pipelines limitations it provides an example of what an OpenSim pipeline looks like and how to plan one. The rest of this page will point out some of the important features of the pipeline, and the pages following this one will provide more detail on the starting steps of preparing a model and data.

Simulations Build on Each Other

In the above pipeline, more than one simulation is required to reach the final goal of finding the generalized forces and torques generated by a subject. Before Inverse Dynamics can be run to output the desired information, Inverse Kinematics is needed to find the subjects’ joint kinematics, and Inverse Kinematics cannot be run before the Scale Tool is used to simulate the geometry of the subjects. Most OpenSim pipelines will require more than one simulation just like this pipeline. When planning a pipeline for an OpenSim simulation, intermediate steps such as these must be considered ahead of time. If you do not consider intermediate simulations necessary for your pipeline ahead of time, you may find out after spending hours collecting data that you did not collect all of the data that you actually need.

 One approach to finding all of the intermediate steps in an OpenSim pipeline is to start with the simulation that will output your goal (in our example Inverse Dynamcs) and asking yourself, “What are the inputs required for this simulation?” Look at the “Getting Started with [desired tool]” page in the OpenSim documentation to find all of the necessary inputs. Often those inputs will not be directly measurable in the lab and they must be obtained as outputs of another simulation. Continue tracing the inputs back until you reach a point where those inputs can be measured directly in the lab or found from existing data (in our example these inputs would be the musculoskeletal model, the marker data, and the external force data).

.xml Settings Files

The number of simulations that need to be run for a project can grow very quickly, especially when large numbers of subjects and motion trials are involved in the study. This large amount of work creates two problems: simulations must be kept as consistent as possible between each run, and the amount of time setting up a simulation must be reduced as much as possible. .xml Settings help with both of these problems by allowing users to save the settings used in each simulation. Each simulation tool has its own settings file(s) that should be set up for consistency and convenience. Some of the simpler tools such as Inverse Kinematics may be quick to set up without a settings file, but keeping track of the settings that were used during the simulation for future reference and consistency is good practice. The OpenSim documentation provides detailed information on what information is in each settings file and what settings files are required for a simulation.

External Loads Specifications Files

External loads specification files are inputs for many different simulation types (Inverse Dynamics, Static Optimization, Forward Dynamics, and more). The goal of these files is to correctly apply any forces measured or estimated to the model during a simulation.

The first editing screen for an external loads specification file is shown below. In this screen the file containing the force data must be selected. Once a file is selected a force must be created for each external force acting on the subject with the Add… button. In the example below, the subject is jumping on one leg and the only external force that needs to be modeled is the ground reaction force on the right leg. In addition, the kinematics that coincide with the load may also be selected. However, many tools already require specifying kinematics in their own settings files, so the kinematics are often left unspecified in the external loads specification file.

Once a force is added the window below appears. In this window the details of how the force is applied are specified. Two types of forces are available in this window: Point Forces and Body Forces. Point Forces are applied to a body at a specific point specified by the data file. Point Forces require the specification of force, torque, and point of application columns from the data file. On the other hand, Body Forces apply forces and torques at the body’s center of mass that are equivalent to the actual moving point of application force. Only force and torque columns need to be specified, but make sure that the torque columns of the file compensate for the actual point of application correctly. Also note that torque columns must be specified for both Point and Body forces even if the columns just contain zeros.

Scaling and the OpenSim Pipeline

One simulation that appears in the pipeline that has not been mentioned much up to this point is the Scale Tool. Unlike simulations such as Inverse Kinematics and Inverse Dynamics, the Scale Tools outputs are not very useful for answering research questions by themselves. However, scaling is one of the most important parts of many OpenSim pipelines since the results of future simulations heavily depend on it.

Scaling changes the musculoskeletal geometry and inertial parameters of an OpenSim model to match a specific subject. The inputs of the Scale Tool include a settings file, a generic OpenSim model to be scaled to the subject, and marker data for comparing the generic model’s markers to the subject’s markers. Simulations such as Inverse Kinematics and Inverse Dynamics heavily rely on accurate musculoskeletal geometry and inertial parameters, so scaling is necessary for these tools to provide valid results. Take a look at the material in the Getting Started with Scaling and How Scaling Works pages of the OpenSim documentation for more detailed information on how the scaling process works and what is required.

Scaling will often be among the first simulations run in a pipeline and will often need to be run multiple times for each subject. Because of disagreements that inevitably appear between the marker placements on the model and on the human subject, markers may need to be moved on the model after reviewing the results of a scaling attempt. This process may take several hours, so have patience.

 Here are a few tips that can improve your scaling results:

• Take pictures of the subjects to help you remember how exactly how you placed the markers on the subjects.
• If you record the subjects’ heights and take pictures, you can use image editing software such as ImageJ to measure the lengths of body segments which can help verify your scaling.
• Digital model markers can be used to “measure distances” on the model; for example, if you want to know the height of a body segment attach a marker to the bottom of the segment and another to the top of the segment. By looking at the coordinates of the model markers you can find distances in the model that can help with setting up scale parameters.
• Marker errors should not be the only way you evaluate scaling! Marker errors are useful for evaluating scaling results but can be misleading. Take a careful look at the joint angles of the static pose produced after scaling. If a segment is at an angle that seems suspect the scaling may still need improvement. Models with many degrees of freedom can often “force themselves” into a pose that minimizes marker error but that might not match the subject’s actual pose. Use any information you have and maybe make a few educated assumptions about what pose the model should have to improve results.
• If you find a particular degree of freedom in the model is too sensitive to marker locations to position accurately during scaling, then you should reconsider using that degree of freedom in your simulations.