OpenSim related files that are used in these examples for download
Visual3D Version 4.02 had a preliminary implementation of a feature which will allow the user to export an OpenSim compatible .mot file which can be used as input to OpenSim gait simulations.
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: simtk.org/home/opensim.
(Note: the default OpenSim model used in the Visual3d to OpenSim process is the model gait2392_simbody.osim which is distributed with the OpenSim software.)
Visual3d 4.02 now allows the user to export OpenSim compatible motion files designed for use with OpenSim gait models. To accomplish this Visual3d creates 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.
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.
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 trunk (RTA).
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 Appendix for an example of how to create of Visual3d v3d_lab.
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 (modified from subject01_Setup_Scale.xml)
The <ScaleTool> name has been changed to Visual3d.
The subject <mass> and <height> needs to be customized for each subject
The <Marker Set> is no longer required and reference to this file has been removed
<scaling_order> is set only to manualScale. (The manual scale factors for the segments will be written by Visual3d to the Visual3d_Scale_ScaleSet.xml file.)
The <MeasurementSet> .xml file and its corresponding .trc file are no longer needed and reference to these files have been removed
The <ModelScaler> section has been removed since this is now done by Visual3d
The <MarkerPlacer> section has been removed since this is now done by Visual3d
Visual3d_Setup_RRA.xml (modified from subject01_Setup_RRA.xml)
The <CMCTool> name has been changed to Visual3d_walk1_RRA
The <model_file> name has been changed to Visual3d_simbody.osim.
The <initial_time> and <final_time> for RRA have been set to 0.0 and 1.0 but this will be changed by the user when operating OpenSim to match the desired time range for RRA
The <desired_kinematics_file> is now Visual3d_SIMM_input.mot. This is the name of the file that is written by Visual3d containing the kinematics.
The <external_loads_file> is now Visual3d_SIMM_input.mot. This is the name of the file that is written by Visual3d containing the fore platform information.
The <external_loads_model_kinematics_file> is now Visual3d_SIMM_input.mot. This is the name of the file that is written by Visual3d containing the fore platform information.
Visual3d_Setup_CMC.xml (modified from subject01_Setup_CMC.xml)
The <CMCTool> name has been changed to Visual3d_walk1.
The <model_file> has been changed to Visual3d_simbody_adjusted.osim.
The <initial_time> and <final_time> for CMC have been set to 0.0 and 1.0 but this will be changed by the user when operating OpenSim to match the desired time range for CMC
The <desired_kinematics_file> has been changed to: ResultsRRA/Visual3d_walk1_RRA_kinemtics_q.sto.
The <external_loads_file> is now Visual3d_SIMM_input.mot. This is the name of the file that is written by Visual3d containing the fore platform information.
The <external_loads_model_kinematics_file> is now Visual3d_SIMM_input.mot. This is the name of the file that is written by Visual3d containing the fore platform information.
Visual3d_Setup_Foward.xml (modified from subject01_Setup_Forward.xml)
The <ForwardTool> name has been changed to Visual3d_walk1
The <model_file> name has been changed to Visual3d_simbody_adjusted.osim
The <initial_time> and <final_time> for Forward simulation have been set to 0.0 and 1.0 0 but this will be changed by the user when operating OpenSim to match the desired time range for the Simulation
The <controls_file> has been changed to: ResultsCMC/Visual3d_walk1_controls.xml
The <states_file file> has been changed to: ResultsCMC/Visual3d_walk1_states.sto
The <external_loads_file> is now Visual3d_SIMM_input.mot. This is the name of the file that is written by Visual3d containing the fore platform information.
The <external_loads_model_kinematics_file> is now Visual3d_SIMM_input.mot. This is the name of the file that is written by Visual3d containing the fore platform information.
Visual3d_Scale_ScaleSet (modified from subject01_Scale_ScaleSet.xml)
This file must be present so Visual3d can write the manual scale factors used for the pelvis, thigh and tibia segments.
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:
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.
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.
Start Visual3d and create a Visual3d hybrid model containing
the following segments:
right foot (RFT), right shank (RSK), right thigh (RTH), left
foot (LFT), left shank (RSK), left thigh (RTH), pelvis and a trunk (RTA)
If the subject is not walking in the +Y with +Z as vertical create a v3d_lab segment as outlined in the Appendix
Go to Model Building and select Inverse Kinematics Constraints tab
Hit Reset to select the default Degrees of Freedom
Got to the Segments tab, select Visual3d SIMM Algorithm for Computing Pose
Hit the Build Model button and complete the Ankle Offset Dialog. These values represent the plantar/dorsiflexion angle during subject calibration and used to adjust the Visual3d ankle angle to match the OpenSim model.
Once Visual3d has fit the original model to the OpenSim model (this can take up to a minute) a dialog will appear asking for the range of data for which you want to output the motion data.
Enter the data range and click the OK button.
Visual3d now needs the required Visual3d_Scale_ScaleSet.xml file and will bring up a File Selection Dialog to help the user make sure that Visual3d will update the correct file.
After selecting the ScaleSet file, Visual3d now applies the Inverse Kinematics process to the gait data. (This can take several minutes.)
Once steps 1-10 are completed, Visual3d will have updated the Visual3d_Scale_ScaleSet.xml file and have created a Visual3d_SIMM_input.mot file which can be loaded into OpenSim.
Start OpenSim and load the file openSim model. (This will be either gait2392_simbody.osim or gait2392_simbody.osim)
From the Tools pulldown select Scale Model
In the Scale Tool Dialog select Settings > Load Settings
Open the file Visual3d_Setup_Scale.xml
Uncheck the Adjust Model Markers box
Hit the Run botton to create the scaled model . The model will be called Visual3d in the Navigator window
Left Click on model 3DGaitModel2354 in the navigator Window then right click and select Close.
A dialog will appear – select No so you do not save settings.
Vusial3d will now be the only Model
From the File pull-down select Load Motion and load Visual3d_SIMM_input.mot
Hit the play button to Animate (On my computer I set the speed to 0.2)
At this point the users should be ready to run the OpenSim Residual Reduction Algorithm by loading the file: Visual3d_Setup_RRA.xml. OpenSim CMC and Forward Simulation can subsequently be run by using the files Visual3d_Setup_CMC.xml and Visual3d_Setup_Foward.xml.
For example if a lab was set up such that the person walked in the –X direction, +Z was vertical, and +Y was to the subjects left. (See Appendix for an example of Visual3d mdh script could be used to create a compatible virtual lab.
! Segment v3d_lab
HYBRID_SEGMENT
! /CALIBRATION_FILE=
/TYPE=Visual_3D
/NAME=v3d_lab
/REFERENCE_OBJECT=Medial Distal+Lateral Distal+Medial Proximal+Lateral
Proximal+Proximal Joint+Distal Joint+Additional Object+Additional Plane+Distal
Radius+Proximal Radius
/REFERENCE_OBJECT_NAMES=v3d_lab_med_distal+v3d_lab_lat_distal+v3d_lab_med_prox+v3d_lab_lat_prox++++Medial+v3d_lab_Distal_Radius+v3d_lab_Proximal_Radius
/REFERENCE_OBJECT_TYPES=LANDMARK+LANDMARK+LANDMARK+LANDMARK+++++METRIC+METRIC
/USE_CAL_TARGETS_FOR_TRACKING=FALSE
/TRACKING_TYPES=LANDMARK+LANDMARK+LANDMARK+LANDMARK
/TRACKING_NAMES=v3d_lab_lat_prox+v3d_lab_med_prox+v3d_lab_lat_distal+v3d_lab_med_distal
! /USE_OPTIMAL_TRACKING=TRUE
/KINEMATIC_ONLY=TRUE
! /STATIC_MODEL=FALSE
/GRAPHICS_ROT_X=0
/GRAPHICS_ROT_Y=0
/GRAPHICS_ROT_Z=0
/GRAPHICS_SCALE_X=1
/GRAPHICS_SCALE_Y=1
/GRAPHICS_SCALE_Z=1
/GRAPHICS_TRANSLATE_X=0
/GRAPHICS_TRANSLATE_Y=0
/GRAPHICS_TRANSLATE_Z=0
! /GRAPHICS_UNIT_SCALE=1.000000
/MASS=0.000000
! /GEOMETRY=
/PROX_TO_CG_AXIAL=0.5*v3d_lab_SEG_LENGTH
/PROX_TO_CG_ML=0*v3d_lab_SEG_LENGTH
/PROX_TO_CG_AP=0*v3d_lab_SEG_LENGTH
/IXX=0
/IYY=0
/IZZ=0
! /AP_DIRECTION=
! /AXIAL_DIRECTION=
! /OBJFILE=
! /COLFILE=
! /DEPTH=
;
! Landmarks
Add_Landmark
/LANDMARK_NAME=v3d_lab_lat_prox
! /CALIBRATION_FILE=
! /USER_GENERATED=TRUE
! /USE_PERCENTAGE=FALSE
! /CALIBRATION_ONLY=FALSE
! /USE_TARGETS=FALSE
/SEGMENT_NAME=LAB
! /TARGET_TYPES=
! /TARGET_NAMES=
! /MCSX=0.0
/MCSY=0.001
! /MCSZ=0.0
! /LANDMARK_LOCATION=
! /REFERENCE_LOCATION_NAME=
! /REFERENCE_LOCATION_TYPE=
! /USE_REFERENCE_LOCATION=FALSE
;
Add_Landmark
/LANDMARK_NAME=v3d_lab_med_prox
! /CALIBRATION_FILE=
! /USER_GENERATED=TRUE
! /USE_PERCENTAGE=FALSE
! /CALIBRATION_ONLY=FALSE
! /USE_TARGETS=FALSE
/SEGMENT_NAME=LAB
! /TARGET_TYPES=
! /TARGET_NAMES=
! /MCSX=0.0
/MCSY=-0.001
! /MCSZ=0.0
! /LANDMARK_LOCATION=
! /REFERENCE_LOCATION_NAME=
! /REFERENCE_LOCATION_TYPE=
! /USE_REFERENCE_LOCATION=FALSE
;
Add_Landmark
/LANDMARK_NAME=v3d_lab_lat_distal
! /CALIBRATION_FILE=
! /USER_GENERATED=TRUE
! /USE_PERCENTAGE=FALSE
! /CALIBRATION_ONLY=FALSE
! /USE_TARGETS=FALSE
/SEGMENT_NAME=LAB
! /TARGET_TYPES=
! /TARGET_NAMES=
! /MCSX=0.0
/MCSY=0.001
/MCSZ=-0.001
! /LANDMARK_LOCATION=
! /REFERENCE_LOCATION_NAME=
! /REFERENCE_LOCATION_TYPE=
! /USE_REFERENCE_LOCATION=FALSE
;
Add_Landmark
/LANDMARK_NAME=v3d_lab_med_distal
! /CALIBRATION_FILE=
! /USER_GENERATED=TRUE
! /USE_PERCENTAGE=FALSE
! /CALIBRATION_ONLY=FALSE
! /USE_TARGETS=FALSE
/SEGMENT_NAME=LAB
! /TARGET_TYPES=
! /TARGET_NAMES=
! /MCSX=0.0
/MCSY=-0.001
/MCSZ=-0.001
! /LANDMARK_LOCATION=
! /REFERENCE_LOCATION_NAME=
! /REFERENCE_LOCATION_TYPE=
! /USE_REFERENCE_LOCATION=FALSE
;