OpenSim

Visual3D, since Version 4.0, allows the user to export OpenSim compatible motion files designed for use with OpenSim gait models.

The Visual3D to OpenSim integration is based on the OpenSim tutorial "Generating a Muscle-Actuated Simulation in OpenSim”. It is assumed that the user is familiar with this tutorial and the files used in this process. For details see: [OpenSim].

Visual3D exports an OpenSim compatible motion file, Visual3D_SIMM_input.mot, which bypasses the Scaling and Inverse Kinematics (IK) in OpenSim and can be used directly by the OpenSim Residual Reduction Algorithm.

Starting with version 4.9.3 Visual3d is now compatible with OpenSim version 2.4.0. The biggest change when exporting to OpenSim 2.4.0 is that OpenSim now looks for the ground reaction force data in a separate .xml or .mot file. Visual3d will now generate this new ground reaction force file on export (called Visual3_SIMM_grf.mot) but there are some consequences of the new OpenSim external force input methodology.

From a user’s point of view the real change occurs when they run the OpenSim RRA and CMC Tools. Now when a user loads the Visual3d_Setup_RRA.xml and Visual3d_SetUp_CMC.xml into the RRA and CMC tools, OpenSim will now look for an External Load file called Visual3d_SIMM_grf.mot. This file will be generated automatically by OpenSim; however Visual3d_SIMM_grf.mot generated by OpenSim does not work with the Visual3d export process. Thus when running both the RRA and CMC the users has to select the “Actuators and External Loads” tab and in the “External Loads Section” and change the “External loads specification file” to Visual3d_SIMM_input_grf.xml. (The file, Visual3d_Simm_input_grf.xml, is supplied with the Visual3 to OpenSIm 2.4.0 distribution.)

In addition to the changes related to the external force export, there are two other revisions with Visual3d 4.9.3 in the exporting to OpenSim. These changes apply to all OpenSim versions:

1) The torso and feet are now automatically scaled to be equal to the average of the left and right femoral lengths. (The new torso and feet manual scale factors are written to the Visual3d_Scale_ScaleSet.xml file.) This modification was made because most users build their feet and head without markers at the very end of the foot and at the top of the head and thus using the average thigh length seems a reasonable scaling approximation for these segments. (Physical anthropometry studies have shown thigh length is a somewhat strongly correlated with height)

2) In the OpenSim Dialog the user is now prompted for the OpenSim version number.

Note: After running RRA in OpenSim version 2.4.0 sometimes the bones will disappear. (This is apparently happens because RRA will occasionally leave the “Working Directory”.) To fix the problem go to the OpenSim Edit->Preference pull-down menu and change the Geometry path to the folder where OpenSim installed the “Geometry” folder. In OpenSim 2.4 this is often C:/OpenSim2.4.0/Geometry.

Download Files

Visual3D to OpenSim Demo OpenSim related files that are used in these examples for download. Visual3DtoOpenSim for OpenSim 1.9.1 and earlier Visual3DtoOpenSim for OpenSim 2.0 to 2.2 Visual3DtoOpenSim for OpenSim 2.4.0 Visual3DtoOpenSim for OpenSim 3.2.0 Visual3DtoOpenSim for OpenSim 4.0.0

Visual3D to OpenSim Inverse Kinematics

Visual3D’s ability to write OpenSim compatible .mot files is based on Visual3D’s own Inverse Kinetics algorithm. The theory behind the Visual3d to OpenSim Inverse Kinematics is a three stage process:

1. Visual3D computes the scale factors which will scale the OpenSim gait model to the Visual3d static calibration model. These scale factors get written to a special OpenSim scale set file named Visual3d_Scale_ScaleSet.xml. (See the Visual3d Scaling section of this document for more details.)
2. Visual3D uses Inverse Kinematics to fit the scaled OpenSim gait model to the Visual3D Static Calibration Model. (This is similar to the OpenSim Marker Placer Process).
3. Visual3D then uses Inverse Kinematics to fit the gait data to the newly calibrated model.

Comparing Visual3D and SIMM exporting to OpenSim

The capability of Visual3d and SIMM are somewhat different. You can think of the process of generating muscle driving simulations in OpenSim as occurring in three steps:

1. Build a Musculoskeletal Model
2. Import the Model along with Motion Capture and Force Plate Data to OpenSim
3. Analyze/Simulate the data in OpenSim

Currently SIMM works at Step 1 while Visual3d works at Step 2.

If you are using a standard OpenSim model to analyze walking or running then you really do not need SIMM since OpenSim comes with two default full body models. (One includes 54 lower extremity muscles and the other includes 92.) In theory you could also bypass SIMM by creating models directly with an xml file but this is really tough to do. Thus if you trying to look at non-standard or non-gait models then SIMM can very helpful. If you are looking at walking and running then SIMM may not be needed.

As mentioned Visual3d comes in at step 2. Visual3D is not required for step 2 especially if you are using the default Open marker set; however if you deviate for the expected marker set then importing the motion capture and force plate data can be a very cumbersome process in OpenSim. In addition Visual3d will also allow you to do many, many more standard kinematic and kinetic analyses on the Motion Capture data then are available in OpenSim.

In short Visual3d will quickly export walking and running data into OpenSim while simultaneously providing you with a large number of kinematic, kinetic and data analysis tools.

Modeling Requirements

The Following model requirements must all be met. Please read the requirements carefully:

1. The Visual3d model used for OpenSim output must include the right foot (RFT), right shank (RSK), right thigh (RTH), left foot (LFT), left shank (RSK), left thigh (RTH), pelvis (RPV) and a Thorax/Ab (RTA).
2. The Thorax/Ab (RTA) segment must be built in a very specific way. First, the proximal end of the RTA should be the created at the exact same location as the proximal end of the pelvis. Thus the proximal end of the RTA forms the joint with the pelvis while the distal end of the RTA should be built at approximately at the height of the shoulder shoulders. If constructed in this manner, the RTA segment will now have the Z axis (which goes distal to proximal) pointed downward and the Y axis pointed backward. This must be changed so the RTA segment coordinate system matches the local coordinate system of the other segments. To do this you go click the "Modify the Segment Coordinate System" button in the "Segment Properties" tab. Then set the "AP Axis" to –Y and the "Distal to Proximal" to be –Z. Building the trunk in the exact manner described above will create a trunk whose origin is at the proximal end of the pelvis, its Z axis is vertical and its Y axis is Anterior. This coordinate system is needed to assure the trunk is properly oriented when you load the.mot file to OpenSim.
3. All segments must follow the default Visual3D convention, X ML, +Y anterior and +Z vertical. This is necessary to enforce the OpenSim model constraints (explained below).
4. One current limitation of the Visual3d to OpenSim approach is that in order to handle the motion of the pelvis relative to the LAB all subjects are assumed to be walking in the +Y direction, with the global +Z axis in vertical direction and the +X axis pointing to the right. If the user’s LAB coordinate system is not setup this way they can get around this limitation by creating "virtual lab segment with this orientation. The virtual lab must be named v3d_lab.

See Virtual_Lab_For_OpenSim for an example of how to create of Visual3D v3d_lab.

Pose Estimation in Visual3D

It should be noted that a 6-degree of freedom joint in Visual3D gets transformed into OpenSim's gait model constraints.

Visual3d offers two methods of POSE Estimation: 1) 6 degree of freedeom which you mention (based on Spoor and Veldpaus, 1980) and 2) Inverse Kinematics (based on Lu and O'Connor, 1999).

When exporting to OpenSim, Visual3d applies the Inverse Kinematics method fit to the model using the constraints specified in the OpenSim gait23*.osim file.

The constrains used are:

1. 3 degree of freedom ball joint at the right hip, left hip and waist.
2. a hinge joint at the knee with the location of the hinge a function of the knee joint angle as specifies in the OpenSim model.
3. The ankle joint is hinge with the direction of the axis matching that of the gatt23*.osim model.
4. The subtalar joint is hinge with the direction of the axis matching that of the gatt23*.osim model.
5. The mtp joint is fixed and set to zero at all frames. (This was done on a recommendation from Jill Higginnson at the University of Delaware.)

So when you export to OpenSim it is not using a 6 dof model; instead it uses an IK model with constraints matching the Opensim model constraints.

It is all hardcoded inside Visual3d so the user never sees the constraints.

Correcting the Lumbar Tilt in the Exported Motion File

In the Visual3d export dialog, Visual3d allows the user to specify a correction angle for the lumbar flexion/extension angle exported to OpenSim. (The edit box is labeled "Lumbar Tilt" in the export dialog.) Generally the lumbar flexion/extension correction is needed only if the user has trouble getting the trunk Z axis lined up properly during subject calibration. (It is often hard to accurately locate the proximal end of the trunk, down by the pelvis, thus the trunk often leans too far forward or backward in Visual3d.) One way to compute an appropriate lumbar adjustment is to build your model in Visual3d and then load a copy of the subject calibration c3d file into Visual3d as movement trial. You can then ask Visual3d to compute the JOINT_ANGLE of the trunk relative to the ground during subject calibration. If you believe you subject was standing straight during calibration then multiply this angle by -1 and use that value as your "Lumbar Tilt".

Visual3D and the OpenSim xml Files

As mentioned previously, the Visual3d to OpenSim process is designed to work with the OpenSim in the manor outlined in the OpenSim tutorial "Generating a Muscle-Actuated Simulation in OpenSim". To work successfully the process required that special versions of several OpenSim xml input be created. Below is the list of new OpenSim xml files and how they were created by modifying the original files:

Visual3D_Setup_Scale.xml

Visual3D_Setup_RRA.xml

Visual3D_Setup_CMC.xml

Visual3D_Scale_ScaleSet

Files No longer Required

Visual3d does manual scaling on all segments and does its own IK, thus many of the OpenSim files related to the Marker Set, Scaling and IK are no longer required.

Visual3D Scaling

Visual3D automatically scales the OpenSim model by:

1. Changing the OpenSim scaling method to manual scaling for all segments. (The simplified version of the OpenSim scaling setup file, called Visual3d_Setup_Scale.xml , should be used to scale the model in OpenSim.)
2. Updating the file Visual3d_Scale_ScaleSet.xml to include the Visual3d computed scale factors for the pelvis, left and right thigh and left and right tibia segments.

In OpenSim 3.1, the xml formats were modified and Visual3D could not write the correct manual scale factors to be used by OpenSim. For OpenSim 3.1, the user will need to manually enter the scale factors in OpenSim. The OpenSim_Scale_Factors.v3s pipeline can be used to calculate the scale factors in Visual3D and export the scale factors to a text file for the user. This is only specific to OpenSim 3.1, the setup scale factors works in all all other OpenSim versions before/after 3.1.

Important Note: The manual scale factors written to the Visual3d_Scale_ScaleSet.xml file must be used to scale the pelvis, thigh and tibia segments in OpenSim. If these scale factors are not used then center of pressure, which is also written by Visual3d to the Visual3d_SIMM_input.mot, will not be adjusted properly in relation to the model. (The scale factors for the feet and torso do not affect the relationship between the center of pressure and the model and thus are these scale factors are left for the user to supply.)

The manual scale factors computed by Visaul3d are based on the subject calibration data and the OpenSim segment geometry (as specified in the gait2392_simbody.osim). Specifically, the segments are scaled by:

Pelvis

To scale the pelvis Visual3d computes the distance (in meters) between the hip centers in the subject calibration and divides this value by 0.167. The value 0.167 is the distance between the medial and lateral hip location in the file gait2392_simbody.osim. (One important note is that by default OpenSim scales the pelvis based on the distance between the left and right ASIS; however since Visual3d does not require targets be placed on the left and right ASIS the pelvis is scaled based on the distance between the hip joint centers which will always be present.)

Thigh

To scale the thigh Visual3d computes the distance between the hip and knee joint center in the subject calibration and divides this value by 0.396. The value 0.396 is the distance between the hip and knee location in the file gait2392_simbody.osim.

(Note: the knee location will vary with knee joint angle in OpenSim and the value 0.396 represents the knee location at zero degree of knee flexion.)

Shank

To scale the thigh Visual3d computes the distance between the knee and ankle joint center in the subject calibration and divides this value by 0.43. The value 0.43 is the distance between the knee and ankle location in the file gait2392_simbody.osim.

Torso, Calcaneus and Toes

Because most users build their feet without markers at the very end of the foot and at the top of the head and thus using the average thigh length is used to scale these segments. (Physical anthropometry studies have shown thigh length is a somewhat strongly correlated with height)

Ankle_Angles

OpenSim versus Visual3D ankle angles

Angles exported to OpenSim

The angles that are exported to OpenSim are slightly different than the angles calculated in Visual3D.

The Inverse Kinematics model used in the Visual3d OpenSim export is a special version of the Visual3d IK designed so the model exactly matches the gait2354 or gait2392 osim models.

The four main differences in this special Visual3d implementation of the IK are:

1. The ankle plantar flexion angle in the OpenSim export corresponds to zero degree when the foot is flat on the floor and the tibia is vertical (most Visual3d models are built with the foot z axis running from the toes to the ankle center)
2. that the knee joint will translate in the thigh X-Y plane as a function of the knee joint angle in the same manner as the OpenSim model
3. the Hip joint center is the located at the values set in the gait2354 or gait2392 osim models
4. the axes of rotation at the ankle and subtalar joints are skewed. (The direction cosines of right plantar flexion axis = 0.9793, -0.1045, -0.1736. The direction cosines of right subtalar axis = -0.1209, 0.7872, 0.6047).

If you look at the osim file you will see that the knee motion, the hip center location and the ankle/subtalar angles are defined and the Visual3d OpenSim IK export model matches these osim files. Thus using a traditional Visual3d IK you will not get exactly the same angles as you get from an OpenSim export. (In Visual3d Pro IK you can skew the ankle and subtalar axes to match OpenSim axes using the "Direction of Rots" button and you probably can even create a hip center in the correct location but there is no way to specify the knee translation as function of knee angle - this is hard coded inside Visual3d for the OpenSim export. Thus no matter how hard you try you can never get an exact match between a standard Visual3d and an OpenSim export IK.)

Exported Force and Free Moment

Visual3D exports the FORCE and FREEMOMENT signals that are found in the data tree.

Exported Center of Pressure

After the Inverse Kinematics (IK) fit the entire model could move relative to the center of pressure thus leaving the IK fit with a significant effect on the moments at the ankle, knee and hip. To counteract this Visual3d first computes and stores the local coordinates of the center of pressure in the foot coordinate system (pre-IK) whenever a foot is in contact with the plate. Then after the IK fit is complete Visual3d retrieves the pre-IK coordinates of the COP and transforms them from the post-IK foot coordinate system into lab space. Thus if the vertical component of the COP in the output .mot file you will not lie flat along the floor (or treadmill); however if look at the distance from the center of pressure to the ankle in OpenSim it should look OK. (Remember the model itself can move up and down in OpenSim, so the location of the COP under the foot is what matters not the COP coordinates in lab space.)

OpenSIm Joint Moments and Joint Load

You can get the Inverse Dynamics directly out of OpenSim using the "Inverse Dynamics.." tool which is located under the Tools menu. Once you Open the Invers Dynamics tool in OpenSim load the attached xml file and run tool. The output will go to the ResultsInverseDynamics subfolder.

The one thing you do need to do before running the Inverse Dynamics tool is modify the initial and final time in the attached xml so that they are a little shorter the time found .mot file you have loaded. (As a reminder, before running the Inverse Dynamics tool you need to load the osim model, scale the model and load the .mot file exported by Visual3d.)

Exporting Other Models

Visual3D's default export to OpenSim only supports the OpenSim "gait_2392.osim" and "gait_2354.osim" models. This means in Visual3D you must have all the segments required for these models.

It is possible to define your own custom OpenSim model in Visual3D, and export the MOT files by going to "File -> Export OpenSim From Data Tree". However, this process requires an experienced Visual3D and OpenSim user who knows how to create a Visual3D IK that matches the degrees of freedom in their OpenSim model. The user must also be able to read their osim file to determine the names of the data that need to be copied into the Visual3d OPEN_SIM, OPEN_SIM_GRF and Metric::Open_Sim_Scale folders.

An example of this can be found here.

OpenSim 4.0

In previous versions of OpenSim, opening (File -> Load Motion) the Visual3d_SIMM_input.mot file loaded the states and ground reaction data were applied. As of OpenSim 4.0, you need to load the Visual3d_SIMM_input.mot file, then associate the Visual3d_SIMM_grf.mot file using these steps.