IK Settings Files and XML Tag Definitions

The topics covered in this section include:

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: 
Example IK Setup File: XML file for an inverse kinematics setup file

<?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>

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>

Example IK Task File: Annotated XML file for an inverse kinematics tasks file

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.