The topics covered in this section include:

You can also find more information in the Example - Model Editing.

Use the OpenSim GUI's XML Browser, under Help to find the XML mark-up for any OpenSim model component described below.

Overview

An OpenSim model represents the dynamics of a system of rigid bodies and joints that are acted upon by forces to produce motion. The OpenSim model file is made up of components corresponding to parts of the physical system. These parts are: bodies, joints, forces, markers, constraints, contact geometry, and controllers. 

In OpenSim, the skeletal part of a model is represented by rigid bodies interconnected by joints. Joints define how a body (e.g., bone segment) can move with respect to its parent body. In OpenSim, all bodies have a parent and are connected to its parent via a joint, except for ground. Constraints can also be applied to limit the motion of bodies. 

Muscles are modeled as specialized force elements that act at muscle points (e.g., insertion and origin points) connected to rigid bodies. The force of a muscle is typically dependent on the path through muscle points comprised of muscle fiber and tendon lengths, the rate of change of the fiber lengths, and the level of muscle activation. OpenSim also has a variety of other forces, which represent externally applied forces (e.g. ground reaction forces), passive spring-dampers (e.g., ligaments), and controlled linear and torsional actuators.

The figure below shows a conceptual schematic of an OpenSim model. In the remainder of the chapter, we will discuss the OpenSim model file format used to describe these models.You can edit these properties using an XML editor, or you can view and edit the properties using the GUI Property Editor.

OpenSim Model File Format

An OpenSim model is described by a file that utilizes the XML code structure to organize its contents. XML uses tags to identify and manage information, such as:

where <body> signifies the opening of the tag, r_humerus is the name of a body in the model, and </body> signifies the end of the tag. The name of the tag identifies the type of information between described. When you edit an OpenSim model file, there are tags representing each part of the model, as shown in the figure below. 

To view and edit XML files with colored tags, you can use Notepad++ on PC or EditiX on Mac, both of which are freely available.

An OpenSim Model File (arm26.osim).  The file below was opened in the XML editor Notepad++, which provides the color coding.  The sections have been collapsed to highlight the model components.  Clicking on the + icon to the left of a section would expand it, displaying the relevant tags for that section.

Bodies

In formulating the equations-of-motion (i.e., the system dynamics), OpenSim employs Simbody which is an open-source multibody dynamics solver. In Simbody and OpenSim, the body is the primary building block of the model. Each body in turn owns a joint that connects it to an existing parent body. The joint defines the coordinates and kinematic transforms that govern the motion of that body with respect to its parent body. Within the model all bodies are contained in a BodySet. 

Thus, to start our model, we need to define a set of rigid bodies that represent our system. In the <BodySet> section, we define this group of bodies, with the name, mass properties, and visible objects associated with each body. The figure below shows an example of the r_humerus body in the Arm26 model. Note the key tags, such as <mass>, <mass_center>, and <inertia_xx> (and similarly named tags for inertia in other directions).

Example XML Code from Model Arm26 to Represent a Body

Body Geometry

VisibleObject

The VisibleObject property of a body allows you to specify and position the geometry file(s) associated with a body. In OpenSim there's a distinction between the body/segment and the geometry attached to it. The geometry of a body is used only for visualization purposes. For example, it does not affect the wrapping of muscles or the articulation of joints.

GeometrySet and DisplayGeometry

You can use .vtp, .stl, or .obj files to visualize geometry. Check the units of your model and the units of the exported geometry (e.g. from Solidworks) if you are experiencing size/display issues.
In the model file you can specify not only the geometry, but also the color, texture (from .jpg or .bmp), display preferences, a transform, and scale factors. These properties can be specified for each DisplayGeometry object and/or for the GeometrySet as a whole. See the XML Browser in the GUI for the tags used for the VisibleObject, GeometrySet, and DisplayGeometry properties of a model. An example snippet from the model arm26.osim is shown below.
To have the geometry displayed in the GUI you need to have the Geometry files in one of these locations:
  1. Same directory as the model
  2. "Geometry" directory underneath it.
  3. In a directory included in the "Geometry Path" available using Edit->Preferences->Geometry Path.

Joints

In addition to the set of rigid bodies, we also need to define the relationship between those bodies (i.e., joint definitions).  In the figure below, a joint (in red) defines the kinematic relationship between two frames (B and P) each affixed to a rigid-body (the parent, Po, and the body being added, Bo) parameterized by joint coordinates 

A body is a moving reference frame (Bo) in which its center-of-mass and inertia are defined, and the location of a joint frame (B) fixed to the body can be specified. Similarly, the joint frame (P) in the parent body frame (Po) can also be specified. Flexibility in specifying the joint is achieved by permitting joint frames that are not coincident with the body frame.

As an example, the body r_humerus contains the joint r_shoulder. The figure below shows an example from Arm26 defining the r_shoulder joint. Note the key tags, such as <parent_body>, <location_in_parent>, <orientation_in_parent>, <location>, <orientation>, and <Coordinate>.

Example XML Code from Model Arm26 to Represent a Joint:

Available Joint Types

  1. WeldJoint: introduces no coordinates (degrees of freedom) and fuses bodies together
  2. PinJoint: one coordinate about the common Z-axis of parent and child joint frames
  3. SliderJoint: one coordinate along common X-axis of parent and child joint frames
  4. BallJoint: three rotational coordinates that are about X, Y, Z of B in P
  5. EllipsoidJoint: three rotational coordinates that are about X, Y, Z of B in P with coupled translations such that B traces and ellipsoid centered at P
  6. FreeJoint: six coordinates with 3 rotational (like the ball) and 3 translations of B in P
  7. CustomJoint: user specified 1-6 coordinates and user defined spatial transform to locate B with respect to P

The CustomJoint Transform

Most joints in an OpenSim model are custom joints since this is the most generic joint representation, which can be used to model both conventional (pins, slider, universal, etc…) as well as more complex biomechanical joints. The user must define the transform (rotation and translation) of the child in the parent (B and P, in the joint definition figure above) as a function of the generalized coordinates listed in the Joint’s CoordinateSet. Consider the spatial transform  :

where

q are the joint coordinates, and x are the spatial coordinates for the rotations (x1, x2, x3) and translations (x4, x5, x6) along user-defined axes that specify a spatial transform (X) according to functions fi. The behavior of a CustomJoint is specified by its SpatialTransform. A SpatialTransform is comprised of 6 TransformAxes (3 rotations and 3 translations) that define the spatial position of B in P as a function of coordinates. Each transform axis enables a function of joint coordinates to operate about or along its axis. The function of q is used to determine the displacement for that axis. The order of the spatial transform is fixed with rotations first followed by translations. Subsequently, coupled motion (i.e., describing motion of two degrees of freedom as a function of one coordinate) is easily handled. The example below (from the gait2354.osim model) describes coupled motion of the knee, with both tibial translation and knee flexion described as a function of knee angle: 

Spatial transform of a custom joint that implements a translating knee joint:

Kinematic Constraints in OpenSim

OpenSim currently supports three types of built-in constraints: PointConstraint WeldConstraint and CoordinateCouplerConstraint. A point constraint fixes a point defined with respect to two bodies (i.e., no relative translations). A weld constraint fixes the relative location and orientation of two bodies (i.e., no translations or rotations). A coordinate coupler relates the generalized coordinate of a given joint (the dependent coordinate) to any other coordinates in the model (independent coordinates). The user must supply a function that returns a dependent value based on independent values. The following example implements coordinate coupler constraint for the motion of the patella as a function of the knee ankle and also welds the foot to ground.

Example of constraints in OpenSim:

Forces

In order to actuate our model, we need to define the forces that will be applied to the model. Just like bodies are defined within the <BodySet> section, forces are defined in the <ForceSet> section of the model file. Forces come in two varieties: passive forces like springs, dampers, and contact and active forces like springs, idealized linear or torque actuators, and muscles. Active forces that require input (controls) supplied by the user or by a controller are called Actuators and are a subset of the ForceSet. 

Available Forces

OpenSim has several built-in forces that include: PrescribedForce, SpringGeneralizedForce, BushingForce, as well as HuntCrossleyForce and ElasticFoundationForce to model forces due to contact (Note: contact forces also require defining contact geometry). Below is an example of a bushing force used to model passive structures surrounding a single lumbar joint that connects a torso body to a pelvis body.

Example of a passive BushingForce:

Common Actuators

OpenSim also includes “ideal” actuators which apply pure forces or torques that are directly proportional to the input control (i.e., excitation) via its optimal force (i.e., a gain). Forces and torques are applied between bodies, while generalized forces are applied along the axis of a generalized coordinate (i.e., a joint axis).

Sample of linear and torque actuators in a model’s ForceSet:

 



 

The Muscle Actuator

There are several muscle models in OpenSim. All muscles include a set of muscle points where the muscle is connected to bones (bodies) and provide utilities for calculating muscle-actuator lengths and velocities. Internally muscle models may differ in the number and type of parameters. Muscles typically include muscle activation and contraction dynamics and their own states (for example activation and muscle fiber length). The control values are typically bounded excitations (ranging from 0 to 1) which lead to a change in activation and then force. Below is an example of a muscle model, as described by Thelen (2003), from an OpenSim model. 

In addition to the muscle properties, we need to define its geometry. In this example, a geometry path is defined for the muscle using a set of path points.

Sample muscle actuator from a model’s ForceSet:

Markers

In order to perform Inverse Kinematics, you will need to define a virtual marker set that matches the experimental marker set used to collect motion capture data. Markers are defined in a <MarkerSet>. The figure below (Example XML Marker) shows an example from Arm26 defining a <Marker>. Note tags that define the marker, such as <body> and <location>. Additionally, the marker name is important, as it must match the name of the corresponding experimental marker.

Example XML Code from Model Arm26 to Represent a Marker



Contact Geometry

A model may have some specific contact geometry that is associated with a model. In OpenSim, contact geometry can be an analytical shape, such as a half-place, sphere, or cube, or a user-defined shape represented in a geometry file. Files of type .obj, .stl, and .vtp are supported as of version 3.3. Prior versions of OpenSim support only .obj files. The figure below shows an example defining contact for the ground (half-space) and a user-defined block from the tugOfWar model. Note tags that define the contact object, such as *<body_name>, <location>, <orientation>, and <filename>.

Example XML Code from Model tugOfWar to Represent Contact Geometry