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="30000">
	<ScaleTool name="subject01">
		<!--Mass of the subject in kg.  Subject-specific model generated by scaling step will 
			have this total mass.-->
		<mass>72.6</mass>
		<!--Height of the subject in mm.  For informational purposes only (not used by scaling).-->
		<height>1803.4</height>
		<!--Age of the subject in years.  For informational purposes only (not used by scaling).-->
		<age>99</age>
		<!--Notes for the subject.-->
		<notes>This is an example setup file for scale.exe.</notes>
		<!--Specifies the name of the unscaled model (.osim) and the marker set.-->
		<GenericModelMaker>
			<!--Model file (.osim) for the unscaled model.-->
			<model_file>gait2354_simbody.osim</model_file>
			<!--Set of model markers used to scale the model. Scaling is done based on distances 
				between model markers compared to the same distances between the corresponding 
				experimental markers.-->
			<marker_set_file>gait2354_Scale_MarkerSet.xml</marker_set_file>
		</GenericModelMaker>
		<!--Specifies parameters for scaling the model.-->
		<ModelScaler>
			<!--Whether or not to use the model scaler during scale-->
			<apply>true</apply>
			<!--Specifies the scaling method and order. Valid options are 'measurements', 'manualScale', 
				singly or both in any sequence.-->
			<scaling_order> measurements manualScale</scaling_order>
			<!--Specifies the measurements by which body segments are to be scaled.-->
			<MeasurementSet name="gait2354"> 
				...
			</MeasurementSet>
			<!--Scale factors to be used for manual scaling.-->
			<ScaleSet name="gait2354_Scale">
				...
			</ScaleSet>
			<!--TRC file (.trc) containing the marker positions used for measurement-based scaling. 
				This is usually a static trial, but doesn't need to be.  The marker-pair distances 
				are computed for each time step in the TRC file and averaged across the time range.-->
			<marker_file>subject01_static.trc</marker_file>
			<!--Time range over which to average marker-pair distances in the marker file (.trc) for 
				measurement-based scaling.-->
			<time_range> 1 2</time_range>
			<!--Flag (true or false) indicating whether or not to preserve relative mass between 
				segments.-->
			<preserve_mass_distribution>true</preserve_mass_distribution>
			<!--Name of OpenSim model file (.osim) to write when done scaling.-->
			<output_model_file>subject01_scaledOnly.osim</output_model_file>
			<!--Name of file to write containing the scale factors that were applied to the unscaled 
				model (optional).-->
			<output_scale_file>subject01_scaleSet_applied.xml</output_scale_file>
		</ModelScaler>
		<!--Specifies parameters for placing markers on the model once a model is scaled. -->
		<MarkerPlacer>
			<!--Whether or not to use the marker placer during scale-->
			<apply>true</apply>
			<!--Task set used to specify weights used in the IK computation of the static pose.-->
			<IKTaskSet name="gait2354_Scale_IKTaskSet">
				...
			</IKTaskSet>
			<!--TRC file (.trc) containing the time history of experimental marker positions (usually 
				a static trial).-->
			<marker_file>subject01_static.trc</marker_file>
			<!--Name of file containing the joint angles used to set the initial configuration of 
				the model -->
			<coordinate_file>Unassigned</coordinate_file>
			<!--Time range over which the marker positions are averaged.-->
			<time_range> 1 1.01</time_range>
			<!--Name of the motion file (.mot) written after marker relocation (optional).-->
			<output_motion_file>subject01_static_output.mot</output_motion_file>
			<!--Output OpenSim model file (.osim) after scaling and maker placement.-->
			<output_model_file>subject01_simbody.osim</output_model_file>
			<!--Output marker set containing the new marker locations after markers have been placed.-->
			<output_marker_file>Unassigned</output_marker_file>
			<!--Maximum amount of movement allowed in marker data when averaging frames of the static 
				trial. A negative value means there is not limit.-->
			<max_marker_movement>-1</max_marker_movement>
		</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 subject-specific model created by scale can be set to have a total mass equal to this specified mass value (see the <preserve_mass_distribution> tag described below).

<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. See Scaling Settings Files and XML Tag Definitions for more details about the contents of the ScaleSet.

Properties for measurement-based scaling

The relevant parameters for measurement-based scaling are <MeasurementSet>, <marker_file>, and <time_range>. <MeasurementSet> 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. 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.