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

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

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, 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 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, 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 debug:

Whether to output debugging info

param smoothing:

Smoothing weight; 0 to disable

param collision_error_weight:

Collision error weight; 0 to disable

param smoothing_weights:

Smoothing weights per model parameter

property collision_error_weight: Collision error weight; 0 to disable

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.convert_locators_to_skinned_locators(character: pymomentum.geometry.Character, max_distance: float = 3.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)

Returns:

New character with converted skinned locators and remaining regular locators

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) → numpy.ndarray[numpy.float32[m, n]]

process markers given character and identity.

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

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