Upgrade Notes for OpenSim 4.0

The OpenSim Desktop Application

The OpenSim 4.0 Graphical User Interface (GUI) operates in a very similar manner to the OpenSim 3.0 GUI with a few differences to note:

• The visualizer is new. In the top right of the visualizer window you will find controls to change the location of a light source for shadows, floor texture, background colors etc.

• Navigating in the view uses different mouse controls

• Selection of model geometry and muscle path points is now indicated by a yellow bounding box. 

• A new color scheme is the default for muscles

• Screen capture outputs high-resolution PNG files. Movie capture outputs webm format, for all platforms (including 64bit).

Upgrading your model files

• The XML format of model files has changed due to underlying improvements in the API. Editing osim files by hand in a text editor may be more challenging, but we provide several scripts to edit files (see the file Code/GUI/modelBuildingUtilities.py in the Resources directory) and you can also utilize the GUI’s Property Editor Property Editor and Outputs List.
• OpenSim 4.0 version model files are not compatible with 3.3 or earlier versions. Do not save a 3.3 version model in 4.0 if you want to be able to also use it in 3.3. OpenSim models from versions 2.4 to 3.3 should open without issue in 4.0 (with the potential changes noted below).
• Components (i.e., muscles, markers, joints, etc.) in a model must all have unique names. OpenSim 4.0 will automatically rename components upon loading a 3.3 or earlier version file with duplicate names. Or edit the model file before opening to resolve duplicates with your own naming scheme.
• Mesh files that are binary vtp files or stl/obj files that contain multiple volumes are not supported in version 4.0. These meshes can be modified to ascii vtp files using Paraview or MeshLab, also multiple volumes can be separated into multiple files using Meshlab or other third party tools.
• If you are using models with CustomJoints that have coupled motion, you may need to redefine your joint definitions. In OpenSim 4.0, we eliminated the potential for MotionType inconsistencies by using the Joint type to determine the MotionTypes of its coordinates. For a CustomJoint, a coordinate is considered Rotational (or Translational) if and only if it is a pure rotation (or translation) along one of the corresponding six spatial transform axes, which means the relationship is 1 to 1 (e.g., linear function of slope +/-1). If the transform axis motion is any other function it is interpreted as Coupled where the motion about that axis is coupled to the generalized coordinate and it is not a physical measure of spatial motion (not an angle or displacement in Cartesian axes) of the joint's child frame. When you load an older (v3.3 or earlier) model in the GUI that has incorrect motion types for some coordinates, the GUI will present you with a warning. Follow the suggestions in the GUI's warning:
  • If you want to keep using your older model file with 4.0, update the motion_type of coordinates. This usually means changing a coupled coordinate's motion_type from Rotational to Coupled.
  • Use the function updatePre40KinematicsFilesFor40MotionType() to fix older MOT files which would have incorrectly converted the units of some coordinates. This function is available in the GUI Scripting Shell, Python, Matlab, and C++.
• If you saved a model file using the beta version of OpenSim 4.0 from August 2018, the model will not work in the released version of OpenSim 4.0. You can fix this by using the function updateSocketConnecteesBySearch() in the GUI Scripting Shell, Python, Matlab, or C++.

  • In the GUI ScriptingShell:

    >>> model = modeling.Model('my_model_file_version_30516.osim')
    >>> modeling.opensimSimulation.updateSocketConnecteesBySearch(model)
    >>> model.print('my_model_file_4.0.osim')
     

• Additional details and changes are listed in the full log of changes to the API

Running OpenSim tools from the command line

We created a new unified command line interface that will replace the single-tool command line executables (scale, ik, id, rra, cmc, etc.). For example, to run scale, the call is now:

scale -S setup.xml -> opensim run-tool setup.xml.

 Read more.

Upgrading your scripts and C++ code

• See the full log of changes to the API

• Please note that if you created model, setup or other files with a beta version of OpenSim 4.0, these may not load properly in 4.0. You can update your xml files by hand to match the latest version in 4.0 or load your 3.3 version files and then make your changes in the official 4.0 release.