pymomentum.geometry

Geometry and forward kinematics for momentum models.

class pymomentum.geometry.BlendShape

Bases: pybind11_object

property base_shape

Returns:: The base shape of the blend shape solver.

compute_shape(self: object, coeffs: torch.Tensor) → torch.Tensor

Apply the blend shape coefficients to compute the rest shape.

The resulting shape is equal to the base shape plus a linear combination of the shape vectors.

Parameters:: coeffs – A torch.Tensor of size [n_batch x n_shapes] containing blend shape coefficients.
Result:: A [n_batch x n_vertices x 3] tensor containing the vertex positions.

static from_bytes(blend_shape_bytes: bytes, num_expected_shapes: int = -1, num_expected_vertices: int = -1) → pymomentum.geometry.BlendShape

Load a blend shape basis from bytes in memory.

Parameters:

blend_shape_bytes – A chunk of bytes containing the blend shape basis.
num_expected_shapes – Trim the shape basis if it contains more shapes than this. Pass -1 (the default) to leave the shapes untouched.
num_expected_vertices – Trim the shape basis if it contains more vertices than this. Pass -1 (the default) to leave the shapes untouched.

Returns:

a BlendShape.

static from_tensors(base_shape: numpy.ndarray[numpy.float32], shape_vectors: numpy.ndarray[numpy.float32]) → pymomentum.geometry.BlendShape

Create a blend shape basis from numpy.ndarrays.

Parameters:

base_shape – A [nPts x 3] ndarray containing the base shape.
shape_vectors – A [nShapes x nPts x 3] ndarray containing the blend shape basis.

Returns:

a BlendShape.

static load(path: str, num_expected_shapes: int = -1, num_expected_vertices: int = -1) → pymomentum.geometry.BlendShape

Load a blend shape basis from a file.

Parameters:

blend_shape_path – The path to a blend shape file.
num_expected_shapes – Trim the shape basis if it contains more shapes than this. Pass -1 (the default) to leave the shapes untouched.
num_expected_vertices – Trim the shape basis if it contains more vertices than this. Pass -1 (the default) to leave the shapes untouched.

Returns:

A BlendShape.

property n_shapes: Number of shapes in the blend shape basis.

property n_vertices: Number of vertices in the mesh.

property shape_vectors

Returns:: The base shape of the blend shape solver.

class pymomentum.geometry.Character

Bases: pybind11_object

A complete momentum character including its skeleton and mesh.

apply_model_param_limits(self: pymomentum.geometry.Character, model_params: torch.Tensor) → torch.Tensor

Clamp model parameters by parameter limits stored in Character.

Note the function is differentiable.

Parameters:: model_params – the (can be batched) body model parameters.
Returns:: clampled model parameters. Same tensor shape as the input.

property bind_pose: Get the bind pose for skinning.

property blend_shape

Returns:: The character’s BlendShape basis, if present, or None.

property collision_geometry

Returns:: A list of TaperedCapsule representing the character’s collision geometry.

find_locators(self: pymomentum.geometry.Character, names: list[str]) → tuple[numpy.ndarray[numpy.int32[m, 1]], numpy.ndarray[numpy.float32[m, n]]]

Return the parents/offsets of the passed-in locators.

Parameters:: names – The names of the locators or joints.
Returns:: a pair [parents, offsets] of numpy arrays.

static from_gltf_bytes(gltf_bytes: bytes) → pymomentum.geometry.Character

Load a character from a gltf byte array.

Parameters:: gltf_bytes – A bytes containing the GLTF JSON/messagepack data.
Returns:: a valid Character.

property has_mesh

property inverse_bind_pose: Get the inverse bind pose for skinning.

property joint_parameter_limits

A tuple (min, max) where each is an (nJoints x 7)-length ndarray containing the upper or lower limits for the joint parameters.

Note that not all parameters will have limits; for those parameters (such as global translation) without limits, (-FLT_MAX, FLT_MAX) is returned.

Note: In practice, most limits are enforced on the model parameters, but momentum’s joint limit functionality permits applying limits to joint parameters also as a conveninence.

joints_for_parameters(self: pymomentum.geometry.Character, active_parameters: torch.Tensor) → list[int]: Maps a list of parameter indices to a list of joints driven by those parameters.

static load_fbx(fbx_filename: str, model_filename: str | None = None, locators_filename: str | None = None, permissive: bool = False) → pymomentum.geometry.Character

Load a character from an FBX file. Optionally pass in a separate model definition and locators file.

Parameters:

fbx_filename – .fbx file that contains the skeleton and skinned mesh; e.g. character_s0.fbx.
model_filename – Configuration file that defines the parameter mappings and joint limits; e.g. character.cfg.
locators_filename – File containing the locators, e.g. character.locators.

Returns:

A valid Character.

static load_fbx_from_bytes(fbx_bytes: bytes, permissive: bool = False) → pymomentum.geometry.Character

Load a character from byte array for an FBX file.

Parameters:: fbx_bytes – An array of bytes in FBX format.
Returns:: A valid Character.

static load_fbx_with_motion(fbx_filename: str, permissive: bool = False) → tuple[pymomentum.geometry.Character, list[numpy.ndarray[numpy.float32[m, n]]], float]

Load a character and animation curves from an FBX file.

Parameters:: fbx_filename – .fbx file that contains the skeleton and skinned mesh; e.g. character_s0.fbx.
Returns:: A valid Character, a vector of motions in the format of nFrames X nNumJointParameters, and fps. The caller needs to decide how to handle the joint parameters.

static load_fbx_with_motion_from_bytes(fbx_bytes: bytes, permissive: bool = False) → tuple[pymomentum.geometry.Character, list[numpy.ndarray[numpy.float32[m, n]]], float]

Load a character and animation curves from an FBX file.

Parameters:: fbx_bytes – A Python bytes that is an .fbx file containing the skeleton and skinned mesh.
Returns:: A valid Character, a vector of motions in the format of nFrames X nNumJointParameters, and fps. The caller needs to decide how to handle the joint parameters.

static load_gltf(path: str) → pymomentum.geometry.Character

Load a character from a gltf file.

Parameters:: path – A .gltf file; e.g. character_s0.glb.

static load_gltf_with_motion(gltf_filename: str) → tuple[pymomentum.geometry.Character, numpy.ndarray[numpy.float32[m, n]], numpy.ndarray[numpy.float32[m, 1]], float]

Load a character and a motion sequence from a gltf file.

Parameters:: gltfFilename – A .gltf file; e.g. character_s0.glb.
Returns:: a tuple [Character, motion, identity, fps], where motion is the motion matrix [nFrames x nParams] and identity is a JointParameter at rest pose.

load_locators(self: pymomentum.geometry.Character, filename: str) → pymomentum.geometry.Character

Load locators from a .locators file.

Parameters:

character – The character to map the locators onto.
filename – Filename for the locators.

Returns:

A valid Character.

load_locators_from_bytes(self: pymomentum.geometry.Character, locator_bytes: bytes) → pymomentum.geometry.Character

Load locators from a .locators file.

Parameters:

character – The character to map the locators onto.
locator_bytes – A byte array containing the locators.

Returns:

A valid Character.

load_model_definition(self: pymomentum.geometry.Character, filename: str) → pymomentum.geometry.Character

Load a model definition from a .model file. This defines the parameter transform, model parameters, and joint limits.

Parameters:

character – The character containing a valid skeleton.
filename – Filename for the model definition.

Returns:

A valid Character.

load_model_definition_from_bytes(self: pymomentum.geometry.Character, model_bytes: bytes) → pymomentum.geometry.Character

Load a model definition from a .model file. This defines the parameter transform, model parameters, and joint limits.

Parameters:

character – The character containing a valid skeleton.
model_bytes – Bytes array containing the model definition.

Returns:

A valid Character.

static load_urdf(urdf_filename: str) → pymomentum.geometry.Character

Load a character from a urdf file.

Parameters:: urdf_filename – A .urdf file; e.g. character.urdf.

static load_urdf_from_bytes(urdf_bytes: bytes) → pymomentum.geometry.Character

Load a character from urdf bytes.

Parameters:: urdf_bytes – Bytes array containing the urdf definition.

property locators: List of locators on the mesh.

property mesh

Returns:: The character’s mesh, or None if not present.

property model_parameter_limits: A tuple (min, max) where each is an nParameter-length ndarray containing the upper or lower limits for the model parameters. Note that not all parameters will have limits; for those parameters (such as global translation) without limits, (-FLT_MAX, FLT_MAX) is returned.

property name: The character’s name.

property parameter_limits: The character’s parameter limits.

property parameter_transform: Maps the reduced k-dimensional modelParameters that are used in the IK solve to the full 7*n-dimensional parameters used in the skeleton.

parameters_for_joints(self: pymomentum.geometry.Character, joint_indices: list[int]) → torch.Tensor: Maps a list of joint indices to a boolean tensor containing the parameters which drive those joints.

pose_mesh(self: pymomentum.geometry.Character, joint_params: numpy.ndarray[numpy.float32[m, 1]]) → pymomentum.geometry.Mesh

Poses the mesh

Parameters:: joint_params – The (7*nJoints) joint parameters for the given pose.
Returns:: A Mesh object with the given pose.

rebind_skin(self: pymomentum.geometry.Character) → pymomentum.geometry.Character: Rebind the character’s inverse bind pose from the resting skeleton pose.

static save_fbx(path: str, character: pymomentum.geometry.Character, fps: float = 120.0, motion: numpy.ndarray[numpy.float32[m, n]] | None = None, offsets: numpy.ndarray[numpy.float32[m, 1]] | None = None, coord_system_info: pymomentum.geometry.FBXCoordSystemInfo | None = None) → None

Save a character to an fbx file.

Parameters:

path – An .fbx export filename.
character – A Character to be saved to the output file.
fps – Frequency in frames per second
motion – [Optional] 2D pose matrix in [n_frames x n_parameters]
offsets – [Optional] Offset array in [(n_joints x n_parameters_per_joint)]
coord_system_info – [Optional] FBX coordinate system info

static save_fbx_with_joint_params(path: str, character: pymomentum.geometry.Character, fps: float = 120.0, joint_params: numpy.ndarray[numpy.float32[m, n]] | None = None, coord_system_info: pymomentum.geometry.FBXCoordSystemInfo | None = None) → None

Save a character to an fbx file with joint params.

Parameters:

path – An .fbx export filename.
character – A Character to be saved to the output file.
fps – Frequency in frames per second
joint_params – [Optional] 2D pose matrix in [n_frames x n_parameters]
coord_system_info – [Optional] FBX coordinate system info

static save_gltf(path: str, character: pymomentum.geometry.Character, fps: float = 120.0, motion: tuple[list[str], numpy.ndarray[numpy.float32[m, n]]] | None = None, offsets: tuple[list[str], numpy.ndarray[numpy.float32[m, 1]]] | None = None, markers: list[list[pymomentum.geometry.Marker]] | None = None) → None

Save a character to a gltf file.

Parameters:

path – A .gltf export filename.
character – A Character to be saved to the output file.
fps – Frequency in frames per second
motion – Pose array in [n_frames x n_parameters]
offsets – Offset array in [n_joints x n_parameters_per_joint]
markers – Additional marker (3d positions) data in [n_frames][n_markers]

static save_gltf_from_skel_states(path: str, character: pymomentum.geometry.Character, fps: float, skel_states: numpy.ndarray[numpy.float32], markers: list[list[pymomentum.geometry.Marker]] | None = None) → None

Save a character to a gltf file.

Parameters:

path – A .gltf export filename.
character – A Character to be saved to the output file.
fps – Frequency in frames per second
skel_states – Skeleton states [n_frames x n_joints x n_parameters_per_joint]
markers – Additional marker (3d positions) data in [n_frames][n_markers]

scaled(self: pymomentum.geometry.Character, scale: float) → pymomentum.geometry.Character

Scale the character (mesh and skeleton) by the desired amount.

Note that this primarily be used when transforming the character into different units; if you simply want to apply an identity-specific scale to the character, you should use the ‘scale_global’ parameter in the ParameterTransform.

Returns:

a new Character that has been scaled.

Parameters:

character – The character to be scaled.
scale – The scale to apply.

simplify(self: pymomentum.geometry.Character, enabled_parameters: torch.Tensor | None = None) → pymomentum.geometry.Character

Simplifies the character by removing extra joints; this can help to speed up IK, but passing in a set of parameters rather than joints. Does not modify the parameter transform. This is the equivalent of calling `character.simplify_skeleton(character.joints_from_parameters(enabled_params))`.

Parameters:: enabled_parameters – Model parameters to be kept in the simplified model. Defaults to including all parameters.
Returns:: a new Character with extraneous joints removed.

simplify_parameter_transform(self: pymomentum.geometry.Character, enabled_parameters: torch.Tensor) → pymomentum.geometry.Character: Simplifies the character by removing unwanted parameters.

simplify_skeleton(self: pymomentum.geometry.Character, enabled_joint_indices: list[int]) → pymomentum.geometry.Character: Simplifies the character by removing unwanted joints.

property skeleton: The character’s skeleton.

skin_points(self: object, skel_state: torch.Tensor, rest_vertices: torch.Tensor | None = None) → torch.Tensor

Skins the points using the character’s linear blend skinning.

Parameters:

character – A Character with both a rest mesh and skinning weights.
skel_state – A torch.Tensor containing either a [nBatch x nJoints x 8] skeleton state or a [nBatch x nJoints x 4 x 4] transforms.
rest_vertices – An optional torch.Tensor containing the rest points; if not passed, the ones stored inside the character are used.

Returns:

The vertex positions in worldspace.

property skin_weights: The character’s skinning weights.

static to_gltf(character: pymomentum.geometry.Character) → str

Serialize a character as a GLTF using dictionary form.

Parameters:

character – A valid character.
fps – Frames per second for describing the motion.
motion – tuple of vector of parameter names and a P X T matrix. P is number of parameters, T is number of frames.
offsets – tuple of vector of joint names and a Vector of size J * 7 (Parameters per joint). Eg. for 3 joints, you would have 21 params.

Returns:

a GLTF representation of Character with motion

transformed(self: pymomentum.geometry.Character, xform: numpy.ndarray[numpy.float32[4, 4]]) → pymomentum.geometry.Character

Transform the character (mesh and skeleton) by the desired transformation matrix.

Note that this is primarily intended for transforming between different spaces (e.g. x-up vs y-up). If you want to translate/rotate/scale a character, you should preferentially use the model parameters to do so.

Returns:

a new Character that has been transformed.

Parameters:

character – The character to be transformed.
xform – The transform to apply.

with_blend_shape(self: pymomentum.geometry.Character, blend_shape: pymomentum.geometry.BlendShape, n_shapes: int = -1) → pymomentum.geometry.Character

Returns a character that uses the parameter transform to control the passed-in blend shape basis. It can be used to solve for shapes and pose simultaneously.

Parameters:

blend_shape – Blend shape basis.
n_shapes – Max blend shapes to retain. Pass -1 to keep all of them (but warning: the default allgender basis is quite large with hundreds of shapes).

with_locators(self: pymomentum.geometry.Character, locators: list[pymomentum.geometry.Locator], replace: bool = False) → pymomentum.geometry.Character

Returns a new character with the passed-in locators. If ‘replace’ is true, the existing locators are replaced, otherwise (the default) the new locators are appended to the existing ones.

param locators:

The locators to add to the character.

param replace:

If true, replace the existing locators with the passed-in ones. Otherwise, append the new locators to the existing ones. Defaults to false.

with_mesh_and_skin_weights(self: pymomentum.geometry.Character, mesh: pymomentum.geometry.Mesh, skin_weights: pymomentum.geometry.SkinWeights | None = None) → pymomentum.geometry.Character: Adds mesh and skin weight to the character and return a new character instance

with_parameter_limits(self: pymomentum.geometry.Character, parameter_limits: list[pymomentum.geometry.ParameterLimit]) → pymomentum.geometry.Character: Returns a new character with the parameter limits set to the passed-in limits.

class pymomentum.geometry.FBXCoordSystem

Bases: pybind11_object

Members:

RightHanded

LeftHanded

LeftHanded = <FBXCoordSystem.LeftHanded: 1>

RightHanded = <FBXCoordSystem.RightHanded: 0>

property name

property value

class pymomentum.geometry.FBXCoordSystemInfo

Bases: pybind11_object

property coordSystem: Returns the coordinate system.

property frontVector: Returns the front vector.

property upVector: Returns the up vector.

class pymomentum.geometry.FBXFrontVector

Bases: pybind11_object

Members:

ParityEven

ParityOdd

ParityEven = <FBXFrontVector.ParityEven: 1>

ParityOdd = <FBXFrontVector.ParityOdd: 2>

property name

property value

class pymomentum.geometry.FBXUpVector

Bases: pybind11_object

Members:

XAxis

YAxis

ZAxis

XAxis = <FBXUpVector.XAxis: 1>

YAxis = <FBXUpVector.YAxis: 2>

ZAxis = <FBXUpVector.ZAxis: 3>

property name

property value

class pymomentum.geometry.InverseParameterTransform

Bases: pybind11_object

apply(self: pymomentum.geometry.InverseParameterTransform, joint_parameters: torch.Tensor) → torch.Tensor

Apply the inverse parameter transform to a 7*nJoints-dimensional joint parameter vector (returns the k-dimensional model parameter vector).

Because the number of joint parameters is much larger than the number of model parameters, this will in general have a non-zero residual.

Parameters:: joint_parameters – Joint parameter tensor with dimensions (nBatch x 7*nJoints).
Returns:: A torch.Tensor containing the (nBatch x nModelParameters) model parameters.

class pymomentum.geometry.Joint

Bases: pybind11_object

property name: Returns the name of the joint.

property parent: Returns the index of the parent joint (-1 for the parent)

property pre_rotation: Returns the pre-rotation for this joint in default pose of the character. Quaternion format: (x, y, z, w)

property translation_offset: Returns the translation offset for this joint in default pose of the character.

class pymomentum.geometry.LimitData

Bases: pybind11_object

property ellipsoid: Data for Ellipsoid limit.

property halfplane: Data for HalfPlane limit.

property linear: Data for Linear limit.

property linear_joint: Data for LinearJoint limit.

property minmax: Data for MinMax limit.

property minmax_joint: Data for MinMaxJoint limit.

class pymomentum.geometry.LimitEllipsoid

Bases: pybind11_object

property ellipsoid

property ellipsoid_inv

property ellipsoid_parent

property offset

property parent

class pymomentum.geometry.LimitHalfPlane

Bases: pybind11_object

property normal

property offset

property param1_index

property param2_index

class pymomentum.geometry.LimitLinear

Bases: pybind11_object

property offset: Offset to use in equation p_0 = scale * p_1 - offset.

property range_max

property range_min

property reference_model_parameter_index: Index of reference parameter p0 to use in equation p_0 = scale * p_1 - offset.

property scale: Scale to use in equation p_0 = scale * p_1 - offset.

property target_model_parameter_index: Index of target parameter p1 to use in equation p_0 = scale * p_1 - offset.

class pymomentum.geometry.LimitLinearJoint

Bases: pybind11_object

property offset: Offset to use in equation p_0 = scale * p_1 - offset.

property range_max

property range_min

property reference_joint_index: Index of reference joint to use in equation p_0 = scale * p_1 - offset.

property reference_joint_parameter: Index of reference parameter to use (tx=0,ty=1,tz=2,rx=3,ry=4,rz=5,s=6).

property scale: Scale to use in equation p_0 = scale * p_1 - offset.

property target_joint_index: Index of target joint to use in equation p_0 = scale * p_1 - offset.

property target_joint_parameter: Index of target parameter to use (tx=0,ty=1,tz=2,rx=3,ry=4,rz=5,s=6).

class pymomentum.geometry.LimitMinMax

Bases: pybind11_object

property max: Maximum value of MinMax limit.

property min: Minimum value of MinMax limit.

property model_parameter_index: Index of model parameter to use.

class pymomentum.geometry.LimitMinMaxJoint

Bases: pybind11_object

property joint_index: Index of joint to affect.

property joint_parameter_index: Index of joint parameter to use, in the range 0->7 (tx,ty,tz,rx,ry,rz,s).

property max: Maximum value of MinMaxJoint limit.

property min: Minimum value of MinMaxJoint limit.

class pymomentum.geometry.LimitType

Bases: pybind11_object

Type of joint limit.

Members:

MinMax

MinMaxJoint

MinMaxJointPassive

Linear

LinearJoint

Ellipsoid

HalfPlane

Ellipsoid = <LimitType.Ellipsoid: 5>

HalfPlane = <LimitType.HalfPlane: 6>

Linear = <LimitType.Linear: 3>

LinearJoint = <LimitType.LinearJoint: 4>

MinMax = <LimitType.MinMax: 0>

MinMaxJoint = <LimitType.MinMaxJoint: 1>

MinMaxJointPassive = <LimitType.MinMaxJointPassive: 2>

property name

property value

class pymomentum.geometry.Locator

Bases: pybind11_object

property limit_origin: Defines the limit reference position. equal to offset on loading.

property limit_weight: Defines how close an unlocked locator should stay to it’s original position

property locked: Flag per axes to indicate whether that axis can be moved during optimization or not.

property name: The locator’s name.

property offset: The locator’s offset to parent joint location.

property parent: The locator’s parent joint index.

property weight: Weight for this locator during IK optimization.

class pymomentum.geometry.Marker

Bases: pybind11_object

property name: Name of the marker

property occluded: True if the marker is occluded with no position info

property pos: Marker 3d position

class pymomentum.geometry.MarkerSequence

Bases: pybind11_object

property fps: Frame rate

property frames: Marker data in [nframes][nMarkers]

property name: Name of the subject

class pymomentum.geometry.Mesh

Bases: pybind11_object

property colors

Returns:: Per-vertex colors if available; returned as a (possibly empty) [n x 3] numpy array.

property confidence: list of per-vertex confidences

property faces

Returns:: The triangles of the mesh in an [n x 3] numpy array.

property lines: list of list of vertex indices per line

property n_faces

Returns:: The number of faces in the mesh.

property n_vertices

Returns:: The number of vertices in the mesh.

property normals

Returns:: The per-vertex normals of the mesh in a [n x 3] numpy array.

property texcoord_faces: n x 3 faces in the texture map. Each face maps 1-to-1 to a face in the original mesh but indexes into the texcoords array.

property texcoord_lines: Texture coordinate indices for each line.

property texcoords: texture coordinates as m x 3 array. Note that the number of texture coordinates may be different from the number of vertices as there can be cuts in the texture map. Use texcoord_faces to index the texture coordinates.

property vertices

Returns:: The vertices of the mesh in a [n x 3] numpy array.

class pymomentum.geometry.Mppca

Bases: pybind11_object

Probability distribution over poses, used by the PosePriorErrorFunction. Currently contains a mixture of probabilistic PCA models.

Each PPCA model is a Gaussian with mean mu and covariance (sigma^2*I + W*W^T).

static from_bytes(mppca_bytes: bytes) → pymomentum.geometry.Mppca: Load a mixture PCA model (e.g. poseprior.mppca).

get_mixture(self: pymomentum.geometry.Mppca, i_model: int) → tuple[float, numpy.ndarray[numpy.float32[m, 1]], numpy.ndarray[numpy.float32[m, n]], float]

static load(mppca_filename: str) → pymomentum.geometry.Mppca: Load a mixture PCA model (e.g. poseprior.mppca).

property n_dimension: The dimension of the parameter space.

property n_mixtures: The number of individual Gaussians in the mixture model.

property names: The names of the parameters.

static save(mppca: pymomentum.geometry.Mppca, mppca_filename: str) → None: Save a mixture PCA model to file (e.g. poseprior.mppca).

to_tensors(self: pymomentum.geometry.Mppca, parameter_transform: pymomentum.geometry.ParameterTransform | None = None) → tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

Return the parameters defining the mixture of probabilistic PCA models.

Each PPCA model a Gaussian N(mu, cov) where the covariance matrix is (sigma*sigma*I + W * W^T). pi is the mixture weight for this particular Gaussian.

Note that mu is a vector of length dimension() and W is a matrix of dimension dimension() x q where q is the dimensionality of the PCA subspace.

The resulting tensors are as follows:

pi: a [n]-dimensional tensor containing the mixture weights. It sums to 1.
mu: a [n x d]-dimensional tensor containing the mean pose for each mixture.
weights: a [n x d x q]-dimensional tensor containing the q vectors spanning the PCA space.
sigma: a [n]-dimensional tensor containing the uniform part of the covariance matrix.
param_idx: a [d]-dimensional tensor containing the indices of the parameters.

Parameters:: parameter_transform – An optional parameter transform used to map the parameters; if not present, then the param_idx tensor will be empty.
Returns:: an tuple (pi, mean, weights, sigma, param_idx) for the Probabilistic PCA model.

class pymomentum.geometry.ParameterLimit

Bases: pybind11_object

static create_ellipsoid(ellipsoid_parent: int, parent: int, offset: numpy.ndarray[numpy.float32[3, 1]], ellipsoid: numpy.ndarray[numpy.float32[4, 4]], weight: float = 1.0) → pymomentum.geometry.ParameterLimit

Create a parameter limit with an ellipsoid constraint.

Parameters:

ellipsoid_parent – Index of joint to use as the ellipsoid’s parent.
parent – Index of joint to constraint.
offset – Offset of the ellipsoid from the parent joint.
ellipsoid – 4x4 matrix defining the ellipsoid’s shape.
weight – Weight of the parameter limit. Defaults to 1.

static create_halfplane(param1_index: int, param2_index: int, normal: numpy.ndarray[numpy.float32[2, 1]], offset: float = 0.0, weight: float = 1.0) → pymomentum.geometry.ParameterLimit

Create a parameter limit with a half-plane constraint.

Parameters:

param1_index – Index of the first parameter in the plane equation (p1, p2) . (n1, n2) - offset >= 0.
param2_index – Index of the second parameter (p1, p2) . (n1, n2) - offset >= 0.
offset – Offset to use in equation (p1, p2) . (n1, n2) - offset >= 0.
weight – Weight of the parameter limit. Defaults to 1.

static create_linear(reference_model_parameter_index: int, target_model_parameter_index: int, scale: float, offset: float, weight: float = 1.0, range_min: float | None = None, range_max: float | None = None) → pymomentum.geometry.ParameterLimit

Create a parameter limit with a linear constraint.

Parameters:

reference_model_parameter_index – Index of reference parameter p0 to use in equation p_0 = scale * p_1 - offset.
target_model_parameter_index – Index of target parameter p1 to use in equation p_0 = scale * p_1 - offset.
scale – Scale to use in equation p_0 = scale * p_1 - offset.
offset – Offset to use in equation p_0 = scale * p_1 - offset.
weight – Weight of the parameter limit. Defaults to 1.
range_min – Minimum of the range that the linear limit applies over. Defaults to -infinity.
range_max – Minimum of the range that the linear limit applies over. Defaults to +infinity.

static create_linear_joint(reference_joint_index: int, reference_joint_parameter: int, target_joint_index: int, target_joint_parameter: int, scale: float, offset: float, weight: float = 1.0, range_min: float | None = None, range_max: float | None = None) → pymomentum.geometry.ParameterLimit

Create a parameter limit with a linear joint constraint.

Parameters:

reference_joint_index – Index of reference joint p0 to use in equation p_0 = scale * p_1 - offset.
reference_joint_parameter – Index of parameter within joint to use.
target_joint_index – Index of target parameter p1 to use in equation p_0 = scale * p_1 - offset.
target_joint_parameter – Index of parameter within joint to use.
scale – Scale to use in equation p_0 = scale * p_1 - offset.
offset – Offset to use in equation p_0 = scale * p_1 - offset.
weight – Weight of the parameter limit. Defaults to 1.
range_min – Minimum of the range that the linear limit applies over. Defaults to -infinity.
range_max – Minimum of the range that the linear limit applies over. Defaults to +infinity.

static create_minmax(model_parameter_index: int, min: float, max: float, weight: float = 1.0) → pymomentum.geometry.ParameterLimit

Create a parameter limit with min and max values for a model parameter.

Parameters:

model_parameter_index – Index of model parameter to limit.
min – Minimum value of the parameter.
max – Maximum value of the parameter.
weight – Weight of the parameter limit. Defaults to 1.

static create_minmax_joint(joint_index: int, joint_parameter: int, min: float, max: float, weight: float = 1.0) → pymomentum.geometry.ParameterLimit

Create a parameter limit with min and max values for a joint parameter.

Parameters:

joint_index – Index of joint to limit.
joint_parameter – Index of joint parameter to limit, in the range 0->7 (tx,ty,tz,rx,ry,rz,s).
min – Minimum value of the parameter.
max – Maximum value of the parameter.
weight – Weight of the parameter limit. Defaults to 1.

property data: Data of parameter limit.

property type: Type of parameter limit.

property weight: Weight of parameter limit.

class pymomentum.geometry.ParameterTransform

Bases: pybind11_object

property all_parameters: Boolean torch.Tensor with all parameters enabled.

apply(self: pymomentum.geometry.ParameterTransform, model_parameters: torch.Tensor) → torch.Tensor

Apply the parameter transform to a k-dimensional model parameter vector (returns the 7*nJoints joint parameter vector).

The modelParameters store the reduced set of parameters (typically around 50) that are actually optimized in the IK step.

The jointParameters are stored (tx, ty, tz; rx, ry, rz; s) and each represents the transform relative to the parent joint. Rotations are in Euler angles.

property blend_shape_parameters: Boolean torch.Tensor with just the blend shape parameters enabled.

find_parameters(self: pymomentum.geometry.ParameterTransform, names: list[str], allow_missing: bool = False) → torch.Tensor

Return a boolean tensor with the named parameters set to true.

Parameters:

parameter_names – Names of the parameters to find.
allow_missng – If false, missing parameters will throw an exception.

inverse(self: pymomentum.geometry.ParameterTransform) → pymomentum.geometry.InverseParameterTransform

Compute the inverse of the parameter transform (a mapping from joint parameters to model parameters).

Returns:: The inverse parameter transform.

property names: List of model parameter names

property no_parameters: Boolean torch.Tensor with no parameters enabled.

property parameter_sets: A dictionary mapping names to sets of parameters (as a boolean torch.Tensor) that are defined in the .model file. This is convenient for turning off certain body features; for example the ‘fingers’ parameters can be used to enable/disable finger motion in the character model.

parameters_for_joints(self: pymomentum.geometry.ParameterTransform, joint_indices: list[int]) → torch.Tensor

Gets a boolean torch.Tensor indicating which parameters affect the passed-in joints.

Parameters:: jointIndices – List of integers of skeleton joints.

property pose_parameters: Boolean torch.Tensor with all the parameters used to pose the body, excluding and scaling, blend shape, or physics parameters.

property rigid_parameters: Boolean torch.Tensor indicating which parameters are used to control the character’s rigid transform (translation and rotation).

property scaling_parameters: Boolean torch.Tensor indicating which parameters are used to control the character’s scale.

property size: Size of the model parameter vector.

property transform: Returns the parameter transform matrix which when applied maps model parameters to joint parameters.

class pymomentum.geometry.Skeleton

Bases: pybind11_object

get_child_joints(self: pymomentum.geometry.Skeleton, root_joint_index: int, recursive: bool) → list[int]

Find all joints parented under the given joint.

Returns:: A list of integers, one per joint.

get_parent(self: pymomentum.geometry.Skeleton, joint_index: int) → int

Get the parent joint index of the given joint. Return -1 for root.

Parameters:: joint_index – the index of a skeleton joint.
Returns:: The index of the parent joint, or -1 if it is the root of the skeleton.

is_ancestor(self: pymomentum.geometry.Skeleton, joint_index: int, ancestor_joint_index: int) → bool

Checks if one joint is an ancestor of another, inclusive.

Parameters:

joint_index – The index of a skeleton joint.
ancestor_joint_index – The index of a possible ancestor joint.

Returns:

true if ancestorJointId is an ancestor of jointId; that is,

if jointId is in the tree rooted at ancestorJointId. Note that a joint is considered to be its own ancestor; that is, isAncestor(id, id) returns true.

joint_index(self: pymomentum.geometry.Skeleton, name: str, allow_missing: bool = False) → int: Get the joint index for a given joint name. Returns -1 if joint is not found and allow_missing is True.

property joint_names: Returns a list of joint names in the skeleton.

property joint_parents

Returns:: the parent of each joint in the skeleton. The root joint has parent -1.

property offsets: Returns skeleton joint offsets tensor for all joints (num_joints, 3

property pre_rotations: Returns skeleton joint offsets tensor for all joints shape: (num_joints, 4)

property size: Returns the number of joints in the skeleton.

property upper_body_joints

Convenience function to get all upper-body joints (defined as those parented under ‘b_spine0’).

Returns:: A list of integers, one per joint.

class pymomentum.geometry.SkinWeights

Bases: pybind11_object

property index: Returns the skinning indices.

property weight: Returns the skinning weights.

class pymomentum.geometry.TaperedCapsule

Bases: pybind11_object

property length

property parent

property radius

property transformation

pymomentum.geometry.apply_parameter_transform(character: object, model_parameters: torch.Tensor) → torch.Tensor

Apply the parameter transform to a [nBatch x nParams] tensor of model parameters. This is functionally identical to ParameterTransform.apply() except that it allows batching on the character.

Parameters:

character (Union[Character, List[Character]]) – A character or list of characters.
modelParameters – A [nBatch x nParams] tensor of model parameters.

Returns:

a tensor of joint parameters.

pymomentum.geometry.compute_vertex_normals(vertex_positions: torch.Tensor, triangles: torch.Tensor) → torch.Tensor

Computes vertex normals for a triangle mesh given its positions.

Parameters:

vertex_positions – [nBatch] x nVert x 3 Tensor of vertex positions.
triangles – nTriangles x 3 Tensor of triangle indices.

Returns:

Smooth per-vertex normals.

pymomentum.geometry.create_test_mppca() → pymomentum.geometry.Mppca

Create a pose prior that acts on the simple 3-joint test character.

Returns:: A simple pose prior.

pymomentum.geometry.find_closest_points(*args, **kwargs)

Overloaded function.

find_closest_points(points_source: torch.Tensor, points_target: torch.Tensor, max_dist: float = 3.4028234663852886e+38) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]

For each point in the points_source tensor, find the closest point in the points_target tensor. This version of find_closest points supports both 2- and 3-dimensional point sets.

Parameters:

points_source – [nBatch x nPoints x dim] tensor of source points (dim must be 2 or 3).
points_target – [nBatch x nPoints x dim] tensor of target points (dim must be 2 or 3).
max_dist – Maximum distance to search, can be used to speed up the method by allowing the search to return early. Defaults to FLT_MAX.

Returns:

A tuple of three tensors. The first is [nBatch x nPoints x dim] and contains the closest point for each point in the target set. The second is [nBatch x nPoints] and contains the index of each closest point in the target set (or -1 if none). The third is [nBatch x nPoints] and is a boolean tensor indicating whether a valid closest point was found for each source point.

find_closest_points(points_source: torch.Tensor, normals_source: torch.Tensor, points_target: torch.Tensor, normals_target: torch.Tensor, max_dist: float = 3.4028234663852886e+38, max_normal_dot: float = 0.0) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

For each point in the points_source tensor, find the closest point in the points_target tensor whose normal is compatible (n_source . n_target > max_normal_dot). Using the normal is a good way to avoid certain kinds of bad matches, such as matching the front of the body against depth values from the back of the body.

Parameters:

points_source – [nBatch x nPoints x 3] tensor of source points.
normals_source – [nBatch x nPoints x 3] tensor of source normals (must be normalized).
points_target – [nBatch x nPoints x 3] tensor of target points.
normals_target – [nBatch x nPoints x 3] tensor of target normals (must be normalized).
max_dist – Maximum distance to search, can be used to speed up the method by allowing the search to return early. Defaults to FLT_MAX.
max_normal_dot – Maximum dot product allowed between the source and target normal. Defaults to 0.

Returns:

A tuple of three tensors. The first is [nBatch x nPoints x dim] and contains the closest point for each point in the target set. The second is [nBatch x nPoints] and contains the index of each closest point in the target set (or -1 if none). The third is [nBatch x nPoints] and is a boolean tensor indicating whether a valid closest point was found for each source point.

pymomentum.geometry.joint_parameters_to_local_skeleton_state(character: object, joint_parameters: torch.Tensor) → torch.Tensor

Map from the 7*nJoints jointParameters (representing transforms to the parent joint) to the 8*nJoints local skeleton state.

The skeletonState is stored (tx, ty, tz; rx, ry, rz, rw; s) and each maps the transform from the joint’s local space to its parent joint space. Rotations are Quaternions in the ((x, y, z), w) format. This is deliberately identical to the representation used in mopy.)

Parameters:

character (Union[Character, List[Character]]) – Character to use.
joint_parameters – torch.Tensor containing the (nBatch x nJointParameters) joint parameters.

Returns:

torch.Tensor of size (nBatch x nJoints x 8) containing the skeleton state; should be also compatible with mopy’s skeleton state representation.

pymomentum.geometry.joint_parameters_to_positions(character: object, joint_parameters: torch.Tensor, parents: torch.Tensor, offsets: torch.Tensor) → torch.Tensor

Convert joint parameters to 3D positions relative to skeleton joints using forward kinematics. You can use this (for example) to supervise a model to produce the correct 3D ground truth.

You should prefer model_parameters_to_positions() when working from modelParameters because it is better able to exploit sparsity; this function is provided as a convenience because motion read from external files generally uses jointParameters.

Parameters:

character (Union[Character, List[Character]]) – Character to use.
joint_parameters – Joint parameter tensor, with dimension (nBatch x (7*nJoints)).
parents – Joint parents, on for each target position.
offsets – 3-d offset in each joint’s local space.

Returns:

Tensor of size (nBatch x nParents x 3), representing the world-space position of each point.

pymomentum.geometry.joint_parameters_to_skeleton_state(character: object, joint_parameters: torch.Tensor) → torch.Tensor

Map from the 7*nJoints jointParameters to the 8*nJoints global skeleton state.

The skeletonState is stored (tx, ty, tz; rx, ry, rz, rw; s) and each maps the transform from the joint’s local space to worldspace. Rotations are Quaternions in the ((x, y, z), w) format. This is deliberately identical to the representation used in mopy.)

Parameters:

character (Union[Character, List[Character]]) – Character to use.
joint_parameters – torch.Tensor containing the (nBatch x nJointParameters) joint parameters.

Returns:

torch.Tensor of size (nBatch x nJoints x 8) containing the skeleton state; should be also compatible with mopy’s skeleton state representation.

pymomentum.geometry.load_markers(path: str, main_subject_only: bool = True) → list[pymomentum.geometry.MarkerSequence]

Load 3d mocap marker data from file.

Parameters:

path – A marker data file: .c3d, .gltf, or .trc.
mainSubjectOnly – True to load only one subject’s data.

Returns:

an array of MarkerSequence, one per subject in the file.

pymomentum.geometry.load_motion(gltf_filename: str) → tuple[numpy.ndarray[numpy.float32[m, n]], list[str], numpy.ndarray[numpy.float32[m, 1]], list[str]]

Load a motion sequence from a gltf file.

Unless you can guarantee that the parameters in the motion files match your existing character, you will likely want to retarget the parameters using the mapParameters() function.

Parameters:: gltfFilename – A .gltf file; e.g. character_s0.glb.
Returns:: a tuple [motionData, motionParameterNames, identityData, identityParameterNames].

pymomentum.geometry.local_skeleton_state_to_joint_parameters(character: pymomentum.geometry.Character, local_skel_state: torch.Tensor) → torch.Tensor

Map from the 8*nJoints local skeleton state to the 7*nJoints jointParameters. This performs the following operations:

Removing the translation offset.
Inverting out the pre-rotation.
Converting to Euler angles.

The local skeleton state is stored (tx, ty, tz; rx, ry, rz, rw; s) and each maps the transform from the joint’s local space to its parent joint space. The joint parameters are stored (tx, ty, tz; ry, rz, ry; s) where rotations are in Euler angles and are relative to the parent joint.

Parameters:

character – Character to use.
local_skel_state – torch.Tensor containing the ([nBatch] x nJoints x 8) skeleton state.

Returns:

torch.Tensor of size ([nBatch] x nJoints x 7) containing the joint parameters.

pymomentum.geometry.map_joint_parameters(motion_data: torch.Tensor, source_character: pymomentum.geometry.Character, target_character: pymomentum.geometry.Character) → torch.Tensor

Remap joint parameters from one character to another.

Parameters:

motionData – The source motion data as a [nFrames x (nBones * 7)] torch.Tensor.
sourceCharacter – The source character.
targetCharacter – The target character to remap onto.

Returns:

The motion with the parameters remapped to match the passed-in Character. The fields with no match are filled with zero.

pymomentum.geometry.map_model_parameters(*args, **kwargs)

Overloaded function.

map_model_parameters(motion_data: torch.Tensor, source_parameter_names: list[str], target_character: pymomentum.geometry.Character, verbose: bool = False) -> torch.Tensor

Remap model parameters from one character to another.

Parameters:

motionData – The source motion data as a nFrames x nParams torch.Tensor.
sourceParameterNames – The source parameter names as a list of strings (e.g. c.parameterTransform.name).
targetCharacter – The target character to remap onto.

Returns:

The motion with the parameters remapped to match the passed-in Character. The fields with no match are filled with zero.

map_model_parameters(motion_data: torch.Tensor, source_character: pymomentum.geometry.Character, target_character: pymomentum.geometry.Character, verbose: bool = True) -> torch.Tensor

Remap model parameters from one character to another.

Parameters:

motionData – The source motion data as a nFrames x nParams torch.Tensor.
sourceCharacter – The source character.
targetCharacter – The target character to remap onto.
verbose – If true, print out warnings about missing parameters.

Returns:

The motion with the parameters remapped to match the passed-in Character. The fields with no match are filled with zero.

pymomentum.geometry.model_parameters_to_blend_shape_coefficients(character: pymomentum.geometry.Character, model_parameters: torch.Tensor) → torch.Tensor

Extract the model parameters that correspond to the blend shape coefficients, in the order required to call meth:BlendShape.compute_shape.

Parameters:

character – A character.
model_parameters – A [nBatch x nParams] tensor of model parameters.

Returns:

A [nBatch x nBlendShape] torch.Tensor of blend shape coefficients.

pymomentum.geometry.model_parameters_to_local_skeleton_state(character: object, model_parameters: torch.Tensor) → torch.Tensor

Map from the k modelParameters to the 8*nJoints local skeleton state.

The skeletonState is stored (tx, ty, tz; rx, ry, rz, rw; s) and each maps the transform from the joint’s local space to its parent joint space. Rotations are Quaternions in the ((x, y, z), w) format. This is deliberately identical to the representation used in mopy.)

Parameters:

character (Union[Character, List[Character]]) – Character to use.
model_parameters – torch.Tensor containing the (nBatch x nModelParameters) model parameters.

Returns:

torch.Tensor of size (nBatch x nJoints x 8) containing the skeleton state; should be also compatible with mopy’s skeleton state representation.

pymomentum.geometry.model_parameters_to_positions(character: object, model_parameters: torch.Tensor, parents: torch.Tensor, offsets: torch.Tensor) → torch.Tensor

Convert model parameters to 3D positions relative to skeleton joints using forward kinematics. You can use this (for example) to supervise a model to produce the correct 3D ground truth.

Working directly from modelParameters is preferable to mapping to jointParameters first because it does a better job exploiting the sparsity in the model and therefore can be made somewhat faster.

Parameters:

character (Union[Character, List[Character]]) – Character to use.
model_parameters – Model parameter tensor, with dimension (nBatch x nModelParams).
parents – Joint parents, on for each target position.
offsets – 3-d offset in each joint’s local space.

Returns:

Tensor of size (nBatch x nParents x 3), representing the world-space position of each point.

pymomentum.geometry.model_parameters_to_skeleton_state(character: object, model_parameters: torch.Tensor) → torch.Tensor

Map from the k modelParameters to the 8*nJoints global skeleton state.

The skeletonState is stored (tx, ty, tz; rx, ry, rz, rw; s) and each maps the transform from the joint’s local space to worldspace. Rotations are Quaternions in the ((x, y, z), w) format. This is deliberately identical to the representation used in mopy.)

Parameters:

character (Union[Character, List[Character]]) – Character to use.
model_parameters – torch.Tensor containing the (nBatch x nModelParameters) model parameters.

Returns:

torch.Tensor of size (nBatch x nJoints x 8) containing the skeleton state; should be also compatible with mopy’s skeleton state representation.

pymomentum.geometry.reduce_to_selected_model_parameters(character: pymomentum.geometry.Character, active_parameters: torch.Tensor) → pymomentum.geometry.Character

Strips out unused parameters from the parameter transform.

Parameters:

character – Full-body character.
activeParameters – A boolean tensor marking which parameters should be retained.

Returns:

A new character whose parameter transform only includes the marked parameters.

pymomentum.geometry.replace_rest_mesh(character: pymomentum.geometry.Character, rest_vertex_positions: numpy.ndarray[numpy.float32[m, n]]) → pymomentum.geometry.Character

Return a new Character with the rest mesh positions replaced by the passed-in positions.: Can be used to e.g. bake the blend shapes into the character’s mesh. Does not allow changing the topology.

Parameters:: rest_vertex_positions – nVert x 3 numpy array of vertex positions.

pymomentum.geometry.replace_skeleton_hierarchy(source_character: pymomentum.geometry.Character, target_character: pymomentum.geometry.Character, source_root: str, target_root: str) → pymomentum.geometry.Character

Replaces the part of target_character’s skeleton rooted at target_root with the part of source_character’s skeleton rooted at source_root. This is used e.g. to swap one character’s hand skeleton with another.

Parameters:

source_character – Source character.
target_character – Target character.
source_root – Root of the source skeleton hierarchy to be copied.
target_root – Root of the target skeleton hierarchy to be replaced.

Returns:

A new skeleton that is identical to tgt_skeleton except that everything under target_root has been replaced by the part of source_character rooted at source_root.

pymomentum.geometry.skeleton_state_to_joint_parameters(character: pymomentum.geometry.Character, skel_state: torch.Tensor) → torch.Tensor

Map from the 8*nJoints skeleton state (representing transforms to world-space) to the 7*nJoints jointParameters. This performs the following operations:

Removing the translation offset.
Inverting out the pre-rotation.
Converting to Euler angles.

The skeleton state is stored (tx, ty, tz; rx, ry, rz, rw; s) and transforms from the joint’s local space to world-space. The joint parameters are stored (tx, ty, tz; ry, rz, ry; s) where rotations are in Euler angles and are relative to the parent joint.

Parameters:

character – Character to use.
skel_state – torch.Tensor containing the ([nBatch] x nJoints x 8) skeleton state.

Returns:

torch.Tensor of size ([nBatch] x nJoints x 7) containing the joint parameters.

pymomentum.geometry.strip_joints(character: pymomentum.geometry.Character, joint_names: list[str]) → pymomentum.geometry.Character

Returns a character where the passed-in joints and all joints parented underneath them have been removed.

Parameters:

character – Full-body character.
joint_names – Names of the joints to remove.

Returns:

A new character with only the upper body visible.

pymomentum.geometry.strip_lower_body_vertices(character: pymomentum.geometry.Character) → pymomentum.geometry.Character

Returns a character where all vertices below the waist have been stripped out (without modifying the skeleton). This can be useful for visualization if you don’t want the legs to distract.

Parameters:: character – Full-body character.
Returns:: A new character with only the upper body visible.

pymomentum.geometry.test_character(num_joints: int = 3) → pymomentum.geometry.Character

Create a simple 3-joint test character. This is useful for writing confidence tests that execute quickly and don’t rely on outside files.

The mesh is made by a few vertices on the line segment from (1,0,0) to (1,1,0) and a few dummy faces. The skeleton has three joints: root at (0,0,0), joint1 parented by root, at world-space (0,1,0), and joint2 parented by joint1, at world-space (0,2,0). The character has only one parameter limit: min-max type [-0.1, 0.1] for root.

Parameters:: numJoints – The number of joints in the resulting character.
Returns:: A simple character with 3 joints and 10 model parameters.

pymomentum.geometry.uniform_random_to_model_parameters(character: pymomentum.geometry.Character, unif_noise: torch.Tensor) → torch.Tensor

Convert a uniform noise vector into a valid body pose.

Parameters:

character – The character to use.
unifNoise – A uniform noise tensor, with dimensions (nBatch x nModelParams).

Returns:

A torch.Tensor with dimensions (nBatch x nModelParams).