The topics covered in this section include:

How to Use the GUI

To launch the IK Tool:

	Select Tools → Inverse Kinematics from the OpenSim main menu bar. The Settings pane is used to specify parameters related to the experimental marker data. The Weights pane is used to specify the marker and coordinate weights used in the weighted least squares equation.

The Inverse Kinematics Tool window, like all other OpenSim tools, operates on the current model. The name of the current model is shown in bold in the Navigator window. Any model can be made the current model by right-clicking on its name and selecting Make Current. See Opening, Closing, and Using the Navigator Window for information on opening models and making a particular model current.

Settings Pane

The Settings pane is used to specify parameters related to the experimental marker data. The pane is organized into two main sections: Current Model and IK Trial.

The section for Current Model displays uneditable information about the current model. It gives the model name, as well as the number of markers associated with the model. Inverse kinematics requires that a marker set is associated with the model. This association with a subject-specific model is established at the time that a generic model is scaled to the subject markers visit Scaling for more information. The IK Trial section specifies the experimental marker data that the IK Tool will match with the current model. A Trial name can be associated with the trial to uniquely identify the resultant motion. The Marker data for trial field contains the path to the marker data (in .trc format). Information from the file, such as the number of markers, the number of frames and the sampling frequency, as well as the start and end times of the data set, are reported in the Marker Data box on the right-hand side. You can specify the time range for performing inverse kinematics in the Time range field. By default, the complete time range is used. If you are using experimental generalized coordinate values in the IK trial, check the Coordinate data for trial checkbox and then specify the motion (.mot) file with the coordinate values in the textbox to the right.

Weights Pane

Once a marker and possibly a coordinate file have been specified, the specific behavior of the inverse kinematics 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). 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 Inverse Kinematics 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. When running the IK Tool using the GUI, the results are not automatically saved to a file. They are associated with the model under its Motions node in the Navigator window (Navigator Window). You can view multiple IK results before saving them to a file. To save the IK results to a file, right click on the motion in the Navigator window and select Save as.

The Control Panel

The control panel at the bottom of the dialog window is used to save the settings in the dialog to a file, read the settings from a file, and to run IK. It has the same behavior as described in Scale Setup File 

Command Line Execution of IK

The Inverse Kinematics Tool is run using the command ik -S <setup file name>, for example:

ik -S subject01_Setup_IK.xml 

Inverse Kinematics Setup File

There are three properties that need to be specified in an inverse kinematics setup file:

1. The model to which the IK solver is to be applied;
2. The marker and coordinate error weightings to be used; and
3. The specific trials to be used by the solver.

A sample inverse kinematics setup file is provided in the example beow: 

<?xml version="1.0" encoding="UTF-8"?>

<IKTool name="subject01">

  <model_file> subject01.osim </model_file>

  <IKTaskSet file="gait2354_IK_Tasks.xml"/> 

  <IKTrialSet name="">
    <objects>

      <IKTrial name="first trial">
        <marker_file> subject01_walk1.trc </marker_file>
        <coordinate_file> subject01_walk1.mot </coordinate_file>
 
        <time_range> 0.4 2.0 </time_range>
 
        <output_motion_file> subject01_walk1_ik.mot  </output_motion_file>
      </IKTrial>
 
    </objects>
  </IKTrialSet> 
 
</IKTool>

Example IK Setup File: XML file for an inverse kinematics setup file

IK Execution Parameters

The parameters/properties for running the IK tool are enclosed inside the opening and closing tags <IKTool> and </IKTool>. If desired, the name attribute name="subject01" can be used to specify the execution name, though it is not used anywhere.

Model

The <model_file> property specifies the file name of an OpenSim (.osim) model that will be used to match the experimental data and/or coordinate values. Typically this will be the subject-specific scaled model generated by the Scale Tool.

IK Tasks

The IK tasks are used to specify the weights on the marker and coordinate error terms used by the IK solver. The set of IK tasks is specified in the <IKTaskSet> property. In Settings Files and XML Tag Definitions for IK, it points to an external file (gait2354_IK_Tasks.xml) using the file attribute, but the IKTaskSet could be specified in the setup file itself. A separate IK tasks file is useful if several models (subjects) will share the same set of IK tasks. Details for specifying the IK tasks file is presented below.

Per-trial Properties

Multiple experimental trials for the same subject/model can be processed during a single execution of IK. The IK Tool will process each trial in sequence and output individual motion files for each set of trial (IKTrial) settings.

The settings for each trial are enclosed by the <IKTrial> and </IKTrial> tags, and the <IKTrialSet> and </IKTrialSet> tags enclose a set of such trials. The <objects> tag is needed because this is a set of data. Note that in the XML file shown in the Example IK Setup File above, only a single trial is computed.

For each trial, the following parameters are needed: the file name for the experimental marker trajectories, the file name for the experimental coordinate values, the time range for computing the inverse kinematics, and the output motion file name. Each of these parameters is explained in more detail in the following sections.

Experimental marker and coordinate values

The <marker_file> property specifies a .trc file containing marker trajectories for this trial. These trajectories give the experimental marker positions which IK will attempt to match as described in How Inverse Kinematics Works.

The <coordinate_file> property specifies a .mot file containing experimental coordinate values (e.g., joint angles computed using anatomical reference frames) for this trial. These values are read in from the file only if there is an IK Task for the coordinate that has a <from_file> tag set to true (see <IKCoordinateTask> in the Example IK Task File below).

If none of the coordinates have <from_file> set to true, the <coordinate_file> property becomes optional. However, a coordinates (motion) file is typically specified even in this situation, because it may also contain other data, such as ground reaction forces and torques, which are copied into the output file generated by IK.

Time range

The <time_range> tag specifies the start and end times for the IK computation (e.g., t=0.4s to t=2.0s in the example above). The time values are in whatever units of time were used in the marker and coordinate files, which must share a range with one another. Note that IK does not require time be expressed in seconds. However, future dynamics analyses which compute accelerations must have time expressed in seconds.

A start time earlier than the first available marker/coordinate data is snapped to the initial time of the data. Similarly, the end time is snapped to the final time of the data, if necessary. Time points that do not coincide with discrete times in the experimental data set are snapped to the nearest time point before the specified time. For example, a specified end time of 0.410s will be snapped to 0.400s if the next time instant is 0.417s from a motion capture system sampling at 60Hz.

Note that the marker file is used to determine the actual time steps (frames) at which IK is computed. Furthermore, if a coordinate file is used, the time values of the rows of data in the coordinate file must match the time values of the data in the marker file. OpenSim will report an error if a corresponding time in the coordinate file cannot be found.

Output file

<output_motion_file> specifies the name of the motion file generated by IK. The columns of this file are:

• Unprescribed generalized coordinates (those solved for by IK), followed by
• Prescribed generalized coordinates (those with fixed values not solved for by IK), followed by
• Any user data (data found in the <coordinate_file> which is not directly used by IK, e.g., ground reaction forces)

Each row represents an instant for which IK determined coordinates corresponding to the times in the marker data file. As a motion (.mot) file, each column has an associated label identifying the joint coordinate, ground reaction, center of pressure, etc. values.

Inverse Kinematics Tasks File

The inverse kinematics tasks file is an external XML file containing the <IKTaskSet> tags used to specify properties associated with error terms during the IK computation. This file is referred to from the main IK setup file (see the Example IK Setup File above). An example IK tasks file is given in Example IK Task File below. Recall that this file is common to all IK trials. 

<?xml version="1.0" encoding="UTF-8"?>
 
<IKTaskSet name="gait2354_IK">
  <objects>

    <!-- Markers -->
    <IKMarkerTask name="Sternum"> <weight>1</weight> </IKMarkerTask>

    <IKMarkerTask name="R.Acromium"> <weight>0.5</weight></IKMarkerTask>

    <IKMarkerTask name="L.Acromium"> <weight> 0.5 </weight></IKMarkerTask>

    <IKMarkerTask name="Top.Head"> <weight> 0.1 </weight> </IKMarkerTask>

    <!-- . . additional <IKMarkerTask> tags cut for brevity . . -->

    <!-- Coordinates -->
    <IKCoordinateTask name="subtalar_angle_r"> <value> 0 </value></IKCoordinateTask>

    <IKCoordinateTask name="mtp_angle_r"> <value> 0 </value></IKCoordinateTask>

    <IKCoordinateTask name="subtalar_angle_l"> <value> 0 </value></IKCoordinateTask>

    <IKCoordinateTask name="mtp_angle_l"> <value> 0 </value></IKCoordinateTask>

  </objects>

If desired, the name attribute (e.g., name="gait2354_IK" as shown above) can be used to specify the execution name for IKTaskSet, though it is not used anywhere.

Marker Tasks

The <IKMarkerTask> tags are used to specify the weights associated with the marker error terms in the IK formulation. A specific marker is identified using the name attribute of <IKMarkerTask>.

The <weight> property specifies the weight multiplying the squared-error term for that marker. These weights are the w_i's appearing in the formula given in How Inverse Kinematics Works. A larger weight means that the error term for that marker will be more significant in the least-squares equation, so the IK computation will try to find a closer match between that marker's position and its experimental position, as compared to a marker with a smaller weight. By default, the weight for a marker is assumed to be zero, indicating that the IK solver will not attempt to match that marker to its experimental position. The default weight is used if <weight> is not specified or if the <IKMarkerTask> is omitted for a marker.

Experimental marker positions are not specified here. They come from the .trc file specified by the <marker_file> property of the <IKTrial> specified in the Example IK Setup File.

Coordinate Tasks

The <IKCoordinateTask> tags are used to specify properties associated with the coordinate error terms in the IK formulation. A specific coordinate is identified using the name attribute of <IKCoordinateTask>.

Three properties can be specified in a <IKCoordinateTask>: <weight>, <from_file>, and <value>. These properties are not required.

<weight> tag

The <weight> property specifies the weight multiplying the squared-error term for that coordinate. These weights are the ω_i's appearing in the formula given in How Inverse Kinematics Works. They tell the IK solver how closely it should try to match a given coordinate to its experimental value: the larger the weight, the closer the match should be.

Recall from How Inverse Kinematics Works that there are two types of coordinates: prescribed and unprescribed. If the OpenSim model specifies a coordinate to be locked (the <IKCoordinateTask> has <locked> set to true), then it is a prescribed coordinate. The lock symbol in the Coordinates Window will also be in the locked position for this coordinate. Prescribed coordinates will be assigned an exact value and will not be solved for by IK. Thus, the <weight> property has no effect on prescribed coordinates; it is only relevant for unprescribed coordinates.

For an unprescribed coordinate, if <weight> is not specified or if its <IKCoordinateTask> is omitted altogether, the weight for that coordinate is assumed to be zero, meaning that IK will not attempt to match that coordinate to any particular value.

Specify experimental values to be matched

For both prescribed coordinates and unprescribed coordinates with nonzero weights, the experimental value to be matched needs to be specified. One way to do this is to specify a .mot file using the <from_file> and </from_file> tags. If <from_file> is set to true, then the experimental coordinate values for that coordinate come from the .mot file specified by the <coordinate_file> property in the Example IK Setup File. 

If <from_file> is set to false or is not specified, then a constant experimental value is used instead of the time-varying trajectory from a file. This constant value comes from:

• The <value> property of the <IKCoordinateTask>, or if that's not specified then
• The <value> property of the <SimmCoordinate> in the OpenSim .osim model, or if that's not specified then
• The <default_value> property of the <SimmCoordinate> in the OpenSim .osim model.

In the Example IK Task File, the subtalar and mtp angles are locked (prescribed) in the model file. This is indicated in the Coordinates Window (the lock symbol is in the locked position). So <value> is used to specify that they should be locked at 0 radians. A <weight> is not needed since these are prescribed coordinates and will be set to 0 exactly. Note, too, if the coordinate default was set to 0˚, you could have relied on the default behavior and omitted the <IKCoordinateTask> for the subtalar and mtp angles.