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 trial to be used by the solver.

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

<?xml version="1.0" encoding="UTF-8" ?>
<OpenSimDocument Version="30000">
    <InverseKinemtaticsTool name="subject01">
        <!--Name of the .osim file used to construct a model.-->
        <model_file>subject01_simbody.osim</model_file>
        <!--Specify which optimizer to use (ipopt or cfsqp or jacobian).-->
        <!--Task set used to specify IK weights.-->
        <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>
		</IKTaskSet>
		<!--Parameters for solving the IK problem for each trial. Each trial
	    should get a seperate SimmIKTril block.-->
        <!--TRC file (.trc) containing the time history of experimental marker
				    positions.-->
        <marker_file>subject01_walk1.trc</marker_file>
        <!--Name of file containing the joint angles used to set the initial
				    configuration of the model -->
        <coordinate_file></coordinate_file>
        <!--Time range over which the IK problem is solved.-->
        <time_range>0.4 1.60</time_range>
        <!--Name of the motion file (.mot) to which the results should be written.-->
        <output_motion_file>subject01_walk1_ik.mot</output_motion_file>
        <!--A positive scalar that is used to weight the importance of satisfying 
			constraints.A weighting of 'Infinity' or if it is unassigned results in 
			the constraints being strictly enforced.-->
        <constraint_weight>20.0</constraint_weight>
        <!--The accuracy of the solution in absolute terms. I.e. the number of significant
			digits to which the solution can be trusted.-->
        <accuracy>1e-5</accuracy>
    </InverseKinemtaticsTool>
</OpenSimDocument>

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. More details for specifying the IK tasks are presented below.

In OpenSim version 3.0 and earlier, the IK tasks could be specified in a separate file. In OpenSim version 3.1, a bug prevented loading IK tasks stored in a separate file. As of OpenSIm 3.2, you can load an old version IK setup file that has a separate tasks file. But when you save this setup, it will be merged into a single file. Moving forward, users should use a single IK setup file (i.e., no separate tasks file).

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

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 Setup File above, 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.