Description

MocoTrack

This tool constructs problems in which state and/or marker trajectory data are tracked while solving for model kinematics and actuator controls.

"Tracking" refers to cost terms that minimize the error between provided reference data and the associated model quantities (joint angles, joint velocities, marker positions, etc).

State and marker tracking

State reference data (joint angles and velocities), marker reference data (x/y/z marker motion capture trajectories), or both may be provided via the states_reference and markers_reference properties. For each set of reference data provided, a tracking cost term is added to the internal MocoProblem.

setMarkersReference() only accepts a scalar TimeSeriesTable (either directly or via a TableProcessor) containing x/y/x marker position values. A TimeSeriesTableVec3 of markers is not accepted, but you may use the flatten() method to convert to a scalar TimeSeriesTable:

MocoTrack track;
TimeSeriesTableVec3 markers = TRCFileAdapter("marker_trajectories.trc");
TimeSeriesTable markersFlat(markers.flatten());
track.setMarkersReference(TableProcessor(markersFlat));

If you wish to set the markers reference directly from a TRC file, use setMarkersReferenceFromTRC().

The states_global_tracking_weight and markers_global_tracking_weight properties apply a cost function weight to all tracking error associated provided reference data. The states_weight_set and markers_weight_set properties give you finer control over the tracking costs, letting you set weights for individual reference data tracking errors.

Control effort minimization

By default, a MocoControlCost term is added to the underlying problem with a weight of 0.001. Control effort terms often help smooth the problem solution controls, and minimally affect the states tracking solution with a sufficiently low weight. Use the minimize_control_effort and control_effort_weight properties to customize these settings.

Problem configuration options

A time range that is compatible with all reference data may be provided. If no time range is set, the widest time range that is compatible will all reference data will be used.

If you would like to track joint velocities but only have joint angles in your states reference, enable the track_reference_position_derivatives property. When enabled, the provided position-level states reference data will be splined in order to compute derivatives. If some velocity-level information exists in the reference, this option will fill in the missing data with position derivatives and leave the existing velocity data intact. This is not enabled by default, but is recommended for improving tracking performance and reducing convergence times.

Since the data in the provided references may be altered by TableProcessor operations or appended to by track_reference_position_derivatives, the tracked data is printed to file in addition to the problem solution. The tracked data files have the following format "<tool_name>_tracked_<data_type>.sto" (e.g. "MocoTool_tracked_states.sto").

Default solver settings

solver: MocoCasADiSolver
multibody_dynamics_mode: explicit
transcription_scheme: Hermite-Simpson
optim_convergence_tolerance: 1e-2
optim_constraint_tolerance: 1e-2
optim_sparsity_detection: random
optim_finite_difference_scheme: 'forward'

Basic example

Construct a tracking problem by setting property values and calling solve():

MocoTrack track;
track.setName("states_tracking_with_reserves");
track.setModel(ModelProcessor("model_file.xml") |
               ModOpAddExternalLoads() |
               ModOpAddReserves(1000));
track.setStatesReference("states_reference_file.sto");
track.set_track_reference_position_derivatives(true);
track.set_control_effort_weight(0.1);
MocoSolution solution = track.solve();

Customizing a tracking problem

If you wish to further customize the underlying MocoProblem before solving, instead of calling solve(), call initialize() which returns a pre-configured MocoStudy object:

MocoTrack track;
track.setName("track_and_minimize_hip_compressive_force");
track.setModel(ModelProcessor("model_file.xml") |
               ModOpAddExternalLoads());
track.setStatesReference("states_reference_file.sto");
MocoStudy study = track.initialize();
auto& problem = study.updProblem();
auto* hipForceCost = problem.addGoal<MocoJointReactionCost>("hip_force");
hipForceCost->set_weight(10);
hipForceCost->setJointPath("/jointset/hip_r");
hipForceCost->setReactionMeasures({"force-y"});
auto& solver = study.updSolver<MocoCasADiSolver>();
solver.set_multibody_dynamics_mode("implicit");
MocoSolution solution = study.solve();

Note: This class is still under active development and should be used with caution.

Examples:: example2DWalking.cpp, and exampleMocoTrack.cpp.

Inheritance diagram for OpenSim::MocoTrack:

#include <Moco/Moco/MocoTrack.h>

Public Member Functions
	OpenSim_DECLARE_PROPERTY (states_reference, TableProcessor, "States reference data to be tracked. If provided, a " "MocoStateTrackingGoal term is created and added to the internal " "MocoProblem. ")

	OpenSim_DECLARE_PROPERTY (states_global_tracking_weight, double, "The weight for the MocoStateTrackingGoal that applies to tracking " "errors for all states in the reference.")

	OpenSim_DECLARE_PROPERTY (states_weight_set, MocoWeightSet, "A set of tracking weights for individual state variables. The " "weight names should match the names of the column labels in the " "file associated with the 'states_reference' property.")

	OpenSim_DECLARE_PROPERTY (scale_state_weights_with_range, bool, "Use the range, or the distance between the maximum and minimum " "value, of each reference quantity to scale the weight " "for the associated tracking error in the cost. The scale is " "computed by the inverse of the range, so a reference quantity " "that changes less across the trajectory has a larger weight. ")

	OpenSim_DECLARE_PROPERTY (track_reference_position_derivatives, bool, "Option to track the derivative of position-level state reference " "data if no velocity-level state reference data was included in " "the `states_reference`. If velocity-reference reference data was " "provided for some coordinates but not others, this option will " "only " "apply to the coordinates without speed reference data. " "(default: false)")

	OpenSim_DECLARE_PROPERTY (markers_reference, TableProcessor, "Motion capture marker reference data to be tracked. The columns " "in " "the table should correspond to scalar x/y/z marker position " "values and the columns labels should have consistent suffixes " "appended to the model marker names. If provided, a " "MocoMarkerTrackingGoal term is created and added to the internal " "MocoProblem.")

	OpenSim_DECLARE_PROPERTY (markers_global_tracking_weight, double, "The weight for the MocoMarkerTrackingGoal that applies to " "tracking " "errors for all markers in the reference.")

	OpenSim_DECLARE_PROPERTY (markers_weight_set, MocoWeightSet, "A set of tracking weights for individual marker positions. The " "weight names should match the marker names in the " "file associated with the 'markers_reference' property.")

	OpenSim_DECLARE_PROPERTY (allow_unused_references, bool, "Allow references to contain data not associated with any " "components " "in the model (such data would be ignored). Default: false.")

	OpenSim_DECLARE_PROPERTY (guess_file, std::string, "Path to a STO file containing a guess for the problem. The path " "can " "be absolute or relative to the setup file. If no file is " "provided, " "then a guess constructed from the variable bounds midpoints will " "be " "used.")

	OpenSim_DECLARE_PROPERTY (apply_tracked_states_to_guess, bool, "If a `states_reference` has been provided, use this setting to " "replace the states in the guess with the states reference data. " "This " "will override any guess information provided via `guess_file`.")

	OpenSim_DECLARE_PROPERTY (minimize_control_effort, bool, "Whether or not to minimize actuator control effort in the problem." "Default: true.")

	OpenSim_DECLARE_PROPERTY (control_effort_weight, double, "The weight on the control effort minimization cost term, if it " "exists. Default: 0.001")

void	setStatesReference (TableProcessor states)
	Set the states reference TableProcessor. More...

void	setMarkersReference (TableProcessor markers)
	Set the markers reference TableProcessor. More...

void	setMarkersReferenceFromTRC (const std::string &filename, double lowpassFilterFreq=6.0)
	Set the markers reference directly from a TRC file. More...

MocoStudy	initialize ()

MocoSolution	solve (bool visualize=false)

Public Member Functions inherited from OpenSim::MocoTool
	OpenSim_DECLARE_OPTIONAL_PROPERTY (initial_time, double, "The start of the time interval. " "All data must start at or before this time. " "(default: earliest time available in all provided data)")

	OpenSim_DECLARE_OPTIONAL_PROPERTY (final_time, double, "The end of the time interval. " "All data must end at or after this time. " "(default: latest time available in all provided data)")

	OpenSim_DECLARE_PROPERTY (mesh_interval, double, "The time duration of each mesh interval " "(default: 0.020 seconds).")

	OpenSim_DECLARE_PROPERTY (clip_time_range, bool, "Set the time range to be 1e-3 shorter on both ends to leave space " "for finite difference estimates (default: false).")

	OpenSim_DECLARE_PROPERTY (model, ModelProcessor, "The musculoskeletal model to use.")

void	setModel (ModelProcessor model)

Additional Inherited Members
Protected Member Functions inherited from OpenSim::MocoTool
void	updateTimeInfo (const std::string &dataLabel, const double &dataInitial, const double &dataFinal, TimeInfo &info) const
	This function updates a TimeInfo so the initial and final times are within the data times provided. More...

std::string	getFilePath (const std::string &file) const
	Get the canonicalized absolute pathname with respect to the setup file directory from a given pathname which can be relative or absolute. More...

std::string	getDocumentDirectory () const
	Get the (canonicalized) absolute directory containing the file from which this tool was loaded. More...

Member Function Documentation

◆ setMarkersReference()

void OpenSim::MocoTrack::setMarkersReference ( TableProcessor markers )

inline

Set the markers reference TableProcessor.

Note: Overrides any existing TableProcessor for 'markers_reference'.

◆ setMarkersReferenceFromTRC()

void OpenSim::MocoTrack::setMarkersReferenceFromTRC	(	const std::string &	filename,
		double	lowpassFilterFreq = `6.0`
	)

inline

Set the markers reference directly from a TRC file.

By default, the marker data is lowpass filtered with a 6 Hz cutoff frequency, but you may set any frequency using the optional argument. If the markers data is in millimeters (detected via the 'Units' metadata tag), then it is converted to meters.

Note: Overrides any existing TableProcessor for 'markers_reference'.

Examples:: exampleMocoTrack.cpp.

◆ setStatesReference()

void OpenSim::MocoTrack::setStatesReference ( TableProcessor states )

inline

Set the states reference TableProcessor.

Note: Overrides any existing TableProcessor for 'states_reference'.

Examples:: example2DWalking.cpp, and exampleMocoTrack.cpp.

The documentation for this class was generated from the following file:

MocoTrack.h

Description

MocoTrack

State and marker tracking

Control effort minimization

Problem configuration options

Default solver settings

Basic example

Customizing a tracking problem

Public Member Functions

Additional Inherited Members

Member Function Documentation

◆ setMarkersReference()

◆ setMarkersReferenceFromTRC()

◆ setStatesReference()