pymomentum.marker_tracking

Module for exposing the C++ APIs of the marker tracking pipeline

class pymomentum.marker_tracking.BaseConfig

Bases: pybind11_object

Represents base config class

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pymomentum.marker_tracking.BaseConfig) -> None
__init__(self: pymomentum.marker_tracking.BaseConfig, min_vis_percent: float = 0.0, loss_alpha: float = 2.0, max_iter: int = 30, regularization: float = 0.05000000074505806, debug: bool = False) -> None

Create a BaseConfig with specified parameters.

param min_vis_percent:

Minimum percentage of visible markers to be used

param loss_alpha:

Parameter to control the loss function

param max_iter:

Maximum number of iterations

param debug:

Whether to output debugging info

property debug: Whether to output debugging info

property loss_alpha: Parameter to control the loss function

property max_iter: Max iterations

property min_vis_percent: Minimum percentage of visible markers to be used

class pymomentum.marker_tracking.CalibrationConfig

Bases: BaseConfig

Config for the body scale calibration step

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pymomentum.marker_tracking.CalibrationConfig) -> None
__init__(self: pymomentum.marker_tracking.CalibrationConfig, min_vis_percent: float = 0.0, loss_alpha: float = 2.0, max_iter: int = 30, regularization: float = 0.05000000074505806, debug: bool = False, calib_frames: int = 100, major_iter: int = 3, global_scale_only: bool = False, locators_only: bool = False, greedy_sampling: int = 0, enforce_floor_in_first_frame: bool = False, first_frame_pose_constraint_set: str = ‘’, calib_shape: bool = False, target_height_cm: float = 0.0, mesh_constraint_weight: float = 1.0) -> None

Create a CalibrationConfig with specified parameters.

param min_vis_percent:

Minimum percentage of visible markers to be used

param loss_alpha:

Parameter to control the loss function

param max_iter:

Maximum number of iterations

param debug:

Whether to output debugging info

param calib_frames:

Number of frames used for model calibration

param major_iter:

Number of calibration loops to run

param global_scale_only:

Calibrate only the global scale and not all proportions

param locators_only:

Calibrate only the locator offsets

param greedy_sampling:

Enable greedy frame sampling with the given stride

param enforce_floor_in_first_frame:

Force floor contact in first frame

param first_frame_pose_constraint_set:

Name of pose constraint set to use in first frame

param target_height_cm:

Target height for character in cm. Defaults to 0 (unspecified).

param mesh_constraint_weight:

Weight multiplier for mesh surface constraints during calibration.

property calib_frames: Number of frames used for model calibration

property calib_shape: Calibrate shape parameters

property enforce_floor_in_first_frame: Force floor contact in first frame

property first_frame_pose_constraint_set: Name of pose constraint set to use in first frame

property global_scale_only: Calibrate only the global scale and not all proportions

property greedy_sampling: Enable greedy frame sampling with the given stride

property locators_only: Calibrate only the locator offsets

property major_iter: Number of calibration loops to run

property mesh_constraint_weight: Weight multiplier for mesh surface constraints during calibration

property target_height_cm: Target height for the character in cm (0 means no target height specified)

class pymomentum.marker_tracking.GloveConfig

Bases: pybind11_object

Configuration for glove constraints in marker tracking.

Controls how data glove observations are integrated into the marker tracking solver, including constraint weights and which wrist joints to attach glove bones to.

__init__(self: pymomentum.marker_tracking.GloveConfig) → None

property orientation_weight: Weight for orientation constraints between glove and finger joints.

property position_weight: Weight for position constraints between glove and finger joints.

property wrist_joint_names: Names of the left and right wrist joints in the skeleton.

class pymomentum.marker_tracking.GloveSensorObservation

Bases: pybind11_object

Single glove sensor observation for one finger joint in one frame.

Represents a measurement from a data glove sensor, providing position and orientation of a finger joint in the glove’s local coordinate frame.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pymomentum.marker_tracking.GloveSensorObservation) -> None
__init__(self: pymomentum.marker_tracking.GloveSensorObservation, joint_name: str, position: numpy.ndarray[numpy.float32[3, 1]] = array([0., 0., 0.], dtype=float32), orientation: numpy.ndarray[4] = array([0., 0., 0., 1.], dtype=float32), valid: bool = True) -> None

Create a GloveSensorObservation with specified parameters.

Parameters:

joint_name – Skeleton joint name (e.g. “b_l_thumb0”).
position – Position in glove-local frame as a 3D vector.
orientation – Orientation in glove-local frame as a quaternion [x, y, z, w].
valid – Whether this observation is valid (False if sensor data is missing/occluded).

property joint_name: Skeleton joint name (e.g. “b_l_thumb0”).

property orientation: Orientation in glove-local frame as a quaternion [x, y, z, w].

property position: Position in glove-local frame as a 3D vector.

property valid: Whether this observation is valid (False if sensor data is missing/occluded).

class pymomentum.marker_tracking.ModelOptions

Bases: pybind11_object

Model options to specify the template model, parameter transform and locator mappings

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pymomentum.marker_tracking.ModelOptions) -> None
__init__(self: pymomentum.marker_tracking.ModelOptions, model: str, parameters: str, locators: str) -> None

Create ModelOptions with specified file paths.

param model:

Path to template model file with locators e.g. character.glb

param parameters:

Path of parameter transform model file e.g. character.model

param locators:

Path to locator mapping file e.g. character.locators

property locators: Path to locator mapping file e.g. character.locators

property model: Path to template model file with locators e.g. character.glb

property parameters: Path of parameter transform model file e.g. character.model

class pymomentum.marker_tracking.RefineConfig

Bases: TrackingConfig

Config for refining a tracked motion.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pymomentum.marker_tracking.RefineConfig) -> None
__init__(self: pymomentum.marker_tracking.RefineConfig, min_vis_percent: float = 0.0, loss_alpha: float = 2.0, max_iter: int = 30, regularization: float = 0.05000000074505806, debug: bool = False, smoothing: float = 0.0, collision_error_weight: float = 0.0, marker_weight: float = 1.0, smoothing_weights: numpy.ndarray[numpy.float32[m, 1]] = array([], dtype=float32), regularizer: float = 0.0, calib_id: bool = False, calib_locators: bool = False) -> None

Create a RefineConfig with specified parameters.

param min_vis_percent:

Minimum percentage of visible markers to be used

param loss_alpha:

Parameter to control the loss function

param max_iter:

Maximum number of iterations

param debug:

Whether to output debugging info

param smoothing:

Smoothing weight; 0 to disable

param collision_error_weight:

Collision error weight; 0 to disable

param marker_weight:

Multiplier for marker position constraint weight; 0 to disable markers

param smoothing_weights:

Smoothing weights per model parameter

param regularizer:

Regularize the time-invariant parameters to prevent large changes

param calib_id:

Calibrate identity parameters

param calib_locators:

Calibrate locator offsets

property calib_id: Calibrate identity parameters; default to False.

property calib_locators: Calibrate locator offsets; default to False.

property regularizer: Regularize the time-invariant parameters to prevent large changes.

class pymomentum.marker_tracking.TrackingConfig

Bases: BaseConfig

Config for the tracking optimization step

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pymomentum.marker_tracking.TrackingConfig) -> None
__init__(self: pymomentum.marker_tracking.TrackingConfig, min_vis_percent: float = 0.0, loss_alpha: float = 2.0, max_iter: int = 30, regularization: float = 0.05000000074505806, debug: bool = False, smoothing: float = 0.0, collision_error_weight: float = 0.0, marker_weight: float = 1.0, smoothing_weights: numpy.ndarray[numpy.float32[m, 1]] = array([], dtype=float32)) -> None

Create a TrackingConfig with specified parameters.

param min_vis_percent:

Minimum percentage of visible markers to be used

param loss_alpha:

Parameter to control the loss function

param max_iter:

Maximum number of iterations

param regularization:

Regularization parameter (lambda) for solver

param debug:

Whether to output debugging info

param smoothing:

Smoothing weight; 0 to disable

param collision_error_weight:

Collision error weight; 0 to disable

param marker_weight:

Multiplier for marker position constraint weight; 0 to disable markers

param smoothing_weights:

Smoothing weights per model parameter

property active_params

Optional boolean numpy array to restrict which parameters are optimized during tracking.

When set, this is ANDed with the internally-computed pose parameters (which already exclude identity and locator parameters). Use the character’s ParameterTransform to construct a meaningful set, e.g. to exclude finger DOFs:

pt = character.parameter_transform
active = pt.pose_parameters.copy()
active &= ~pt.parameter_sets.get("fingers", np.zeros_like(active))
tracking_config.active_params = active

Set to None (default) to use the solver’s default parameter set.

property collision_error_weight: Collision error weight; 0 to disable

property marker_weight: Multiplier for marker position constraint weight; 0 to disable markers

property mesh_constraint_weight: Weight multiplier for mesh surface constraints

property smoothing: Smoothing weight; 0 to disable

property smoothing_weights: Smoothing weights per model parameter. The size of this vector should be equal to number of model parameters and this overrides the value specific in smoothing

pymomentum.marker_tracking.calibrate_markers(character: pymomentum.geometry.Character, identity: numpy.ndarray[numpy.float32[m, 1]], marker_data: list[list[pymomentum.geometry.Marker]], calibration_config: pymomentum.marker_tracking.CalibrationConfig, first_frame: int = 0, max_frames: int = 0, left_glove_data: list[list[pymomentum.marker_tracking.GloveSensorObservation]] = [], right_glove_data: list[list[pymomentum.marker_tracking.GloveSensorObservation]] = [], glove_config: pymomentum.marker_tracking.GloveConfig | None = None) → numpy.ndarray[numpy.float32[m, 1]]

Calibrate a character model using marker data without running full tracking.

This function performs only the calibration step (scaling, locator offsets, and optionally shape parameters) without running per-frame tracking on all frames. This is useful when you want to calibrate on a ROM (range of motion) sequence but don’t need the tracked motion for that sequence.

The calibration modifies the character in-place (updating locators if configured) and returns the calibrated identity parameters. These can then be used with process_markers() or track_poses() for tracking other sequences.

When glove data is provided via left_glove_data / right_glove_data and a GloveConfig, the solver adds glove-to-finger constraints during calibration. This improves locator calibration by providing additional constraint information from the data glove sensors.

Parameters:

character – Character to be calibrated. Will be modified in-place if locator calibration is enabled.
identity – Identity parameters, pass in empty array for default identity.
marker_data – A list of marker data for each frame (from ROM/calibration sequence).
calibration_config – Calibration config specifying number of frames, iterations, etc.
first_frame – First frame to be used for calibration.
max_frames – Max number of frames to be used for calibration (0 for all).
left_glove_data – Per-frame glove sensor observations for the left hand. Each element is a list of GloveSensorObservation for that frame.
right_glove_data – Per-frame glove sensor observations for the right hand.
glove_config – Optional GloveConfig controlling constraint weights and wrist joint names. Must be provided if glove data is non-empty.

Returns:

Calibrated identity parameters (scaling parameters).

pymomentum.marker_tracking.convert_locators_to_skinned_locators(character: pymomentum.geometry.Character, max_distance: float = 3.0, min_skin_weight: float = 0.029999999329447746, verbose: bool = False, marker_diameter: float = 0.0) → pymomentum.geometry.Character

Convert regular locators to skinned locators based on mesh proximity.

This function converts locators attached to specific joints into skinned locators that are weighted across multiple joints based on the underlying mesh skin weights. For each locator, it:

Computes the locator’s world space position using the rest skeleton state
Finds the closest point on the character’s mesh surface that is skinned to the same bone as the locator (this is to avoid skinning the locator to the wrong bone)
If the distance is within max_distance, converts the locator to a skinned locator with bone weights interpolated from the closest mesh triangle
Otherwise, keeps the original locator unchanged

The resulting skinned locators maintain the same world space position but are now influenced by multiple joints through skin weights.

Parameters:

character – Character with mesh, skin weights, and locators to convert
max_distance – Maximum distance from mesh surface to convert a locator (default: 3.0)
min_skin_weight – Minimum skin weight threshold for considering a mesh triangle as belonging to the same bone as the locator (default: 0.03)
verbose – If True, print diagnostic messages about locators that could not be converted (default: False)
marker_diameter – Marker diameter in centimeters. When positive, the skinned locator position is offset toward the mesh surface by half this value to account for the physical marker sitting on top of the skin (default: 0.0)

Returns:

New character with converted skinned locators and remaining regular locators

pymomentum.marker_tracking.convert_skinned_locators_to_locators(character: pymomentum.geometry.Character) → pymomentum.geometry.Character

Convert skinned locators to regular locators by selecting the bone with highest weight.

This function is useful when exporting to file formats that don’t support skinned locators (e.g., Maya). Each skinned locator is converted to a regular locator by:

Finding the bone with the highest skin weight from the skinned locator’s bone influences
Transforming the locator’s position from rest pose space to the local coordinate space of the selected bone
Creating a regular locator attached to that bone with the computed offset

The resulting locators can be exported to formats like Maya that only support single-parent attachments. Any existing regular locators in the character are preserved.

Parameters:: character – Character with skinned locators to convert
Returns:: New character with skinned locators converted to regular locators

pymomentum.marker_tracking.get_locator_error(marker_data: list[list[pymomentum.geometry.Marker]], motion: numpy.ndarray[numpy.float32[m, n]], character: pymomentum.geometry.Character) → tuple[float, float]

Compute average and maximum marker tracking errors across all frames.

This is a utility function for evaluating tracking quality by measuring the Euclidean distance between observed marker positions and their corresponding locator positions on the character. It provides both average error per frame and the maximum error encountered across all markers and frames.

Parameters:

marker_data – List of marker observations for each frame. Each frame contains a list of Marker objects with position and occlusion information.
motion – Solved motion parameters matrix. Can be in Python layout (frames, params) or C++ layout (params, frames) - the function handles both.
character – Character model with locators that correspond to the markers.

Returns:

Tuple of (average_error, max_error) in world units (typically meters or cm depending on your character scale). average_error is the mean error per frame across all frames, max_error is the single largest marker error found.

pymomentum.marker_tracking.process_marker_file(input_marker_file: str, output_file: str, tracking_config: pymomentum.marker_tracking.TrackingConfig, calibration_config: pymomentum.marker_tracking.CalibrationConfig, model_options: pymomentum.marker_tracking.ModelOptions, calibrate: bool, first_frame: int = 0, max_frames: int = 0) → None

pymomentum.marker_tracking.process_markers(character: pymomentum.geometry.Character, identity: numpy.ndarray[numpy.float32[m, 1]], marker_data: list[list[pymomentum.geometry.Marker]], tracking_config: pymomentum.marker_tracking.TrackingConfig, calibration_config: pymomentum.marker_tracking.CalibrationConfig, calibrate: bool = True, first_frame: int = 0, max_frames: int = 0, left_glove_data: list[list[pymomentum.marker_tracking.GloveSensorObservation]] = [], right_glove_data: list[list[pymomentum.marker_tracking.GloveSensorObservation]] = [], glove_config: pymomentum.marker_tracking.GloveConfig | None = None) → numpy.ndarray[numpy.float32[m, n]]

Process markers given character and identity.

Calibrates the character model (if enabled) and tracks per-frame poses from marker data.

When glove data is provided via left_glove_data / right_glove_data and a GloveConfig, the solver adds glove-to-finger constraints during both calibration and per-frame tracking. This produces more accurate results for characters wearing data gloves alongside optical markers.

Parameters:

character – Character to be used for tracking.
identity – Identity parameters, pass in empty array for default identity.
marker_data – A list of marker data for each frame.
tracking_config – Tracking config to be used for tracking.
calibration_config – Calibration config to be used for calibration.
calibrate – Whether to calibrate the model.
first_frame – First frame to be processed.
max_frames – Max number of frames to be processed.
left_glove_data – Per-frame glove sensor observations for the left hand. Each element is a list of GloveSensorObservation for that frame.
right_glove_data – Per-frame glove sensor observations for the right hand.
glove_config – Optional GloveConfig controlling constraint weights and wrist joint names. Must be provided if glove data is non-empty.

Returns:

Transform parameters for each frame.

pymomentum.marker_tracking.refine_motion(character: pymomentum.geometry.Character, identity: numpy.ndarray[numpy.float32[m, 1]], motion: numpy.ndarray[numpy.float32[m, n]], marker_data: list[list[pymomentum.geometry.Marker]], refine_config: pymomentum.marker_tracking.RefineConfig) → numpy.ndarray[numpy.float32[m, n]]

pymomentum.marker_tracking.save_motion(out_file: str, character: pymomentum.geometry.Character, identity: numpy.ndarray[numpy.float32[m, 1]], motion: numpy.ndarray[numpy.float32[m, n]], marker_data: list[list[pymomentum.geometry.Marker]], fps: float, save_marker_mesh: bool = True) → None