NMSBuilder

Tutorial
Create an OpenSim model from Test Data

Giordano Valente, Lorenzo Pitto, Stefano Perticoni

Laboratorio di Tecnologia Medica, Istituto Ortopedico Rizzoli, Bologna
BioComputing Competence Centre, SCS srl, Bologna

1. Objectives
NMSBuilder is an open-source software package, being developed within the NMSPhysiome
project. It allows to import and edit subject-specific data from different sources, develop OpenSim
musculoskeletal models, leverage OpenSim to perform dynamic simulations of movement and
store the results. Next release features will also include statistical post-processing and
visualization tools, as well as import/export facilities of Matlab file formats. The software
integrates the multimodal data fusion functionalities of Multimod Application Framework with the
OpenSim API.
The purpose of this tutorial is to help users getting started with the software, creating a simple
OpenSim musculoskeletal model from subject-specific data distributed with the alpha version
released. Only specific tools to the purpose will be described in this tutorial. For all other software
capabilities and potential, users are referred to the user's guide.

Figure 1 - Main parts of a musculoskeletal model in OpenSim. All necessary features are definable within
NMSBuilder operations

2. Test Data
First of all, download the test data from here:
https://www.biomedtown.org/nmsphysiome/reception/alpha/
Test data include models of the right thigh and shank of a specific normal subject, derived from
MRI images. File Open Test Data.msf to import the data. To visualize and navigate the data
elements, select View Add View Surface and go into the Data Tree panel.
Data are organized in a hierarchical tree and divided into rigid bodies (parent), joints, marker sets
and attachment points (children), plus Muscle Actuator and OpenSim model source code:

Figure 2 - Test data visualized in a surface view. Each object is stored in the hierarchical tree in the data tree bar

Closed surfaces of hard and soft tissues:

Each part has an assigned density, and the inertial properties have been calculated. It is
possible to visualize and edit the properties from VME metadata facilities (Operations
Modify VME Metadata). Note that multi-surface groups R_Thigh and R_Shank account
for the properties of both hard and soft tissues.

Knee Reference Systems in Parent and in Child:

The two RefSys have been conveniently defined.

Marker Sets:
Identified with a virtual palpation procedure on anatomical landmarks [1].

Attachment Points:
Registered from Delp model [2] onto the specific anatomy.

Actuator path and parameters:

 Vastus lateralis muscle, including the origin/via/insertion points and maximum isometric
force parameter. Other muscle parameters can be defined from VME metadata facilities
(Operations Modify VME Metadata, also refer to user's guide).

Source code of the OpenSim model created:

Additional files, distributed in the Geometries and output model folder, include the vtp geometry
files and the osim model file, created as result of this tutorial.

3. Create OpenSim model

The purpose is to create, from subject-specific surfaces segmented from MRI images, a multibody-
dynamics model of two rigid bodies (thigh and shank), connected by a 1 DOF pin joint, moved by
one muscle actuator, and with a 6 DOF free joint connecting the thigh to the ground.
First, the user must define the necessary features to build the model (Figure 1 and following 3
paragraphs in this section): inertial properties of bodies, joint reference frames, muscle actuator
paths and parameters. Then it is possible to build the OpenSim model: 1) from Wizard or 2)
creating cpp command blocks for each model part, to be pasted (and modified if necessary) into
the source code template (advanced users).
Definition of bodies
Each rigid body is made of multi-surfaces defining hard and soft tissues. Beyond the geometry, the
inertial properties need to be calculated. First, the density of each sub-part composing the body
can be assigned from VME metadata facilities (Operations Modify VME Metadata), defining
the tag 'DENSITY' and typing the numerical value. If density is not defined, a default unitary value
is assumed. Then, the inertial properties can be calculated with the appropriate operation
(Operations Measure Compute Inertial Tensor) on each multi-surface body. This will return
the mass, center of mass, inertial matrix in the local reference frame and principal moments of
inertia, that will be automatically stored as VME attributes in the VME Metadata properties.

Figure 3 - VME Metadata parameters of R_Thigh multi-surface after performing the compute Inertial Tensor
operation
3

Definition of joints
Two joint reference frames (RefSys) define position and orientation of the joint in each of the two
connected bodies. The origin of the RefSys will be the center/axis of rotation of the joint, and the
degree of freedom will take place along its axes (Pin Joint rotates along the blue Z-axis).
The two RefSys have to be created from anatomical landmarks defined. This can be done in two
ways:
1. Select a landmark cloud (Marker Set) representing the anatomical landmarks of the bone
corresponding to the desired body, then Operation Create Derive AFRefsys and
then select the acronym corresponding to the bone. This will create a RefSys child of the
landmark cloud. Select it, go to the vme tab and assign the requested landmarks.
2. Operation Create RefSys. Select it, go to the vme tab, check Select Plane. The first
landmark to feed will be the origin, the second one will define the X axis and the third will
define the plane and direction of the Y axis.
The RefSys can be moved (rotated and translated) using the Move facilities (refer to user's guide):
select it, Operation Create Derive Freeze VME. This will create an object that can be
moved as any other VME object.
In the Test Data, the knee joint is modelled as a pin joint with the axis of rotation passing through
the RME and RLE markers. The RefSys in Parent is defined using RME and RLE as origin and point1,
and then rotating the RefSys to make this axis the Z-axis. From this, RefSys in Child is defined such
to have the knee neutral pose according to ISB standard [3].

Definition of muscle actuators
An action line representing the muscle needs to be created: select Operation Create Derive
Wrapped Action Line, go to vme tag, select Pivot-set method and set wrap to manual, feed the
start and end points and a list of ordered midpoints. Physiological muscle parameters can be
assigned through VME Metadata facilities (Operation Modify VME Metadata): the maximum
isometric force parameter can be assigned adding a "maxIsometricForce" numeric tag and typing
the value. To see other valid muscle parameter tags, please refer to the user's guide. If muscle
parameters are not defined, default values will be assumed.

Create OpenSim model from Wizard
Once all necessary model objects have been defined (body properties, RefSys, muscle action lines),
the user is ready to create the OpenSim model. The more user-friendly way is to use the Wizard
facility: Operations Create New OpenSim model from Wizard will guide users through a
step-by-step procedure in selecting all the necessary model objects and create the OpenSim
model source code to be compiled later.
1. Create Bodies from Surfaces
Select Add Groups to define multi-surface bodies and pick "R_Thigh" and "R_Shank" groups.
Bodies will be automatically added to the model. In addition, this operation creates and saves
all geometry vtp files in the default model directory.

Figure 4 - First step of creating OpenSim model from Wizard: create bodies from multi-surfaces

2. Create Joints
To define the free joint with the ground, select the Child Body,
pick "R_Thigh" and Add Joint. To define the hinge joint at the knee,
select Pin Joint from the drop-down menu and pick the necessary
bodies and reference frames corresponding to Parent Body,
RefSys in Parent, Child Body, RefSys in Child, and then Add Joint.
3. Create Marker Sets
To attribute the two defined marker sets to the corresponding
bodies, select Source Landmark Cloud and pick the corresponding
Marker Set, to then select Target Body and pick the corresponding
body. Select Add Marker Set each time to add the markers to the
model.
4. Add Muscles
Select Add Muscle and simply pick the wrapped action line
corresponding to the "R_vas_lat" muscle.
Selecting continue in the last step of the procedure (Wizard Done!)
will automatically add the model source code to the data tree, and an Figure 5 - Create Pin Joint
from Create OpenSim
automatic pop-up window will show the created cpp file in a
modelfrom Wizard
Notepad++ text editor.
Now this file needs to be compiled to create the corresponding .osim model. Select the
OpenSimModel from the data tree and go to Operations Modify OpenSim Model Editing
Tools: selecting Generate Model, the source code will be compiled and the model file will
automatically show up in the text editor. The "outputmodel.osim" will be saved in the default
directory, editable from the Editing Tool panel.
The created .osim model can now be imported in OpenSim.

Alternative: Create OpenSim model

As alternative to creating the model from Wizard, a possibility for
advanced users is to create the model by generating all cpp command
blocks separately. This allows to edit any model parameter working
directly on source codes.

Figure 6 - Editing Tools

for the OpenSim model
source code

To create the same model described, first go to Operations Create

New OpenSim model: this will create and add to the data tree a
template model source code, which corresponds to an empty OpenSim
model. After selecting this model from the data tree, go to Operations
Modify OpenSim model, where users can find all the necessary
operations, previously described, to create the different model parts.
Each operation allows to create a corresponding cpp command block
that need to be pasted into the template model file. When all operations
will be concluded, users can save and compile the final model source
code file.

References
[1] Taddei et al., 2007. Virtual palpation of skeletal landmarks with multimodal display interfaces.
Medical informatics and the Internet in medicine, 32(3): 191-8
[2] Delp et al., 1990. An interactive graphics-based model of the lower extremity to study
orthopaedic surgical procedures. IEEE transactions on bio-medical engineering, 37(8): 757-67
[3] Wu et al., 2002. ISB recommendation on definitions of joint coordinate system of various joints
for the reporting of human joint motion--part I: ankle, hip, and spine. International Society of
Biomechanics. J Biomech, 35(4):543-8