Upgrade Notes for OpenSim 2.4

Converting your Model, Setup, and Data Files

In version 2.4 we added a few tools to facilitate the conversion of files to the latest format:

1. OpenSim 2.4 includes an auto conversion tool that tries to map objects from older file formats to the latest format. This code is triggered based on the Document version number at the top of .osim and .xml files.    
2. You can also access the conversion tool in the GUI through Help->Convert Files… allows users to open an existing file (.osim, .xml or .sto) and converting it to the latest format.
3. There is also a command line utility (versionUpdate) that operates like to the previous item.
4. Help->Available Objects… allows you to see the XML representation of various objects in the current version. This is helpful in testing plugins and for users editing XML files by hand (be careful not to mix objects from different versions/formats).
5. Our storage files (.sto) now contain a version number in the header, this will be used in the future to provide more meta-data about the contents of the file. The assumption made by the code is that angles in old .sto files are in radians (unless there was an explicit text "Angles are in degrees" in the file header). Newly created .sto files have angular units specified in their header.

Exceptions in the Conversion Process

We do our best to make the transition to the next version of OpenSim as smooth as possible; however, this is not always possible if you are using advanced features of the software or functionality that have been refactored or deprecated.  Some known exceptions for the tools above:

1. New objects/abstractions (ExternalLoads) didn't exist in previous versions, so there is no easy way to map old files to new files. We recommend that users create these files from scratch in the GUI or follow an example from the distribution.
2. InverseDynamics was previously an Analysis included with other analyses when running various tools.  Now it's a standalone tool with a new abstraction/object (InverseDynamicsTool). The GUI for Tools->Inverse Dynamics tries to map these old files to the new format, but the generic "Convert Files" does not handle this conversion.
3. RRATool is a new abstraction.  It was previously implemented as a CMCTool. The GUI for Tools->Reduce Residuals tries to map these old files to the new format, but the generic "Convert Files" does not handle this context.
4. Data files used to specify ExternalLoads are required to have unique labels so that there's no ambiguity regarding force specification (in the past we used a convention where we assumed only 2 forces on right then left foot, but this was confusing and was not flexible to meet user needs). You need to use the GUI to create a new ExternalLoads specification file and also to have OpenSim make the column labels unique (you'll be given a chance to save to a new file so that your raw data can stay untouched).