The topics covered in this section include:
You can also find more information in the Example - Model Editing.
An OpenSim model represents the neuromuscular and musculoskeletal dynamics of a human or animal that is of interest to study within a computer simulation. The OpenSim model is made up of components corresponding to parts of the physical system that combine to generate or describe movement. These parts are: reference frames, bodies, joints, constraints, forces, contact geometry, markers and controllers.
In OpenSim, a model's skeletal system is represented by rigid bodies interconnected by joints. Joints define how two bodies (e.g., bone segment), termed parent and child bodies, can move with respect to one another. 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 scripts (in the GUI, Matlab or Python), via an XML editor, or you can view and edit the properties using the GUI Property Editor and Outputs List.
While this page describes OpenSim's XML model format, the easiest way to build models is not by editing XML files. See the ModelBuilder.py GUI script described at Scripting in the GUI#AvailableExampleScripts.
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 <gravity> signifies the opening of the tag, 0 -9.8065999999999995 0 is a vector describing the acceleration due to gravity, and </gravity> signifies the end of the tag. The name of the tag identifies the type of information between the tags. When you edit an OpenSim model file, there are tags representing each part of the model, as shown in the figure below.
An OpenSim Model File (arm26.osim). The file below was opened in the XML editor Notepad++, which provides the color syntax highlighting. 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.
Use the OpenSim GUI's XML Browser, under Help to find the XML mark-up for any OpenSim model component described below.
Connecting Components Together using Sockets and Component Paths
It is common for components to depend on each other. For example, Joint components depend on the Body components (actually, PhysicalFrames) that the Joint connects. To specify these dependencies, OpenSim uses the notion of Sockets. As you will see later, a Joint has two Sockets: parent_frame and child_frame. You can specify the frames that satisfy these sockets in XML:
Any XML element whose tag begins with socket_ is used to indicate the path to a component (ComponentPath) in the model that should be used to satisfy the socket. Models in OpenSim version 4.0 and greater are hierarchical: components can contain other components. For example, the BodySet component named 'bodyset' contains the Body component 'r_humerus'. We use forward slashes, similar to a file system path or web URL, to indicate the path to a component in the model's hierarchy. In the example above, we use absolute paths (starting with a slash), but relative paths (e.g., ../../some/other/component) also work.
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> (and similarly named tags for inertia in other directions).
Example XML Code from Model Arm26 to Represent a Body
Every model comes with a Ground body, which exists as a property of a Model, not in the BodySet.
- Same directory as the model
- "Geometry" directory underneath it
- In a directory included in the "Geometry Path" available using Edit >Preferences > Paths: Geometry Search Path
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. In 4.0, this flexibility was enhanced via the introduction of the Frame class hierarchy. There are three main types of Frames: Ground (each model starts with a ground frame), Body, and PhysicalOffsetFrame. All three of these frames are called PhysicalFrames because they either are a rigid body or are fixed to a rigid body. In OpenSim 4.0, a joint connects two PhysicalFrames (parent and child). One can use PhysicalOffsetFrames to specify a constant transform between a joint frame and the body frame.
The figure below shows an example from Arm26 defining the r_shoulder joint. Note the key tags, such as <socket_parent_frame>, <socket_child_frame>, <Coordinate>, <translation>, and <orientation>. Note the use of an intermediate PhysicalOffsetFrame for the joint's parent frame.
Available Joint Types
- WeldJoint: introduces no coordinates (degrees of freedom) and fuses bodies together
- PinJoint: one coordinate about the common Z-axis of parent and child joint frames
- SliderJoint: one coordinate along common X-axis of parent and child joint frames
- BallJoint: three rotational coordinates that are about X, Y, Z of B in P
- 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
- FreeJoint: six coordinates with 3 rotational (like the ball) and 3 translations of B in P
- 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:
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 TransformAxis tags (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:
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.
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.
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.
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).
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 types 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.
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 <socket_parent_frame> and <location>. Additionally, the marker name is important, as it must match the name of the corresponding experimental marker.
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 <socket_frame>, <location>, <orientation>, and <filename>.
Example XML Code from Model tugOfWar to Represent Contact Geometry