pymomentum.solver2

Inverse kinematics and other optimizations for momentum models.

class pymomentum.solver2.AimData

Bases: pybind11_object

property global_target: The global aim target

property local_dir: The direction of the local ray

property local_point: The origin of the local ray

property parent: The parent joint index

property weight: The weight of the constraint

class pymomentum.solver2.AimDirErrorFunction

Bases: SkeletonErrorFunction

The AimDirErrorFunction minimizes the element-wise difference between a ray (origin, direction) defined in joint-local space and the normalized vector connecting the ray origin to the world-space target point. If the vector has near-zero length, the residual is set to zero to avoid divide-by-zero.

add_constraint(self: pymomentum.solver2.AimDirErrorFunction, local_point: numpy.ndarray[numpy.float32[3, 1]], local_dir: numpy.ndarray[numpy.float32[3, 1]], global_target: numpy.ndarray[numpy.float32[3, 1]], parent: int, weight: float = 1.0, name: str = '') → None

Adds an aim constraint to the error function.

param local_point:

The origin of the local ray.

param local_dir:

The direction of the local ray.

param global_target:

The global aim target.

param parent_index:

The index of the parent joint.

param weight:

The weight of the constraint.

param name:

The name of the constraint (for debugging).

add_constraints(self: pymomentum.solver2.AimDirErrorFunction, local_point: numpy.ndarray[numpy.float32], local_dir: numpy.ndarray[numpy.float32], global_target: numpy.ndarray[numpy.float32], parent_index: numpy.ndarray[numpy.int32], weight: numpy.ndarray[numpy.float32] | None, name: list[str] | None = None) → None

Adds multiple aim constraints to the error function.

param local_point:

A numpy array of shape (n, 3) for the origins of the local rays.

param local_dir:

A numpy array of shape (n, 3) for the directions of the local rays.

param global_target:

A numpy array of shape (n, 3) for the global aim targets.

param parent_index:

A numpy array of size n for the indices of the parent joints.

param weight:

A numpy array of size n for the weights of the constraints.

param name:

An optional list of names for the constraints (for debugging).

property constraints: Returns the list of aim constraints.

class pymomentum.solver2.AimDistErrorFunction

Bases: SkeletonErrorFunction

The AimDistErrorFunction minimizes the distance between a ray (origin, direction) defined in joint-local space and the world-space target point. The residual is defined as the distance between the tartet position and its projection onto the ray. Note that the ray is only defined for positive t values, meaning that if the target point is _behind_ the ray origin, its projection will be at the ray origin where t=0.

add_constraint(self: pymomentum.solver2.AimDistErrorFunction, local_point: numpy.ndarray[numpy.float32[3, 1]], local_dir: numpy.ndarray[numpy.float32[3, 1]], global_target: numpy.ndarray[numpy.float32[3, 1]], parent: int, weight: float = 1.0, name: str = '') → None

Adds an aim constraint to the error function.

param local_point:

The origin of the local ray.

param local_dir:

The direction of the local ray.

param global_target:

The global aim target.

param parent_index:

The index of the parent joint.

param weight:

The weight of the constraint.

param name:

The name of the constraint (for debugging).

add_constraints(self: pymomentum.solver2.AimDistErrorFunction, local_point: numpy.ndarray[numpy.float32], local_dir: numpy.ndarray[numpy.float32], global_target: numpy.ndarray[numpy.float32], parent_index: numpy.ndarray[numpy.int32], weight: numpy.ndarray[numpy.float32] | None, name: list[str] | None = None) → None

Adds multiple aim constraints to the error function.

param local_point:

A numpy array of shape (n, 3) for the origins of the local rays.

param local_dir:

A numpy array of shape (n, 3) for the directions of the local rays.

param global_target:

A numpy array of shape (n, 3) for the global aim targets.

param parent_index:

A numpy array of size n for the indices of the parent joints.

param weight:

A numpy array of size n for the weights of the constraints.

param name:

An optional list of names for the constraints (for debugging).

property constraints: Returns the list of aim constraints.

class pymomentum.solver2.CollisionErrorFunction

Bases: SkeletonErrorFunction

get_collision_pairs(self: pymomentum.solver2.CollisionErrorFunction) → numpy.ndarray[numpy.float32]: Returns the pairs of colliding elements.

class pymomentum.solver2.DistanceData

Bases: pybind11_object

property offset: The offset in parent space

property origin: The origin point in world space

property parent: The parent joint index

property target: The target distance

property weight: The weight of the constraint

class pymomentum.solver2.DistanceErrorFunction

Bases: SkeletonErrorFunction

The DistanceErrorFunction computes the squared difference between the distance from a point to an origin and a target distance. The constraint is defined as ||(p_joint - origin)^2 - target||^2.

add_constraint(self: pymomentum.solver2.DistanceErrorFunction, origin: numpy.ndarray[numpy.float32[3, 1]], target: float, parent: int, offset: numpy.ndarray[numpy.float32[3, 1]], weight: float = 1.0) → None

Adds a distance constraint to the error function.

param origin:

The origin point in world space.

param target:

The target distance in world space.

param parent:

The index of the parent joint.

param offset:

The offset from the parent joint in local space.

param weight:

The weight of the constraint.

add_constraints(self: pymomentum.solver2.DistanceErrorFunction, origin: numpy.ndarray[numpy.float32], target: numpy.ndarray[numpy.float32], parent: numpy.ndarray[numpy.int32], offset: numpy.ndarray[numpy.float32], weight: numpy.ndarray[numpy.float32] | None = None) → None

Adds multiple distance constraints to the error function.

param origin:

A numpy array of shape (n, 3) for the origin points in world space.

param target:

A numpy array of size n for the target distances in world space.

param parent:

A numpy array of size n for the indices of the parent joints.

param offset:

A numpy array of shape (n, 3) for the offsets from the parent joints in local space.

param weight:

A numpy array of size n for the weights of the constraints.

clear_constraints(self: pymomentum.solver2.DistanceErrorFunction) → None: Clears all distance constraints from the error function.

property constraints: Returns the list of distance constraints.

empty(self: pymomentum.solver2.DistanceErrorFunction) → bool: Returns true if there are no constraints.

num_constraints(self: pymomentum.solver2.DistanceErrorFunction) → int: Returns the number of constraints.

class pymomentum.solver2.FixedAxisAngleErrorFunction

Bases: SkeletonErrorFunction

Error function that minimizes the difference between a local axis (in joint-local space) and a global axis using the angle between the vectors.

add_constraint(self: pymomentum.solver2.FixedAxisDiffErrorFunction, local_axis: numpy.ndarray[numpy.float32[3, 1]], global_axis: numpy.ndarray[numpy.float32[3, 1]], parent: int, weight: float = 1.0, name: str = '') → None

Adds a fixed axis constraint to the error function.

param local_axis:

The axis in the parent’s coordinate frame.

param global_axis:

The target axis in the global frame.

param parent_index:

The index of the parent joint.

param weight:

The weight of the constraint.

param name:

The name of the constraint (for debugging).

add_constraints(self: pymomentum.solver2.FixedAxisAngleErrorFunction, local_axis: numpy.ndarray[numpy.float32], global_axis: numpy.ndarray[numpy.float32], parent_index: numpy.ndarray[numpy.int32], weight: numpy.ndarray[numpy.float32] | None, name: list[str] | None = None) → None

Adds multiple fixed axis constraints to the error function.

param local_axis:

A numpy array of shape (n, 3) for the axes in the parent’s coordinate frame.

param global_axis:

A numpy array of shape (n, 3) for the target axes in the global frame.

param parent_index:

A numpy array of size n for the indices of the parent joints.

param weight:

A numpy array of size n for the weights of the constraints.

param name:

An optional list of names for the constraints (for debugging).

property constraints: Returns the list of fixed axis constraints.

class pymomentum.solver2.FixedAxisCosErrorFunction

Bases: SkeletonErrorFunction

Error function that minimizes the difference between a local axis (in joint-local space) and a global axis using the cosine of the angle between the vectors (which is the same as the dot product of the vectors).

add_constraint(self: pymomentum.solver2.FixedAxisDiffErrorFunction, local_axis: numpy.ndarray[numpy.float32[3, 1]], global_axis: numpy.ndarray[numpy.float32[3, 1]], parent: int, weight: float = 1.0, name: str = '') → None

Adds a fixed axis constraint to the error function.

param local_axis:

The axis in the parent’s coordinate frame.

param global_axis:

The target axis in the global frame.

param parent_index:

The index of the parent joint.

param weight:

The weight of the constraint.

param name:

The name of the constraint (for debugging).

add_constraints(self: pymomentum.solver2.FixedAxisCosErrorFunction, local_axis: numpy.ndarray[numpy.float32], global_axis: numpy.ndarray[numpy.float32], parent_index: numpy.ndarray[numpy.int32], weight: numpy.ndarray[numpy.float32] | None, name: list[str] | None = None) → None

Adds multiple fixed axis constraints to the error function.

param local_axis:

A numpy array of shape (n, 3) for the axes in the parent’s coordinate frame.

param global_axis:

A numpy array of shape (n, 3) for the target axes in the global frame.

param parent_index:

A numpy array of size n for the indices of the parent joints.

param weight:

A numpy array of size n for the weights of the constraints.

param name:

An optional list of names for the constraints (for debugging).

property constraints: Returns the list of fixed axis constraints.

class pymomentum.solver2.FixedAxisData

Bases: pybind11_object

property global_axis: The global axis

property local_axis: The local axis in parent space

property parent: The parent joint index

property weight: The weight of the constraint

class pymomentum.solver2.FixedAxisDiffErrorFunction

Bases: SkeletonErrorFunction

Error function that minimizes the difference between a local axis (in joint-local space) and a global axis using element-wise differences.

add_constraint(self: pymomentum.solver2.FixedAxisDiffErrorFunction, local_axis: numpy.ndarray[numpy.float32[3, 1]], global_axis: numpy.ndarray[numpy.float32[3, 1]], parent: int, weight: float = 1.0, name: str = '') → None

Adds a fixed axis constraint to the error function.

param local_axis:

The axis in the parent’s coordinate frame.

param global_axis:

The target axis in the global frame.

param parent_index:

The index of the parent joint.

param weight:

The weight of the constraint.

param name:

The name of the constraint (for debugging).

add_constraints(self: pymomentum.solver2.FixedAxisDiffErrorFunction, local_axis: numpy.ndarray[numpy.float32], global_axis: numpy.ndarray[numpy.float32], parent_index: numpy.ndarray[numpy.int32], weight: numpy.ndarray[numpy.float32] | None, name: list[str] | None = None) → None

Adds multiple fixed axis constraints to the error function.

param local_axis:

A numpy array of shape (n, 3) for the axes in the parent’s coordinate frame.

param global_axis:

A numpy array of shape (n, 3) for the target axes in the global frame.

param parent_index:

A numpy array of size n for the indices of the parent joints.

param weight:

A numpy array of size n for the weights of the constraints.

param name:

An optional list of names for the constraints (for debugging).

property constraints: Returns the list of fixed axis constraints.

class pymomentum.solver2.GaussNewtonSolver

Bases: Solver

Basic 2nd-order Gauss-Newton solver

class pymomentum.solver2.GaussNewtonSolverOptions

Bases: SolverOptions

property direct_sparse_jtj: Directly computes sparse JᵀJ without dense intermediate representation

property do_line_search: Enables backtracking line search to ensure error reduction at each step

property regularization: Damping parameter added to Hessian diagonal for numerical stability

property sparse_matrix_threshold: Parameter count threshold for switching to sparse matrix operations

property use_block_jtj: Uses pre-computed JᵀJ and JᵀR from the solver function

class pymomentum.solver2.GaussNewtonSolverQR

Bases: Solver

Gauss-Newton solver with QR decomposition

class pymomentum.solver2.GaussNewtonSolverQROptions

Bases: SolverOptions

Options specific to the Gauss-Newton QR solver

property do_line_search: Flag to enable line search during optimization.

property regularization: Regularization parameter for QR decomposition.

class pymomentum.solver2.LimitErrorFunction

Bases: SkeletonErrorFunction

A skeleton error function that penalizes joints that exceed their limits.

class pymomentum.solver2.ModelParametersErrorFunction

Bases: SkeletonErrorFunction

A skeleton error function that penalizes the difference between the target model parameters and the current model parameters.

set_target_parameters(self: pymomentum.solver2.ModelParametersErrorFunction, target_parameters: numpy.ndarray[numpy.float32], weights: numpy.ndarray[numpy.float32] | None = None) → None

Sets the target model parameters and optional weights.

Parameters:

target_parameters – The target model parameters to achieve.
weights – Optional weights for each parameter, defaulting to 1 if not provided.

class pymomentum.solver2.ModelParametersSequenceErrorFunction: Bases: SequenceErrorFunction

class pymomentum.solver2.NormalData

Bases: pybind11_object

property global_point: The global point

property local_normal: The local normal in parent space

property local_point: The local point in parent space

property parent: The parent joint index

property weight: The weight of the constraint

class pymomentum.solver2.NormalErrorFunction

Bases: SkeletonErrorFunction

The NormalErrorFunction computes a “point-to-plane” (signed) distance from a target point to the plane defined by a local point and a local normal vector.

add_constraint(self: pymomentum.solver2.NormalErrorFunction, local_normal: numpy.ndarray[numpy.float32[3, 1]], global_point: numpy.ndarray[numpy.float32[3, 1]], parent: int, local_point: numpy.ndarray[numpy.float32[3, 1]] | None = None, weight: float = 1.0, name: str = '') → None

Adds a normal constraint to the error function.

param local_normal:

The normal in the parent’s coordinate frame.

param global_point:

The target point in global space.

param parent:

The index of the parent joint.

param local_point:

The point in the parent’s coordinate frame (defaults to origin).

param weight:

The weight of the constraint.

param name:

The name of the constraint (for debugging).

add_constraints(self: pymomentum.solver2.NormalErrorFunction, local_normal: numpy.ndarray[numpy.float32], global_point: numpy.ndarray[numpy.float32], parent: numpy.ndarray[numpy.int32], local_point: numpy.ndarray[numpy.float32] | None = None, weight: numpy.ndarray[numpy.float32] | None = None, name: list[str] | None = None) → None

Adds multiple normal constraints to the error function.

param local_normal:

A numpy array of shape (n, 3) for the normals in the parent’s coordinate frame.

param global_point:

A numpy array of shape (n, 3) for the target points in global space.

param parent:

A numpy array of size n for the indices of the parent joints.

param local_point:

A numpy array of shape (n, 3) for the points in the parent’s coordinate frame (defaults to origin).

param weight:

A numpy array of size n for the weights of the constraints.

param name:

An optional list of names for the constraints (for debugging).

property constraints: Returns the list of normal constraints.

class pymomentum.solver2.OrientationErrorFunction

Bases: SkeletonErrorFunction

A skeleton error function that minimizes the F-norm of the element-wise difference of a 3x3 rotation matrix to a target rotation.

add_constraint(self: pymomentum.solver2.OrientationErrorFunction, target: numpy.ndarray[numpy.float32[4, 1]], parent: int, offset: numpy.ndarray[numpy.float32[4, 1]] | None = None, weight: float = 1.0, name: str = '') → None

Adds an orientation constraint to the error function.

param offset:

The rotation offset in the parent space.

param target:

The target rotation in global space.

param parent:

The index of the parent joint.

param weight:

The weight of the constraint.

param name:

The name of the constraint (for debugging).

add_constraints(self: pymomentum.solver2.OrientationErrorFunction, target: numpy.ndarray[numpy.float32], parent: numpy.ndarray[numpy.int32], offset: numpy.ndarray[numpy.float32] | None = None, weight: numpy.ndarray[numpy.float32] | None = None, name: list[str] | None = None) → None

Adds multiple orientation constraints to the error function.

param target:

A numpy array of shape (n, 4) for the (x, y, z, w) quaternion target rotations in global space.

param parent:

A numpy array of size n for the indices of the parent joints.

param offset:

A numpy array of shape (n, 4) for the (x, y, z, w) quaternion rotation offsets in the parent space.

param weight:

A numpy array of size n for the weights of the constraints.

param name:

An optional list of names for the constraints (for debugging).

class pymomentum.solver2.PlaneData

Bases: pybind11_object

property d: The d parameter in the plane equation

property normal: The normal of the plane

property offset: The offset in parent space

property parent: The parent joint index

property weight: The weight of the constraint

class pymomentum.solver2.PlaneErrorFunction

Bases: SkeletonErrorFunction

The PlaneErrorFunction computes the point-on-plane error or point-in-half-plane error. For point-on-plane error (above = false), it computes the signed distance of a point to a plane using the plane equation. For half-plane error (above = true), the error is zero when the distance is greater than zero (ie. the point being above).

add_constraint(self: pymomentum.solver2.PlaneErrorFunction, offset: numpy.ndarray[numpy.float32[3, 1]], normal: numpy.ndarray[numpy.float32[3, 1]], d: float, parent: int, weight: float = 1.0, name: str = '') → None

Adds a plane constraint to the error function.

param offset:

The offset of the point in the parent’s coordinate frame.

param normal:

The normal of the plane.

param d:

The d parameter in the plane equation: x.dot(normal) - d = 0.

param parent:

The index of the parent joint.

param weight:

The weight of the constraint.

param name:

The name of the constraint (for debugging).

add_constraints(self: pymomentum.solver2.PlaneErrorFunction, normal: numpy.ndarray[numpy.float32], d: numpy.ndarray[numpy.float32], parent: numpy.ndarray[numpy.int32], offset: numpy.ndarray[numpy.float32] | None = None, weight: numpy.ndarray[numpy.float32] | None = None, name: list[str] | None = None) → None

Adds multiple plane constraints to the error function.

param offset:

A numpy array of shape (n, 3) for the offsets of the points in the parent’s coordinate frame.

param normal:

A numpy array of shape (n, 3) for the normals of the planes.

param d:

A numpy array of size n for the d parameters in the plane equations: x.dot(normal) - d = 0.

param parent:

A numpy array of size n for the indices of the parent joints.

param weight:

A numpy array of size n for the weights of the constraints.

param name:

An optional list of names for the constraints (for debugging).

property constraints: Returns the list of plane constraints.

class pymomentum.solver2.PointTriangleVertexErrorFunction

Bases: SkeletonErrorFunction

add_constraints(self: pymomentum.solver2.PointTriangleVertexErrorFunction, source_vertex_index: numpy.ndarray[numpy.int32], target_triangle_index: numpy.ndarray[numpy.int32], target_triangle_bary_coord: numpy.ndarray[numpy.float32], depth: numpy.ndarray[numpy.float32], weight: numpy.ndarray[numpy.float32]) → None

Adds a new constraint to the error function.

param parents:

The indices of the joints that are the parents of the locators.

param offsets:

The offsets of the locators from the parent joints.

param targets:

The target positions of the locators.

param weights:

The weights of the constraints.

param names:

The names of the constraints (for debugging).

clear_constraints(self: pymomentum.solver2.PointTriangleVertexErrorFunction) → None: Clears all vertex constraints from the error function.

class pymomentum.solver2.PosePriorErrorFunction

Bases: SkeletonErrorFunction

log_probability(self: pymomentum.solver2.PosePriorErrorFunction, model_parameters: numpy.ndarray[numpy.float32]) → float

Computes the log probability of the given model parameters under the pose prior.

param model_parameters:

The model parameters to evaluate.

return:

The log probability value.

set_pose_prior(self: pymomentum.solver2.PosePriorErrorFunction, pose_prior: pymomentum.geometry.Mppca) → None

Sets the pose prior model for the error function.

param pose_prior:

The pose prior model to use.

class pymomentum.solver2.PositionData

Bases: pybind11_object

property offset: The offset in parent space

property parent: The parent joint index

property target: The target position

property weight: The weight of the constraint

class pymomentum.solver2.PositionErrorFunction

Bases: SkeletonErrorFunction

A skeleton error function that tries to move locators to a target position.

Uses a generalized loss function that support various forms of losses such as L1, L2, and Cauchy. Details can be found in the paper ‘A General and Adaptive Robust Loss Function’ by Jonathan T. Barron.

add_constraint(self: pymomentum.solver2.PositionErrorFunction, parent: int, *, target: numpy.ndarray[numpy.float32[3, 1]], offset: numpy.ndarray[numpy.float32[3, 1]] | None = None, weight: float = 1.0, name: str = '') → None

Adds a new constraint to the error function.

Parameters:

parent – The index of the joint that is the parent of the locator.
offset – The offset of the locator in the parent joint local space.
target – The target position of the locator.
weight – The weight of the constraint.
name – The name of the constraint (for debugging).

add_constraints(self: pymomentum.solver2.PositionErrorFunction, parent: numpy.ndarray[numpy.int32], *, target: numpy.ndarray[numpy.float32], offset: numpy.ndarray[numpy.float32] | None = None, weight: numpy.ndarray[numpy.float32] | None = None, name: list[str] | None = None) → None

Adds a new constraint to the error function.

Parameters:

parent – The index of the joints that are the parents of the locator.
offset – The offset of the locators from the parent joint.
target – The target positions of the locator.
weight – The weight of the constraint.
names – The names of the constraints (for debugging).

property constraints: Returns the list of position constraints.

class pymomentum.solver2.ProjectionConstraint

Bases: pybind11_object

property offset: The offset in parent space

property parent: The parent joint index

property projection: The 3x4 projection matrix

property target: The target 2D position

property weight: The weight of the constraint

class pymomentum.solver2.ProjectionErrorFunction

Bases: SkeletonErrorFunction

The ProjectionErrorFunction projects a 3D point to a 2D point using a projection matrix. This is useful for camera-based constraints where you want to match a 3D point to a 2D observation.

add_constraint(self: pymomentum.solver2.ProjectionErrorFunction, projection: numpy.ndarray[numpy.float32[3, 4]], target: numpy.ndarray[numpy.float32[2, 1]], parent: int, offset: numpy.ndarray[numpy.float32[3, 1]] | None = None, weight: float = 1.0) → None

Adds a projection constraint to the error function.

param projection:

The 3x4 projection matrix.

param target:

The 2D target point.

param parent:

The index of the parent joint.

param offset:

The offset from the parent joint in local space.

param weight:

The weight of the constraint.

add_constraints(self: pymomentum.solver2.ProjectionErrorFunction, projection: numpy.ndarray[numpy.float32], target: numpy.ndarray[numpy.float32], parent: numpy.ndarray[numpy.int32], offset: numpy.ndarray[numpy.float32] | None = None, weight: numpy.ndarray[numpy.float32] | None = None) → None

Adds multiple projection constraints to the error function.

param projection:

A numpy array of shape (n, 3, 4) for the projection matrices.

param target:

A numpy array of shape (n, 2) for the 2D target points.

param parent:

A numpy array of size n for the indices of the parent joints.

param offset:

A numpy array of shape (n, 3) for the offsets from the parent joints in local space.

param weight:

A numpy array of size n for the weights of the constraints.

clear_constraints(self: pymomentum.solver2.ProjectionErrorFunction) → None: Clears all projection constraints from the error function.

property constraints: Returns the list of projection constraints.

empty(self: pymomentum.solver2.ProjectionErrorFunction) → bool: Returns true if there are no constraints.

num_constraints(self: pymomentum.solver2.ProjectionErrorFunction) → int: Returns the number of constraints.

class pymomentum.solver2.SequenceErrorFunction: Bases: pybind11_object

class pymomentum.solver2.SequenceSolverFunction

Bases: SolverFunction

add_error_function(*args, **kwargs)

Overloaded function.

add_error_function(self: pymomentum.solver2.SequenceSolverFunction, frame_idx: int, error_function: pymomentum.solver2.SkeletonErrorFunction) -> None

Adds an error function that applies to a single frame to the solver.

Parameters:

frame_idx – The frame index to add the error function to.
error_function – The error function to add.

add_error_function(self: pymomentum.solver2.SequenceSolverFunction, error_function: pymomentum.solver2.SkeletonErrorFunction) -> None

Adds an error function that applies to all frames to the solver.

Parameters:: error_function – The error function to add.

add_sequence_error_function(self: pymomentum.solver2.SequenceSolverFunction, frame_idx: int, error_function: pymomentum.solver2.SequenceErrorFunction) → None

Adds an error function that spans multiple frames in the solver.

Parameters:

frame_idx – The frame index to add the error function to.
error_function – The error function to add.

add_sequence_error_function_all_frames(self: pymomentum.solver2.SequenceSolverFunction, error_function: pymomentum.solver2.SequenceErrorFunction) → None

Adds an error function that spans all frames in the solver.

Parameters:: error_function – The error function to add.

get_error_functions(self: pymomentum.solver2.SequenceSolverFunction, frame_idx: int) → list[pymomentum.solver2.SkeletonErrorFunction]: Returns the per-frame error functions for a given frame.

Note that this is read-only; appending to this list will not affect the SequenceErrorFunction, use add_error_function() instead.

get_sequence_error_functions(self: pymomentum.solver2.SequenceSolverFunction, frame_idx: int) → list[pymomentum.solver2.SequenceErrorFunction]: Returns the sequence error functions.

Note that this is read-only; appending to this list will not affect the SequenceErrorFunction, use add_sequence_error_function() instead.

set_enabled_parameters(self: pymomentum.solver2.SequenceSolverFunction, active_parameters: numpy.ndarray[bool]) → None

Sets the active model parameters for the solver. The array should be of size character.parameter_transform.size() and applies to every frame of the solve.

Parameters:: active_parameters – Numpy array of length num of model params.

class pymomentum.solver2.SequenceSolverOptions

Bases: SolverOptions

Options specific to the sequence solver

property do_line_search: Flag to enable line search during optimization.

property multithreaded: Flag to enable multithreading for the Sequence solver.

property progress_bar: Flag to enable a progress bar during optimization.

property regularization: Regularization parameter for QR decomposition.

class pymomentum.solver2.SkeletonErrorFunction

Bases: pybind11_object

get_error(self: pymomentum.solver2.SkeletonErrorFunction, model_parameters: numpy.ndarray[numpy.float32]) → float

Compute the error for a given set of model parameters.

If you want to compute the error of multiple error functions, consider wrapping them in a SkeletonSolverFunction and using SkeletonSolverFunction.get_error().

Parameters:: model_parameters – The model parameters to evaluate.
Returns:: The error value.

get_gradient(self: pymomentum.solver2.SkeletonErrorFunction, model_parameters: numpy.ndarray[numpy.float32]) → numpy.ndarray[numpy.float32[m, 1]]

Compute the gradient for a given set of model parameters.

If you want to compute the gradient of multiple error functions, consider wrapping them in a SkeletonSolverFunction and using SkeletonSolverFunction.get_gradient().

Parameters:: model_parameters – The model parameters to evaluate.
Returns:: The gradient of the error function with respect to the model parameters.

get_jacobian(self: pymomentum.solver2.SkeletonErrorFunction, model_parameters: numpy.ndarray[numpy.float32]) → tuple[numpy.ndarray[numpy.float32[m, 1]], numpy.ndarray[numpy.float32[m, n]]]

Compute the jacobian and residual for a given set of model parameters.

If you want to compute the jacobian of multiple error functions, consider wrapping them in a SkeletonSolverFunction and using SkeletonSolverFunction.get_jacobian().

Parameters:: model_parameters – The model parameters to evaluate.
Returns:: A tuple containing the residual and the jacobian of the error function with respect to the model parameters.

property weight

class pymomentum.solver2.SkeletonSolverFunction

Bases: SolverFunction

add_error_function(self: pymomentum.solver2.SkeletonSolverFunction, arg0: pymomentum.solver2.SkeletonErrorFunction) → None

clear_error_functions(self: pymomentum.solver2.SkeletonSolverFunction) → None: Clears all error functions from the solver.

property error_functions

get_error(self: pymomentum.solver2.SkeletonSolverFunction, model_parameters: numpy.ndarray[numpy.float32]) → float

Compute the error for a given set of model parameters.

param model_parameters:

The model parameters to evaluate.

return:

The error value.

get_gradient(self: pymomentum.solver2.SkeletonSolverFunction, model_parameters: numpy.ndarray[numpy.float32]) → numpy.ndarray[numpy.float32[m, 1]]

Compute the gradient for a given set of model parameters.

Note that if you’re trying to actually solve a problem using SGD, you should consider using one of the Solver class instead, which are more efficient since they don’t require passing anything through the Python binding layers.

param model_parameters:

The model parameters to evaluate.

return:

The gradient of the error function with respect to the model parameters.

get_jacobian(self: pymomentum.solver2.SkeletonSolverFunction, model_parameters: numpy.ndarray[numpy.float32]) → tuple[numpy.ndarray[numpy.float32[m, 1]], numpy.ndarray[numpy.float32[m, n]]]

Compute the jacobian and residual for a given set of model parameters.

param model_parameters:

The model parameters to evaluate.

return:

A tuple containing the residual and the jacobian of the error function with respect to the model parameters.

class pymomentum.solver2.Solver

Bases: pybind11_object

property per_iteration_errors: The error after each iteration of the solver.

set_enabled_parameters(self: pymomentum.solver2.Solver, active_parameters: numpy.ndarray[bool]) → None

Sets the active model parameters for the solver. The array should be of size character.parameter_transform.size() and applies to every frame of the solve.

Parameters:: active_parameters – Numpy array of length num of model params.

solve(self: pymomentum.solver2.Solver, model_parameters: numpy.ndarray[numpy.float32[m, 1]]) → numpy.ndarray[numpy.float32[m, 1]]

class pymomentum.solver2.SolverFunction: Bases: pybind11_object

class pymomentum.solver2.SolverOptions

Bases: pybind11_object

property max_iterations: Maximum number of iterations before terminating

property min_iterations: Minimum number of iterations before checking convergence criteria

property threshold: Convergence threshold for relative error change

property verbose: Enable detailed logging during optimization

class pymomentum.solver2.StateErrorFunction

Bases: SkeletonErrorFunction

set_target_state(self: pymomentum.solver2.StateErrorFunction, target_state: numpy.ndarray[numpy.float32]) → None

Sets the target skeleton state for the error function.

Parameters:: target_state – A numpy array of shape (njoints, 8) where each row contains 3D position, 4D quaternion (rotation), and 1D scale for each joint.

class pymomentum.solver2.StateSequenceErrorFunction

Bases: SequenceErrorFunction

set_target_state(self: pymomentum.solver2.StateSequenceErrorFunction, target_state: numpy.ndarray[numpy.float32]) → None

Sets the target skeleton state for the error function.

param target_state:

A numpy array of shape (njoints, 8) where each row contains 3D position, 4D quaternion (rotation), and 1D scale for each joint.

class pymomentum.solver2.SubsetGaussNewtonSolver

Bases: Solver

Gauss-Newton solver that optimizes only a selected subset of parameters

class pymomentum.solver2.SubsetGaussNewtonSolverOptions

Bases: SolverOptions

Options specific to the Subset Gauss-Newton solver

property do_line_search: Enables backtracking line search to ensure error reduction at each step

property regularization: Damping parameter added to Hessian diagonal for numerical stability

class pymomentum.solver2.VertexConstraint

Bases: pybind11_object

property target_normal: The target normal for the vertex.

property target_position: The target position for the vertex.

property vertex_index: The index of the vertex to constrain.

property weight: The weight of the constraint.

class pymomentum.solver2.VertexConstraintType

Bases: pybind11_object

Members:

Position : Target the vertex position

Plane : Point-to-plane distance using the target normal

Normal : Point-to-plane distance using the source (body) normal

SymmetricNormal : Point-to-plane using a 50/50 mix of source and target normal

Normal = <VertexConstraintType.Normal: 2>

Plane = <VertexConstraintType.Plane: 1>

Position = <VertexConstraintType.Position: 0>

SymmetricNormal = <VertexConstraintType.SymmetricNormal: 3>

property name

property value

class pymomentum.solver2.VertexErrorFunction

Bases: SkeletonErrorFunction

add_constraint(self: pymomentum.solver2.VertexErrorFunction, vertex_index: int, weight: float, target_position: numpy.ndarray[numpy.float32[3, 1]], target_normal: numpy.ndarray[numpy.float32[3, 1]]) → None

Adds a vertex constraint to the error function.

param vertex_index:

The index of the vertex to constrain.

param weight:

The weight of the constraint.

param target_position:

The target position for the vertex.

param target_normal:

The target normal for the vertex.

add_constraints(self: pymomentum.solver2.VertexErrorFunction, vertex_index: numpy.ndarray[numpy.int32], target_position: numpy.ndarray[numpy.float32], target_normal: numpy.ndarray[numpy.float32], weight: numpy.ndarray[numpy.float32]) → None

Adds multiple vertex constraints to the error function.

param vertex_index:

The indices of the vertices to constrain.

param target_position:

The target positions for the vertices.

param target_normal:

The target normals for the vertices.

param weight:

The weights of the constraints.

clear_constraints(self: pymomentum.solver2.VertexErrorFunction) → None: Clears all vertex constraints from the error function.

property constraints: Returns the list of vertex constraints.

class pymomentum.solver2.VertexProjectionConstraint

Bases: pybind11_object

Read-only access to a vertex projection constraint.

property projection: Returns the 3x4 projection matrix.

property target_position: Returns the target 2D position.

property vertex_index: Returns the index of the vertex to project.

property weight: Returns the weight of the constraint.

class pymomentum.solver2.VertexProjectionErrorFunction

Bases: SkeletonErrorFunction

The VertexProjectionErrorFunction projects 3D vertices onto 2D points using a projection matrix. This is useful for camera-based constraints where you want to match a 3D vertex to a 2D observation.

add_constraint(self: pymomentum.solver2.VertexProjectionErrorFunction, vertex_index: int, weight: float, target_position: numpy.ndarray[numpy.float32[2, 1]], projection: numpy.ndarray[numpy.float32[3, 4]]) → None

Adds a vertex projection constraint to the error function.

param vertex_index:

The index of the vertex to project.

param weight:

The weight of the constraint.

param target_position:

The target 2D position.

param projection:

The 3x4 projection matrix.

add_constraints(self: pymomentum.solver2.VertexProjectionErrorFunction, vertex_index: numpy.ndarray[numpy.int32], weight: numpy.ndarray[numpy.float32], target_position: numpy.ndarray[numpy.float32], projection: numpy.ndarray[numpy.float32]) → None

Adds multiple vertex projection constraints to the error function.

param vertex_index:

A numpy array of size n for the indices of the vertices to project.

param weight:

A numpy array of size n for the weights of the constraints.

param target_position:

A numpy array of shape (n, 2) for the target 2D positions.

param projection:

A numpy array of shape (n, 3, 4) for the projection matrices.

clear_constraints(self: pymomentum.solver2.VertexProjectionErrorFunction) → None: Clears all vertex projection constraints from the error function.

property constraints: Returns the list of vertex projection constraints.

pymomentum.solver2.solve_sequence(solver_function: pymomentum.solver2.SequenceSolverFunction, model_params: numpy.ndarray[numpy.float32], options: pymomentum.solver2.SequenceSolverOptions | None = None) → numpy.ndarray[numpy.float32]

Solves a sequence of poses using the sequence solver.

Parameters:

solver_function – The solver function to use.
model_params – The initial model parameters. This is an n_frames x n_params array.
options – The solver options to use.

Returns:

The optimized model parameters.