A framework to simulate Joint and Articular Mechanics in OpenSim.
Author: Colin Smith
OpenSim JAM is a collection of force component plugins, models, and executables (tools) designed to enable OpenSim musculoskeletal simulations that include 6 degree of freedom joint mechanics with explicit representations of articular contact and ligament structures. A series of examples are available to demonstrate how to use these fools to perform forward simulations of joint mechanics, and simulate walking using the Concurrent Optimization of Muscle Activations and Kinematics (COMAK) algorithm. The new OpenSim Components, models, and simulation tools are described below:
This one dimensional path geometry acts as a spring-damper to represent ligament fibers. The force strain relationship includes a nonlinear toe region at low strains and a linear region at high strains to represent the uncrimping and stretching of collagen fibers within a ligament.
Source
Description
This force component represents articular contact between cartilage, mensici, or artifical components using triangular mesh representations of the surface geometries and an elastic foundation model to compute local contact pressures.
Source
- Smith2018ArticularContactForce.h
- Smith2018ArticularContactForce.cpp
- Smith2018ContactMesh.h
- Smith2018ContactMesh.cpp
Description
The Lenhart2015 model is an OpenSim implementation of the model described in the paper below. A multibody knee model was constructed based on magnetic resonance images from a healthy young adult female. The bones, ligaments, and cartilage were segmented from different image sets that were optimized for the discerning the relavent structures and registered together. The lenhart2015 model includes the tibiofemoral and patellofemoral joints as 6 DOF joints. Tibiofemoral and patellofemoral articular contact are represented using Smith2018SmithArticularContactForce components and damping within the joint is represented using SpringGeneralizedForce components acting on each knee coodinate. Knee ligaments and passive structures are represented using bundles of Blankevoort1991Ligaments. See the publication for further details of model construction:
The ForsimTool enables forward dynamic simulations of joint mechanics to be performed. Practically, this allows simulations of cadaver experiments, passive clinical examinations, and simulations where the muscle forces or excitations are known inputs. Fundamentally, it is similar to the ForwardTool in the OpenSim GUI, but the interface is designed for performing forward simulations involving articular contact. The input files can define the muscle and actuator controls (excitations), activations, or forces vs time, external loads applied to the model, and the coordinate values vs time for prescribed coordinates. The forsim tool uses an implicit integrator (SimTK::CPODES::BDF), which gives far superior performance for simulations that involve contact compared to the explicit integrators used by the existing OpenSim ForwardTool.
Source
Description
- ForsimTool Description coming soon
The Concurrent Optimization of Muscle Activations and Kinematics (COMAK) algorithm enables the calculation of muscle forces and detailed joint mechanics during dynamic movements. For details of the COMAK algorithm refer to the following publications:
Smith, C. R., Brandon, S. C., & Thelen, D. G. (2019). Can altered neuromuscular coordination restore soft tissue loading patterns in anterior cruciate ligament and menisci deficient knees during walking?. Journal of biomechanics, 82, 124-133.
Brandon, S. C., Smith, C. R., & Thelen, D. G. (2018). Simulation of soft tissue loading from observed movement dynamics. Handbook of Human Motion, 395-428.
Smith, C. R., Lenhart, R. L., Kaiser, J., Vignos, M. F., & Thelen, D. G. (2016). Influence of ligament properties on tibiofemoral mechanics in walking. The journal of knee surgery, 29(02), 099-106.
Source
Description
- COMAKInverseKinematicsTool Description coming soon
- COMAKTool Description coming soon
The JointMechanicsTool enables detailed post-hoc analysis of simulations or measurements of joint mechanics. It can be used to generate .vtp files to visualize simulation results in Paraview, or .h5 files which are binary files that can store the large quantites of contact data (multiple calculated values for each triange face) in compact files that can be quickly read by MATLAB, Python, or HDF View
Source
Description
- JointMechanicsTool Description coming soon
The C++ source code and CMake files are available so you can build all of the OpenSim-JAM libraries and executables for windows, linux, and mac operating system. Additionally, compiled versions of OpenSim-JAM are provided for windows and Centos6 (redhat linux) users. The descriptions below are focused on the windows release.
An OpenSim Plugin containing the OpenSim-JAM Components and Tools has been compiled for Windows and OpenSim 4.1 using Visual Studio 15 2017 Win64. The plugin file is located at ./bin/win/jam_plugin.dll.
The plugin can be used with the OpenSim 4.1 GUI, MATLAB/Python, and commmand line interfaces (instructions).
Each of the Simulation Tools have been compiled as command line executables (.exe) for windows. This allows users to define simulation settings in a .xml file and organize and perform simulations using windows .cmd files. The compiled executable files are located here and the C++ source files for each tool is located at cmd_tools
Each executable can be called in the windows command line using the following syntax:
exectuable-name .\path\to\jam_plugin.dll .\path\to\settings_file.xmlThe execuatables are dependent on the OpenSim 4.1 libraries. A copy of the necessary OpenSim .dll libraries are included in this repository here.
Relative paths in the .xml settings files should be referenced to the location of the .xml file.
A series of examples are provided to demonstrate the capabilities of OpenSim JAM.
The examples use the OpenSim 4.1 - MATLAB scripting interface to generate the necessary input files and process the simulation results. The windows commmand line executables are used to perform the simulations. Thus, currently only windows can be used to run the examples.
Perform a forward simulation of passive knee flexion where tibiofemoral flexion is prescribed and the other knee coordinates are unlocked (unconstrained) and thus are calculated based on the passive muscle, ligament, and articular contact forces.
Replicate a clinical test for anterior cruciate ligament (ACL) deficiency by performing a forward simulation where the hip is flexed to 25o, the knee is flexed to 25o and an anterior force is applied to the tibia.
Replicate a clinical isometric extension test where the hip and knee are held at 30o flexion and the patient activates their quadriceps.
Use COMAK to predict muscle forces, ligament forces, cartilage contact pressures, and secondary knee kinematics during walking.
The OpenSim GUI is helpful for visualizing models and simulation results. Instructions for visualizing models and simulation results are provided here
MATLAB is used in the examples to generate input files and process simulation results. You will need to have the OpenSim 4.1 - MATLAB scripting interface setup in order to generate the example input files. Python is an open-source alternative that can also be used for this purpose, but you will need to translate the MATLAB scripts.
A text editor that is capable of syntax highlighting and code folding is nice for viewing the .osim model files, as well as the .cmd scripts and .xml settings files in the examples. Visual Studio Code is my personal choice at the moment, but many OpenSim users also like Notepad++.
Paraview is used to for high quality rendering of simulation results including visualization of contact maps. The JointMechanicsTool provides the ability to generate .vtp files that can be directly read into Paraview.
Instructions for visualizing simulation results are provided here
HDFviewer is a standalone gui to explore .h5 file contents.
The following softwares can be helpful for constructing and editing the triangular mesh representations of the articular surfaces (.stl, .vtp, or .obj) files used in the Smith2018ContactMesh component.
Software for mesh visualization, refinement, cutting, smoothing etc.
Software for mesh visualization, smoothing etc.
MATLAB based software toolkit that includes mesh editing features.
Much of the included models and codes were initially developed in the UW Neuromuscular Biomechanics Lab at the University of Wisconsin-Madison. Contributers to this work include Darryl Thelen, Rachel Lenhart, Jarred Kaiser, Michael Vignos, Kwang won Choi, Scott Brandon, and Josh Roth. Translation and extension of the orginal SIMM and UWPipeline into OpenSim was performed during my time as a PhD at UW-Madison (NIH EB015410) and Stanford (NCSRR Visiting Scholar), and as a Post-doc at the Laboratory for Movement Biomechanics at ETH Zürich (Whitaker International Program, OpenSim Pilot Project Pilot Project Award No. 5P2CHD065690-09).
A list of publications that use these tools is located here