How to Use the Scale Tool

The topics covered in this section include:

How to Use the GUI

The Scale Tool is accessed by:

• Select Tools  → Scale Model... from the OpenSim main menu bar.

• You need the model you want to be scale to be current. To learn how to make a model current visit Opening, Closing, and Using the Navigator Window.

The Scale Tool is controlled by a window with three tabbed panes. The  is used to specify parameters relating to the subject data, the generic model, and how the model is to be scaled. The Scale Factors Pane is used to specify the scale factors for each segment. The Scale Static Pose Weights Panel pane is used to specify weights on marker positions and joint angles for solving an inverse kinematics problem for the static pose. The inverse kinematics solution for the static pose is used to place the virtual markers on the model so that they coincide with the measured marker locations on the subject.

The Control Panel

At the bottom of all the Tool dialog windows are four buttons, located in what we call the Control Panel.

The Load and Save buttons are used to load or save settings for the tool.  The Run button starts execution.  The Close button closes the window. The Help button takes you to the relevant section of the User Guide. Note that the Close button can be clicked immediately after execution has begun; the execution will complete even though the window has been closed.   If you click Load…, you will be presented with a file browser that displays all files ending with the .xml suffix. You may browse for an appropriate settings file (e.g., subject01_Forward_Setup.xml or subject01_Scale_Setup.xml)) and click Open. The tool will then be populated with the settings in that setup file. If you have manually entered or modified settings, you may save those settings to a file for future use. If you click Save…, a Save dialog box will come up in which you can specify the name of the settings file. The name you specify for the file should have a suffix of .xml. Click Save to save the settings to file. After you click Save, you may be presented with another dialog box that asks you whether or not you would like to save some of the settings to separate external files. This can be useful if you would like to reuse those settings for other trials or subjects. Check the boxes of the settings that you'd like to save to external files and specify the names of these files. All of these files should have a suffix of .xml.

The Settings Pane

The Settings pane is used to specify parameters related to the subject data, the generic model, and how the model is to be scaled. The panel is organized into four main sections, described below.

Generic Model Data

The section for Generic Model Data displays uneditable information about the generic model that is to be scaled. It gives the model name, the model mass, and whether or not a marker set is included as part of the model).

Subject Data Section

The section for Subject Data displays editable information that allows you to specify the name of the new model that will be generated, the subject's total mass, and whether or not to add markers to the model from an external marker set. If you select the check box next to Add markers from file, you will be required to specify a settings file that contains markers. You may use the folder button to browse for a marker set. Once a marker set is read in, the number of markers in the marker set will be displayed just below the file name.

Controlling Model Scaling

The Scale Model section provides access to basic settings for specifying how a model is scaled. If the Scale Model box in the upper left-hand corner is not checked, the model will not be scaled. If the box is checked, the model will be scaled and a number of options become available. When the box for Preserve mass distribution during scale is checked, the total mass of the generic model is scaled so that it equals the mass of the subject while preserving the relative masses of its body segments. So, for example, if in the generic model the mass of the thigh is twice that of the shank, the mass of the thigh in the scaled model will also be twice that of the scaled shank. If this check box is not checked, the segment masses are scaled based solely on the scale factors applied to each body segment, and the total mass of the model will not equal the experimentally-measured mass of the subject.

To use measurement-based scaling, a .trc file that contains suitable marker data must be specified. A static trial (i.e., a trial in which the subject is stationary in some known position) is typically used for this purpose. To specify a file containing marker data, check the box labeled Marker data for measurements. When this is done, you will be able to specify a file in the text box to the right. Click the  button to browse for a file. Once the marker data is loaded, information about the trial will be displayed in a box on the far right entitled Marker Data. The information includes the total number of markers in the .trc file (the marker data is arranged in columns of x, y, and z coordinates), number of frames, frame rate, and the time interval over which the data is available. The distances between marker pairs used to compute the scale factors for the segments is based on averaging the marker positions over a time interval. To specify the time interval, enter the starting and final times in the text boxes to the right of the label Average measurements between times. The starting time should always be less than or equal to the final time. If you are computing scale factors based on a dynamic trial (i.e., a trial in which the subject was moving), use a small time interval or specify the same starting and final time to pick out a single frame of data.

Adjusting Model Markers

The Adjust Model Markers section provides access to basic settings for specifying how markers on the model should be moved to match the experimental locations. If the Adjust Model Markers box is not check, the model markers will not be moved. If the box is checked, a number of options become available. The text box labeled Marker data for static pose is used to specify the .trc file containing the experimental marker locations. Typically, this file is the same file used to scale the model, but this is not necessary. The name of the file can be typed in the box, or you can click the folder button to browse for the file. Once the marker data is loaded, information about the trial will be displayed in a box on the far right entitled Marker Data. The information includes the total number of markers in the .trc file (the marker data is arranged in columns of x, y, and z coordinates), number of frames, frame rate, and the time interval over which the data is available.

Before the virtual markers on the model can be moved, the model must be put into a position that closely matches the position of the subject. This includes placing the model in the correct location in the laboratory (three translations and three rotations) and also finding an appropriate set of joint angles to match the pose of the subject. To do this, the locations of all the experimental markers are averaged over a specified time interval, and an inverse kinematics problem is solved to find the joint angles that minimize the position error between the model markers and the corresponding average experimental markers. To specify the time interval over which the experimental marker locations are averaged, enter the starting and final times in the text boxes to the right of the label Average markers between times. The starting time should always be less than or equal to the final time. If you are using a dynamic trial (i.e., a trial in which the subject was moving), use a small time interval or specify the same starting and final time to pick out a single frame of data.

Unlike the settings controlling the scaling of the model, the settings for adjusting the model markers also allow you to specify coordinate data (e.g., angle joints in the model). This data can be used to control or influence the inverse kinematics solution. For example, if you already had joint angles for the static pose provided by the motion capture software that was used, you could specify a .mot file and use the joint angles contained in the motion file to place the model in an appropriate pose for adjusting the marker positions. To specify a coordinate data file, select the box labeled Coordinate data for static pose. Once this box is checked, you can type the name of a .mot file in the text box directly to the right or use the  button to browse for one.

Previewing Scale Solution and Static Pose

Frequently, it is helpful to preview the inverse kinematic solution for the static pose before adjusting the positions of the model markers. This can be useful for identifying markers that are poorly placed on the model that you may need to manually adjust or may decide not to include in the inverse kinematic problem. Checking the box labeled Preview static pose (no marker movement) will display the inverse kinematic solution in a 3D View without any adjustments made to the original model marker locations.

Once all the settings have been made on the Settings pane, use the Scale Factors pane to control exactly how each segment in the model is scaled.

Scale Factors Pane

The Scale Factors pane is used to specify the factors by which each segment in the model will be scaled. Settings for each body are listed in the table in the upper portion of the pane. Each row contains the name of the body, the measurement(s) used for that body, and the applied scale factor(s). The measurement(s) consist of either a label declaring MANUAL SCALES, indicating that the scale factors were specified manually, or a list of measurements (as shown for the femur_r segment). A measurement is a list of marker pairs; the distances between these markers are used to compute the scale factors applied to the segment in question. The measurement set is edited by clicking on the Edit Measurement Set button. Each segment can be scaled uniformly by a single scale factor (one scale factor is displayed) or non-uniformly by three independent scale factors along the X, Y, and Z axes of the body segment (three scale factors are displayed).

The controls at the bottom of the pane are used to specify the type of scaling and the scale factors for the selected segment. When a body is selected, such as the pelvis, the settings for that segment become editable. You can select one of two radio buttons to Use measurements or Use manual scales. To the right of each of the radio buttons are three text fields that are used to specify the scale factors that will be applied to the segment along the X, Y, and Z axes of the body. A typical choice for reference frames is X perpendicular to the frontal plane pointing forward, Y perpendicular to the transverse plane pointing up, and Z perpendicular to the sagittal plane pointing to the right. The choice of reference frames depends on how the model was constructed and may vary from model to model.

Using Measurement-Based Scaling

To specify scale factors based on measurement:

Click the Use measurements radio button. Click in any of the three scale-factor fields to the right. Select a measurement for the scale factors that will be applied along the X, Y, and Z axes of the selected body. Clicking in any of these fields brings up a list of defined measurements (torso, pelvis, thigh, etc). If the Uniform check box is checked, equal signs appear between the scale-factor fields, and any entry made in one field will be set for the others Use the Edit Measurement Set button to inspect and edit the measurements.

Using Manual Scale Factors

To specify scale factors manually:

click the Use manual scales radio button Type in the three fields to the right to specify the factors that will be applied along the X, Y, and Z axes of the selected body. If the Uniform check box is unchecked, the three factors can be different from each other. Clicking the Reset to Measurement button will compute scale factors based on any measurement that was previously set for that segment.

For each segment, you may choose to apply one uniform scale factor, or three different scale factors along the X, Y, and Z axes of the segment. The checkboxes labeled Uniform to the right of the three scale-factor fields are used to choose between uniform and non-uniform scaling. When checked, equal signs appear between the three scale-factor fields, and any value specified in one field will be propagated to the other two. When a box is not checked, you can specify the measurement or scale factors for the X, Y, and Z directions independently.

The Reset to Measurement button is used in conjunction with manual scale factors. As a convenience, clicking the Reset to Measurement button will compute scale factors based on any measurements that were previously set for a segment, giving a starting place for modifying the manual scale factors.

Editing the Measurement Set

Clicking the Edit Measurement Set button of the Scale Factors pane brings up an editor that allows you to inspect and edit the definitions of the measurements that can be used to compute scale factors for body segments. The name of each measurement is displayed in the far left-hand column, and the marker pairs that make up a measurement are listed to the right.

Definitions for the measurements used to scale the segments can be inspected and edited by clicking the Edit Measurement Set button . Doing so brings up another table that contains, in each row, the name of a measurement and the list of marker pairs that make up that measurement. The distances between the experimental marker pairs, relative to the distances between the same markers on the model, are used to compute the scale factors (How Scaling Works). To edit which markers make up a pair, click on one of the markers. A list of available markers will pop up, and you can then select from the list. Use the  buttons to delete measurements or marker pairs, and the  buttons to add new measurements or marker pairs. Click the  button in the lower right or the  button in the upper right-hand of the window when you are finished inspecting or editing the measurements. Any changes you made will be saved; the only way to undo any changes you made is to undo them manually. Once a measurement has been added to the set, it will appear among the choices you have for computing the scale factors.

Scale Static Pose Weights Panel

Once a marker and possibly a coordinate file have been specified, the specific behavior of the scaling tool can be described and modified using the Weights pane (Figure below). Each entry in the table represents a task in the least-squares matching for either a marker (top table) or a coordinate (lower table). By left-clicking on a row, you select it, making the entry fields below the tables editable so you can specify weights and values for the selected marker(s) or coordinate(s). This means the coordinate is being actively tracked (e.g. constrained to a specific joint angle). You can select multiple rows to edit by using ctrl + left-mouse-click or shift + left-mouse-click.

The weight value affects to what degree a match should be satisfied. Larger weightings penalize errors for that marker or coordinate more heavily and thus should match the experimental value more closely (see How Scaling Works). For coordinates, the coordinate value to be matched can come from a specified motion file, be set to its default value, or be set to a user-specified (manual) value.

Command-line Execution

The Scaling Tool can also be run using the command scale -S <setup file name>, for example:

scale -S subject01_Setup_Scale.xml