HAS-Motion Software Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== OpenSim ======

Visual3D 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 [[https://opensimconfluence.atlassian.net/wiki/spaces/OpenSim/pages/53088700/Tutorial+1+-+Intro+to+Musculoskeletal+Modeling|"Intro to Musculoskeletal Modeling”]]. It is assumed that the user is familiar with this tutorial and the files used in this process.

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

===== Modeling Requirements =====

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

  - 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).
  - 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.
  - 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 [[#Pose_Estimation_in_Visual3D|below]]).
  - 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 [[Visual3D:Documentation:Third-Party:OpenSim:Virtual_Lab_for_OpenSim|v3d_lab]].

See [[Visual3D:Documentation:Third-Party:OpenSim:Virtual_Lab_for_OpenSim|Virtual_Lab_For_OpenSim]] for an example of how to create of Visual3D v3d_lab.

==== Pose Estimation in Visual3D ====

Visual3D offers two methods of pose estimation: 1) [[visual3d:documentation:kinematics_and_kinetics:six_degrees_of_freedom|6 degree of freedom]] (based on Spoor and Veldpaus, 1980) and 2) [[visual3d:documentation:kinematics_and_kinetics:inverse_kinematics|Inverse Kinematics]] (based on Lu and O'Connor, 1999). Any 6-degree of freedom joint in Visual3D is transformed into OpenSim's gait model constraints by applying the Inverse Kinematics method fit to the model using the constraints specified in the OpenSim gait23*.osim file:

  - 3 degree of freedom ball joint at the right hip, left hip and waist.
  - 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.
  - The ankle joint is hinge with the direction of the axis matching that of the gatt23*.osim model.
  - The subtalar joint is hinge with the direction of the axis matching that of the gatt23*.osim model.
  - 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.)


==== 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:

  - 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.)
  - 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).
  - Visual3D then uses Inverse Kinematics to fit the gait data to the newly calibrated model.

To recap, any export from Visual3D to OpenSim will not use a 6DOF model regardless of how the model is defined in Visual3D. Instead exports use a IK model incorporating the Opensim model constraints. This process is hard-coded inside Visual3D and occurs automatically.

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.

==== Model Scaling ====

Visual3D automatically scales the OpenSim model by:
  - 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.
  - 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.

**NOTE**: 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. [[http://c-motion.com/download/examples/OpenSim/OpenSim_Scale_Factors.zip|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.

**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 | 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 | 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 | 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 | Most users build their feet without markers at the very end of the foot and at the top of the head. Visual3D therefore uses the average thigh length to scale these segments. (Physical anthropometry studies have shown thigh length is a somewhat strongly correlated with height). |

===== Visual3D-to-OpenSim Exports =====

The Visual3D-to-OpenSim process is designed according to the OpenSim tutorial "Intro to Musculoskeletal Modeling". This requires special versions of several OpenSim xml input to be created, so Visual3D will create a number of new OpenSim xml files as part of any OpenSim export:
  - [[Visual3D:Documentation:OpenSim:Setup_Scale.xml|Visual3D_Setup_Scale.xml]]
  - [[Visual3D:Documentation:OpenSim:Setup_RRA.xml|Visual3D_Setup_RRA.xml]]
  - [[Visual3D:Documentation:OpenSim:Setup_CMC.xml|Visual3D_Setup_CMC.xml]]
  - [[Visual3D:Documentation:OpenSim:Scale_ScaleSet|Visual3D_Scale_ScaleSet]]

==== Correcting the Lumbar Tilt in the Exported Motion File ====

Visual3D's export dialog 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".

==== Exported Joint Angles ====

The angles that are exported to OpenSim are slightly different than the angles calculated in Visual3D because the Inverse Kinematics model used in the Visual3D-to-OpenSim export is a special version of Visual3D's IK model that exactly matches the gait2354 or gait2392 osim models.

The four main differences in this special Visual3d implementation of the IK are:
  - 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)
  - 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
  - the Hip joint center is the located at the values set in the gait2354 or gait2392 osim models
  - 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. You can skew the ankle and subtalar axes in Visual3D 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 IK 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.)

==== 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 [[Visual3D:Documentation:Third-Party:OpenSim:Manual_OpenSim|here]].

==== Comparing Visual3D and SIMM exporting to OpenSim ====

Visual3D and SIMM each accomplish a different task. You can think of the process of generating muscle driving simulations in OpenSim as occurring in three steps:

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

SIMM works at Step 1. 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 practically speaking if you are looking 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.

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 from the expected marker set then importing the motion capture and force plate data into OpenSim can be a very cumbersome process. Visual3D will also allow you to do many, many more standard kinematic and kinetic analyses from your 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.

==== 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 Inverse 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.

**NOTE**: Before running OpenSim's Inverse Dynamics tool you need to load the osim model, scale the model and load the .mot file exported by Visual3D.

===== Compatibility =====

  - Visual3D v4.0 - The basic Visual3D-to-OpenSim integration is available.
  - Visual3D v4.9.3 - Compatible with OpenSim version 2.4.0.
    - OpenSim version 2.4.0 looks for the ground reaction force data in a separate .xml or .mot file. Visual3D v4.9.3 and later will generate this new ground reaction force file, named 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.)
    - Visual3D now automatically scales the torso and feet to be equal to the average of the left and right femoral lengths with the new torso and feet manual scale factors written to Visual3d_Scale_ScaleSet.xml. 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. Using the average thigh length seems a reasonable scaling approximation for these segments as physical anthropometry studies have shown thigh length is a somewhat strongly correlated with height.
    - 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.

  - OpenSim 4.0 - IOpening (File -> Load Motion) the Visual3d_SIMM_input.mot file in previous versions of OpenSim 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 [[https://opensimconfluence.atlassian.net/wiki/spaces/OpenSim/pages/53089193/Associating+Data+with+a+Motion|associate the Visual3d_SIMM_grf.mot file using these steps]].

==== Example ====

An example of this export process can be found [[Visual3D:Documentation:OpenSim:Visual3D_to_OpenSim_Demo|here]].