Scale Setup File

The topics covered in this section include:

There are 5 major sections to a scale setup file: execution parameters; subject-specific parameters (e.g., mass, height, age); parameters related to the generic model to scale; scaling properties; and marker placement properties. A sample scale setup file is provided below. 

Example: XML file for a scale setup file

 <?xml version="1.0" encoding="UTF-8"?> 
 <OpenSimDocument version="20000"> 
 <ScaleTool name="subject01"> 
 
    <mass> 72.6 </mass> 
    <height> 1803.4 </height> 
    <age> 99 </age> 
    <notes> This is an example setup file for scale.exe. </notes> 
 
 <GenericModelMaker name=""> 
    <model_file> gait2354.osim </model_file> 
    <MarkerSet file="gait2354_Scale_MarkerSet.xml"/> 
 </GenericModelMaker> 
 
 <ModelScaler name=""> 
    <scaling_order> measurements manualScale </scaling_order> 
 
    <ScaleSet file="subject01_Scale_ScaleSet.xml"/> 
 
    <MeasurementSet file="gait2354_Scale_MeasurementSet.xml"/> 
    <marker_file> subject01_static.trc </marker_file> 
    <time_range> 1 2 </time_range> 
 
    <preserve_mass_distribution> true </preserve_mass_distribution> 
 
    <output_joint_file> subject01_scaledOnly.jnt </output_joint_file> 
    <output_muscle_file> subject01_scaledOnly.msl </output_muscle_file> 
    <output_model_file> subject01_scaledOnly.osim </output_model_file> 
    <output_scale_file> subject01_scaleSet_applied.xml</output_scale_file> 
 </ModelScaler> 
 
 <MarkerPlacer name=""> 
    <IKTaskSet file="gait2354_Scale_Tasks.xml"/> 
    <marker_file> subject01_static.trc </marker_file> 
    <time_range> 1 2 </time_range> 
    <coordinate_file> gait2354_zeros.mot </coordinate_file> 
    <output_joint_file> subject01.jnt </output_joint_file> 
    <output_muscle_file> subject01.msl </output_muscle_file> 
    <output_model_file> subject01.osim </output_model_file> 
    <output_motion_file> subject01_static_output.mot </output_motion_file> 
 </MarkerPlacer> 
 
 </ScaleTool> 
 </OpenSimDocument> 

Specifying Execution Parameters

The properties for the scale operation are enclosed inside the opening and closing tags <ScaleTool> and </ScaleTool>. The name attribute name="subject01" specifies the execution name, though it is not used anywhere.

Specifying Subject-specific Parameters

Subject specific measurements are specified in the <mass>, <height>, and <age> properties. These are in kg, mm, and years, respectively. Currently, <height> and <age> are specified for informational purposes only, and do not affect the scaling result. (In fact, they do not appear in the subject-specific model output by scale). The <mass> property, however, is used: the final model will have a total mass equal to this specified mass value.

<notes> Tag

The <notes> property is another purely informational (for the user) property that does not get propagated to any output files.

Specifying a Generic Model to Scale

The generic model that will be scaled is specified within the <GenericModelMaker> tag. In particular, <model_file> points to the OpenSim (.osim) model file that will be scaled. In Example 14-1 above, it is gait2354.osim (a gait model with 23 degrees of freedom and 54 muscles).

The <MarkerSet> property can be used to add or update markers in the generic model. In the example, gait2354.osim does not include any markers, so the <MarkerSet> given in the external file gait2354_Scale_MarkerSet.xml (referred to using the file attribute) adds the full marker set necessary for this example. This file is described in more detail in the <marker file> tag section below.

Specifying Scaling Properties

Scaling properties are enclosed in the <ModelScaler> tag. As described in How Scaling Works, a combination of measurement-based and manual scaling can be used. <scaling_order> specifies which of the two is used (using the keywords measurements and manualScale, respectively), or, if both are listed, the order in which they are applied.

Properties for manual scaling

The <ScaleSet> tag is used to specify the scale set supplying the manual scale factors. In the example above, this tag refers to the external file subject01_Scale_ScaleSet.xml (using the file attribute). See Scaling Settings Files and XML Tag Definitions for more details about the contents of this XML file.

Properties for measurement-based scaling

The relevant parameters for measurement-based scaling are <MeasurementSet>, <marker_file>, and <time_range>. <MeasurementSet> (in this case specified in the external file gait2354_Scale_MeasurementSet.xml using the file attribute) specifies which marker pairs are used to compute the scales and which bodies those scale factors are applied to. In addition, the experimental marker positions need to be supplied. The <marker_file> property points to a .trc file containing these marker positions, and <time_range> indicates which subset of the frames in the .trc file the marker-pair distances should be averaged across.

Mass scaling properties

The <preserve_mass_distribution> property specifies whether the scaled model's segment masses should be in the same proportion as they were in the generic model (see How Scaling Works).

Specifying output of scaling-only step (before marker placement)

The scaling step can (optionally) produce a number of output files. Assuming the marker placement step is executed, none of the intermediary output files from the scaling step are strictly necessary, but can be useful for debugging (e.g., to see what the model looks like after scaling but before markers are moved). The properties controlling the output file names are:

• <output_model_file> generates the scaled-only OpenSim model file
• <output_scale_file> generates a <ScaleSet> file consisting of the x-y-z scale factors used to scale each segment

If the tags specifying these files are omitted or the file names are blank, then no files will be written.

Specifying Marker Placement Properties

The marker placement properties are enclosed within the <MarkerPlacer> tag. Note that it is valid to omit this section from the XML file if only scaling (and no marker placement) is desired.

As mentioned in How Scaling Works, a "static pose" needs to be defined and the model needs to be placed in a configuration matching that pose as best as possible. This reduces to an inverse kinematics (IK) problem, and so many of the properties used in the marker placement step are similar to the properties in IK. The reader should therefore refer to the IK chapter (Inverse Kinematics) for additional details on some of these properties.

The <IKTaskSet> property is used to specify the marker and coordinate weights which IK will use in order to compute the static pose. In the example above, a file attribute is used to refer to an external XML file. More details of the file contents are given below.

The <marker_file> and <coordinate_file> properties are used to specify files containing experimental marker and coordinate values, respectively. These values are used by the IK tool to compute the static pose.

<marker_file> tag

Since the file specified by the <marker_file> tag will in general have multiple frames of marker data (i.e., marker trajectories recorded during a static trial), these are averaged within the time range specified by the <time_range> tags to give a single, fixed set of experimental marker positions. If the experimental marker locations in <marker_file> do not represent a static trial (where the subject is not moving or only slightly moving) then averaging marker positions across a large time window does not really make sense. In this case, the values for <time_range> should be reduced and/or the file specified by <marker_file> should be edited to only contain a few rows of nearly-stationary marker positions.

<coordinate_file> tag

The coordinate values specified by <coordinate_file> are not averaged the same way the marker data is. Rather, the values from the row corresponding to the initial time of <time_range> are used. In the example XML file for a scale setup file, the coordinate values from time t=1 will be used as the "experimental coordinate values."

Moving markers to match experimental locations

The IK solver will be invoked to try to find generalized coordinate values for the model which put it in a pose that closely matches the "static pose" experimental marker positions and coordinate values. After the model's static pose is computed, a selected subset of the model's markers are moved to match the averaged experimental marker locations (those that were used to define the static pose).

Only markers which are tagged as "not fixed" are moved to match the experimental markers. This is done within the file specified by <MarkerSet>. Each marker that is moveable should have its <fixed> property set to false. <fixed> is a property of <Marker> (see Scale Marker File). The remaining markers are untouched.

Specifying final scaling and marker placement output

After marker placement, the final subject-specific model is ready for output. The only essential file to be output in this step is the subject-specific OpenSim model, specified in <output_model_file>. Additional files can be output:

• <output_motion_file> - a motion file consisting of a single row of values representing the "static pose" in which model markers were moved to match experimental markers. This file can be visualized in SIMM. Note: since this motion file only contains a single frame, to view it in SIMM's Model Viewer, you need to use the "start >" button to start playing the motion; the motion slider in SIMM does not appear to work.