pymomentum.geometry

Geometry and forward kinematics for momentum models.

class pymomentum.geometry.BlendShape

Bases: pybind11_object

A blend shape basis for facial expressions and corrective shapes. Contains a base mesh and a set of shape vectors that can be linearly combined to create different facial expressions or body shape variations.

__init__(*args, **kwargs)

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.

save(self: pymomentum.geometry.BlendShape, path: str) → None: Save a blend shape basis to a file.

property shape_vectors

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

to_bytes(self: pymomentum.geometry.BlendShape) → bytes: Save a blend shape basis to bytes in memory.

class pymomentum.geometry.Character

Bases: pybind11_object

A complete momentum character including its skeleton and mesh.

__init__(self: pymomentum.geometry.Character, name: str, skeleton: pymomentum.geometry.Skeleton, parameter_transform: pymomentum.geometry.ParameterTransform, *, locators: list[pymomentum.geometry.Locator] = []) → None

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.

bake_blend_shape(self: pymomentum.geometry.Character, blend_weights: numpy.ndarray[numpy.float32]) → pymomentum.geometry.Character

Returns a new Character with blend shapes baked into the mesh.

Parameters:: blend_weights – A 1D array of blend shape weights to apply.
Returns:: A new Character with the blend shapes baked into the mesh and blend shape parameters removed from the parameter transform.

property bind_pose: Get the bind pose for skinning.

property blend_shape

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

clone(self: pymomentum.geometry.Character) → pymomentum.geometry.Character: Performs a deep-copy of the character.

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.

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.
permissive – If true, ignore certain errors during loading.

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.
permissive – If true, ignore certain errors during loading.

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.
permissive – If true, ignore certain errors during loading.

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.
permissive – If true, ignore certain errors during loading.

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_from_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.

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. Note that motion can only be read from GLTF files saved using momentum, which stores model parameters in a custom extension. For GLTF files saved using other software, use load_gltf_with_skel_states().

Parameters:: gltf_filename – 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.

static load_gltf_with_motion_from_bytes(gltf_bytes: bytes) → tuple[pymomentum.geometry.Character, numpy.ndarray[numpy.float32[m, n]], numpy.ndarray[numpy.float32[m, 1]], float]

Load a character and motion from a gltf byte array.

param gltf_bytes:

A bytes containing the GLTF JSON/messagepack data.

return:

a valid Character.

static load_gltf_with_skel_states(gltf_filename: str) → tuple[pymomentum.geometry.Character, numpy.ndarray[numpy.float32], list[float]]

Load a character and a skel state sequence from a gltf file. Unlike load_gltf_with_motion(), this function should work with any GLTF file since it reads the raw transforms from the file and doesn’t require that the Character have a valid parameter transform. Unlike load_gltf_with_motion(), it does not support the proprietary momentum motion format for storing model parameters in GLB.

Parameters:: gltf_filename – A .gltf file; e.g. character_s0.glb.
Returns:: a tuple [Character, skel_states, timestamps], where skel_states is the tensor [n_frames x n_joints x 8] and timestamps is [n_frames]

static load_gltf_with_skel_states_from_bytes(gltf_bytes: bytes) → tuple[pymomentum.geometry.Character, numpy.ndarray[numpy.float32], list[float]]

Load a character and a skeleton state motion sequence from gltf bytes. Unlike load_gltf_with_motion(), this function should work with any GLTF file since it reads the raw transforms from the file and doesn’t require that the Character have a valid parameter transform. Unlike load_gltf_with_motion(), it does not support the proprietary momentum motion format for storing model parameters in GLB.

Parameters:: gltf_bytes – The bytes of a gltf file.
Returns:: a tuple [Character, skel_states, fps], where skel_states is the tensor [nFrames x nJoints x 8].

static load_legacy_json(json_path: str) → pymomentum.geometry.Character

Load a character from a legacy JSON file.

This function directly converts from the deprecated JSON format to momentum::Character, this is a legacy format that has historically been used in mopy but should be considered deprecated.

Parameters:: json_path – Path to the legacy JSON file.
Returns:: A valid Character.

static load_legacy_json_from_bytes(json_bytes: bytes) → pymomentum.geometry.Character

Load a character from legacy JSON bytes.

Parameters:: json_bytes – A bytes object containing the legacy JSON data.
Returns:: A valid Character.

static load_legacy_json_from_string(json_string: str) → pymomentum.geometry.Character

Load a character from a legacy JSON string.

Parameters:: json_string – String containing the legacy JSON data.
Returns:: A valid Character.

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 byte array containing .locators file data.

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. See Locator.

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. See ParameterLimit.

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. See ParameterTransform.

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]

static save_legacy_json(character: pymomentum.geometry.Character, json_path: str) → None

Save a character to legacy JSON format.

This function converts a momentum::Character back to the legacy JSON format for compatibility with existing tools and workflows.

Parameters:

character – The Character to save.
json_path – Path where to save the legacy JSON file.

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. See 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:

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.

skin_skinned_locators(self: pymomentum.geometry.Character, skel_state: torch.Tensor, rest_positions: torch.Tensor | None = None) → torch.Tensor

Apply linear blend skinning to compute the world-space positions of the character’s skinned locators.

This function uses the character’s built-in skinned locators and applies linear blend skinning to compute their world-space positions given a skeleton state.

Parameters:

skel_state – Skeleton state tensor with shape [nJoints x 8] or [nBatch x nJoints x 8].
rest_positions – Optional rest positions tensor with shape [nLocators x 3] or [nBatch x nLocators x 3]. If not provided, uses the position stored in each SkinnedLocator.

Returns:

Tensor of shape [nLocators x 3] or [nBatch x nLocators x 3] containing the world-space positions of the skinned locators.

property skin_weights: The character’s skinning weights. See SkinWeights.

property skinned_locators: List of skinned locators on the mesh.

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

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

Convert a character to legacy JSON string.

Parameters:: character – The Character to convert.
Returns:: String containing the legacy JSON representation.

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 | None, 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_collision_geometry(self: pymomentum.geometry.Character, arg0: list[pymomentum.geometry.TaperedCapsule]) → pymomentum.geometry.Character: Returns a new Character with the collision geometry replaced.

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.

with_skinned_locators(self: pymomentum.geometry.Character, skinned_locators: list[pymomentum.geometry.SkinnedLocator], replace: bool = False) → pymomentum.geometry.Character

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

parameter skinned_locators:

The skinned locators to add to the character.

parameter replace:

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

class pymomentum.geometry.FBXCoordSystem

Bases: pybind11_object

Members:

RightHanded

LeftHanded

LeftHanded = <FBXCoordSystem.LeftHanded: 1>

RightHanded = <FBXCoordSystem.RightHanded: 0>

__init__(self: pymomentum.geometry.FBXCoordSystem, value: int) → None

property name

property value

class pymomentum.geometry.FBXCoordSystemInfo

Bases: pybind11_object

FBX coordinate system information containing up vector, front vector, and handedness. Used when importing/exporting FBX files to ensure proper coordinate system conversion.

__init__(self: pymomentum.geometry.FBXCoordSystemInfo, upVector: pymomentum.geometry.FBXUpVector, frontVector: pymomentum.geometry.FBXFrontVector, coordSystem: pymomentum.geometry.FBXCoordSystem) → None

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

__init__(self: pymomentum.geometry.FBXFrontVector, value: int) → None

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

__init__(self: pymomentum.geometry.FBXUpVector, value: int) → None

property name

property value

class pymomentum.geometry.GltfBuilder

Bases: pybind11_object

A builder class for creating GLTF files with multiple characters and animations.

The GltfBuilder allows you to incrementally construct a GLTF scene by adding characters, meshes, motions, and marker data. This is useful for creating complex scenes with multiple characters or combining different types of data into a single GLTF file.

__init__(self: pymomentum.geometry.GltfBuilder, fps: float = 120.0) → None

Create a new GltfBuilder with the specified frame rate.

Parameters:: fps – Frame rate in frames per second for animations.

add_character(self: pymomentum.geometry.GltfBuilder, character: pymomentum.geometry.Character, position_offset: numpy.ndarray[numpy.float32[3, 1]] | None = None, rotation_offset: numpy.ndarray[numpy.float32[4, 1]] | None = None, add_extensions: bool = True, add_collisions: bool = True, add_locators: bool = True, add_mesh: bool = True) → None

Add a character to the GLTF scene.

Each character will have a root node with the character’s name as the parent of the skeleton root and the character mesh. Position and rotation offsets can be provided as an initial transform for the character.

Parameters:

character – The character to add to the scene.
position_offset – Translation offset for the character’s root node. Defaults to zero vector if None.
rotation_offset – Rotation offset as a quaternion in (x,y,z,w) format. Defaults to identity quaternion if None.
add_extensions – Whether to add momentum extensions to GLTF nodes.
add_collisions – Whether to add collision geometry to the scene.
add_locators – Whether to add locator data to the scene.
add_mesh – Whether to add the character’s mesh to the scene.

add_marker_sequence(self: pymomentum.geometry.GltfBuilder, fps: float, marker_sequence: list[list[pymomentum.geometry.Marker]], marker_mesh: pymomentum.geometry.MarkerMesh = <MarkerMesh.NoMesh: 0>, anim_name: str = 'default') → None

Add marker sequence animation data to the GLTF scene.

This method adds motion capture marker data to the GLTF file. The marker data represents 3D positions of markers over time, which can be used for motion capture analysis or visualization. Optional marker mesh visualization can be added as unit cubes.

Parameters:

fps – Frame rate in frames per second for the marker sequence data.
marker_sequence – A 2D list/array with shape [numFrames][numMarkers] containing Marker objects for each frame. Each Marker contains name, position, and occlusion status.
marker_mesh – Type of mesh to represent markers visually using MarkerMesh enum. Default is MarkerMesh.None for no visual representation. MarkerMesh.UnitCube displays markers as unit cubes.
anim_name – Custom name for the marker animation in the GLTF file.

add_mesh(self: pymomentum.geometry.GltfBuilder, mesh: pymomentum.geometry.Mesh, name: str, add_color: bool = False) → None

Add a static mesh to the GLTF scene.

This can be used to add environment meshes, target scans, or other static geometry that doesn’t require animation. The mesh will be added as a separate node in the scene with the specified name.

Parameters:

mesh – The mesh to add to the scene.
name – Name for the mesh node in the GLTF scene.
add_color – Whether to include vertex colors if present in the mesh.

add_motion(self: pymomentum.geometry.GltfBuilder, 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, add_extensions: bool = True, custom_name: str = 'default') → None

Add a motion sequence to the specified character.

If addCharacter has not been called before adding the motion, the character will be automatically added with default settings. The motion data contains model parameters that animate the character over time.

Parameters:

character – The character to add motion for.
fps – Frame rate in frames per second for the motion data.
motion – Optional motion parameters as a tuple of (parameter_names, motion_data). Motion data should be a matrix with shape [n_frames x n_parameters].
offsets – Optional identity parameters as a tuple of (joint_names, offset_data). Offset data should be a vector with shape [n_joints * 7].
add_extensions – Whether to add momentum extensions to GLTF nodes.
custom_name – Custom name for the animation in the GLTF file.

add_skeleton_states(self: pymomentum.geometry.GltfBuilder, character: pymomentum.geometry.Character, fps: float, skeleton_states: numpy.ndarray[numpy.float32], custom_name: str = 'default') → None

Add skeleton states animation to the specified character.

If addCharacter has not been called before adding the skeleton states, the character will be automatically added with default settings. The skeleton states contain per-joint transforms that define the character’s pose over time.

Parameters:

character – The character to add skeleton states for.
fps – Frame rate in frames per second for the skeleton state data.
skeleton_states – Skeleton states as a 3D array with shape [nFrames, nJoints, 8]. Each joint state contains [tx, ty, tz, rx, ry, rz, rw, s] where translation is (tx,ty,tz), rotation is quaternion (rx,ry,rz,rw) in (x,y,z,w) format, and s is scale.
custom_name – Custom name for the animation in the GLTF file.

property fps

The frame rate in frames per second used for animations.

This property controls the timing of all animations added to the GLTF file. Setting this value will affect subsequently added motions and animations.

Type:: float

save(self: pymomentum.geometry.GltfBuilder, filename: str, file_format: pymomentum.geometry.GltfFileFormat | None = None) → None

Save the GLTF scene to a file.

This method writes the constructed GLTF scene to the specified file. The file format can be explicitly specified or automatically deduced from the file extension.

Parameters:

filename – Path where to save the GLTF file.
file_format – Optional file format specification using GltfFileFormat enum. If not provided, format will be deduced from filename extension.

to_bytes(self: pymomentum.geometry.GltfBuilder, file_format: Optional[pymomentum.geometry.GltfFileFormat] = <GltfFileFormat.GltfBinary: 1>) → bytes

Convert the GLTF scene to bytes in memory.

This method serializes the constructed GLTF scene to a byte array without writing to disk. This is useful for programmatic processing, network transmission, or when you need the GLTF data as bytes for other purposes.

Returns:: The GLTF scene as bytes. For GltfBinary format, this will be GLB binary data. For GltfAscii format, this will be JSON text encoded as UTF-8 bytes.

class pymomentum.geometry.GltfFileFormat

Bases: pybind11_object

Members:

Extension

GltfBinary

GltfAscii

Extension = <GltfFileFormat.Extension: 0>

GltfAscii = <GltfFileFormat.GltfAscii: 2>

GltfBinary = <GltfFileFormat.GltfBinary: 1>

__init__(self: pymomentum.geometry.GltfFileFormat, value: int) → None

property name

property value

class pymomentum.geometry.InverseParameterTransform

Bases: pybind11_object

Inverse parameter transform that maps from full joint parameters back to reduced model parameters. Used for fitting model parameters to existing joint parameter data.

__init__(*args, **kwargs)

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

A single joint in a character skeleton. Contains the joint’s name, parent relationship, pre-rotation, and translation offset from its parent joint.

__init__(self: pymomentum.geometry.Joint, name: str, parent: int, pre_rotation: numpy.ndarray[numpy.float32[4, 1]], translation_offset: numpy.ndarray[numpy.float32[3, 1]]) → None

property name: Returns the name of the joint.

property parent: Returns the index of the parent joint (-1 if it has no parent)

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

property pre_rotation_matrix

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

class pymomentum.geometry.LimitData

Bases: pybind11_object

Data container for parameter limits. Contains the specific constraint data for different limit types (MinMax, Linear, Ellipsoid, etc.).

__init__(*args, **kwargs)

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

Ellipsoid constraint data for model parameters. Enforces that parameters lie within an ellipsoid defined by a transformation matrix and offset.

__init__(*args, **kwargs)

property ellipsoid

property ellipsoid_inv

property ellipsoid_parent

property offset

property parent

class pymomentum.geometry.LimitHalfPlane

Bases: pybind11_object

Half-plane constraint data for model parameters. Enforces that parameters lie on one side of a plane defined by a normal vector and offset.

__init__(*args, **kwargs)

property normal

property offset

property param1_index

property param2_index

class pymomentum.geometry.LimitLinear

Bases: pybind11_object

Linear constraint data for model parameters. Enforces a linear relationship between two parameters of the form: p0 = scale * p1 + offset.

__init__(*args, **kwargs)

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

Linear constraint data for joint parameters. Enforces a linear relationship between two joint parameters of the form: p0 = scale * p1 + offset.

__init__(*args, **kwargs)

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

Min/max constraint data for model parameters. Contains the parameter index and the minimum and maximum allowed values.

__init__(*args, **kwargs)

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

Min/max constraint data for joint parameters. Contains the joint index, joint parameter index, and the minimum and maximum allowed values.

__init__(*args, **kwargs)

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

__init__(self: pymomentum.geometry.LimitType, value: int) → None

property name

property value

class pymomentum.geometry.Locator

Bases: pybind11_object

A 3D point attached to a skeleton joint used for inverse kinematics constraints. Locators define target positions that the character should reach during pose optimization, with configurable weights and axis locks for fine-grained control.

__init__(self: pymomentum.geometry.Locator, name: str = 'uninitialized', parent: int = 18446744073709551615, offset: numpy.ndarray[numpy.float32[3, 1]] = array([0., 0., 0.], dtype=float32), locked: numpy.ndarray[numpy.int32[3, 1]] = array([0, 0, 0], dtype=int32), weight: float = 1.0, limit_origin: numpy.ndarray[numpy.float32[3, 1]] = array([0., 0., 0.], dtype=float32), limit_weight: numpy.ndarray[numpy.float32[3, 1]] = array([0., 0., 0.], dtype=float32)) → None

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

A 3D marker used in motion capture systems. Contains position data and occlusion status for tracking points on subjects during motion capture recording.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pymomentum.geometry.Marker) -> None
__init__(self: pymomentum.geometry.Marker, name: str, pos: numpy.ndarray[numpy.float64[3, 1]], occluded: bool) -> None

Create a marker with the specified properties.

param name:

The name of the marker

param pos:

The 3D position of the marker

param occluded:

Whether the marker is occluded with no position info

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.MarkerMesh

Bases: pybind11_object

Members:

NoMesh

UnitCube

NoMesh = <MarkerMesh.NoMesh: 0>

UnitCube = <MarkerMesh.UnitCube: 1>

__init__(self: pymomentum.geometry.MarkerMesh, value: int) → None

property name

property value

class pymomentum.geometry.MarkerSequence

Bases: pybind11_object

A sequence of motion capture marker data over time. Contains marker positions and occlusion status for each frame, along with frame rate information.

__init__(self: pymomentum.geometry.MarkerSequence) → None

property fps: Frame rate

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

property name: Name of the subject

class pymomentum.geometry.Mesh

Bases: pybind11_object

A 3D mesh containing vertices, faces, normals, and optional texture coordinates. Supports triangular meshes with additional data like vertex colors, confidence values, and line segments for wireframe rendering.

__init__(self: pymomentum.geometry.Mesh, vertices: numpy.ndarray[numpy.float32], faces: numpy.ndarray[numpy.int32], *, normals: numpy.ndarray[numpy.float32] | None = None, lines: list[list[int]] = [], colors: numpy.ndarray[numpy.uint8] | None = None, confidence: list[float] = [], texcoords: numpy.ndarray[numpy.float32] | None = None, texcoord_faces: numpy.ndarray[numpy.int32] | None = None, texcoord_lines: list[list[int]] = []) → None

Parameters:

vertices – n x 3 array of vertex locations.
faces – n x 3 array of triangles.
normals – Optional n x 3 array of vertex normals. If not passed in, vertex normals will be computed automatically.
lines – Optional list of lines, where each line is a list of vertex indices.
colors – Optional n x 3 array of vertex colors.
confidence – Optional n x 1 array of vertex confidence values.
texcoords – Optional n x 2 array of texture coordinates.
texcoord_faces – Optional n x 3 array of triangles in the texture map. Each triangle corresponds to a triangle on the mesh, but indices should refer to the texcoord array.
texcoord_lines – Optional list of lines, where each line is a list of texture coordinate indices.

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.

self_intersections(self: pymomentum.geometry.Mesh) → numpy.ndarray: Test if the mesh self intersects anywhere and return all intersecting face pairs

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.

with_updated_normals(self: pymomentum.geometry.Mesh) → pymomentum.geometry.Mesh

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

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pymomentum.geometry.Mppca) -> None
__init__(self: pymomentum.geometry.Mppca, pi: numpy.ndarray[numpy.float64[m, 1]], mu: numpy.ndarray[numpy.float64[m, n]], W: numpy.ndarray[numpy.float64], sigma: numpy.ndarray[numpy.float64[m, 1]], names: list[str]) -> None

Construct an Mppca model from numpy arrays. :param pi: The (nModels) mixture weights :param mu: The (nModels x dimension) mean vectors. :param W: The (nModels x dimension x nParams) weight matrices. :param sigma2: The (nModels) squared sigma uniform variance parameters. :param names: The (nDimension) names of the affected parameters.

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

A constraint on model or joint parameters used to enforce realistic poses. Supports various limit types including min/max bounds, linear relationships, ellipsoid constraints, and half-plane constraints.

__init__(*args, **kwargs)

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

Maps reduced model parameters to full joint parameters for character animation. This class handles the transformation from a compact set of model parameters (typically ~50) used in optimization to the full 7*nJoints parameters needed for skeleton posing.

__init__(self: pymomentum.geometry.ParameterTransform, names: list[str], skeleton: pymomentum.geometry.Skeleton, transform: scipy.sparse.csr_matrix[numpy.float32]) → None

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

A hierarchical skeleton structure containing joints with parent-child relationships. Each joint has a name, parent index, pre-rotation, and translation offset. Used for character animation and forward kinematics.

__init__(self: pymomentum.geometry.Skeleton, joint_list: list[pymomentum.geometry.Joint]) → None

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 joints

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

Linear blend skinning weights that define how mesh vertices are influenced by skeleton joints. Contains weight values and joint indices for each vertex, enabling smooth deformation of the mesh during character animation.

__init__(self: pymomentum.geometry.SkinWeights, index: numpy.ndarray[numpy.int32[m, n]], weights: numpy.ndarray[numpy.float32[m, n]]) → None

property index: Returns the skinning indices.

property weight: Returns the skinning weights.

class pymomentum.geometry.SkinnedLocator

Bases: pybind11_object

__init__(self: pymomentum.geometry.SkinnedLocator, name: str, parents: numpy.ndarray[numpy.int32[m, 1]], skin_weights: numpy.ndarray[numpy.float32[m, 1]], position: numpy.ndarray[numpy.float32[3, 1]] | None = None, weight: float = 1.0) → None

property name: The skinned locator’s name.

property parents: Indices of the parent joints in the skeleton.

property position: Position relative to rest pose of the character.

property skin_weights: Skinning weights for the parent joints.

property weight: Influence weight of this locator when used in constraints.

class pymomentum.geometry.TaperedCapsule

Bases: pybind11_object

A tapered capsule primitive used for collision detection and physics simulation. Represents a capsule with potentially different radii at each end, attached to a skeleton joint.

__init__(self: pymomentum.geometry.TaperedCapsule, parent: int, transformation: numpy.ndarray[numpy.float32[4, 4]] | None = None, radius: numpy.ndarray[numpy.float32[2, 1]] | None = None, length: float = 1.0) → None

Create a capsule using its transformation, radius, parent and length.

Parameters:

transformation – Transformation defining the orientation and starting point relative to the parent coordinate system.
radius – Start and end radius for the capsule.
parent – Parent joint to which the capsule is attached.
length – Length of the capsule in local space.

property length

property parent: Parent joint to which the capsule is attached.

property radius: Start and end radius for the capsule.

property transformation: Transformation defining the orientation and starting point relative to the parent coordinate system

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.
model_parameters – 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_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.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.find_closest_points_on_mesh(points_source: torch.Tensor, vertices_target: torch.Tensor, faces_target: torch.Tensor) → tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

For each point in the points_source tensor, find the closest point in the target mesh.

param points_source:

[nBatch x nPoints x 3] tensor of source points.

param vertices_target:

[nBatch x nPoints x 3] tensor of target vertices.

param faces_target:

[nBatch x nPoints x 3] tensor of target faces.

return:

A tuple of three tensors, (valid, points, face_index, bary). The first is [nBatch x nPoints] and specifies if the closest point result is valid. The second is [nBatch x nPoints x 3] and contains the actual closest point (or 0, 0, 0 if invalid). The third is [nBatch x nPoints] and contains the index of the closest face (or -1 if invalid). The fourth is [nBatch x nPoints x 3] and contains the barycentric coordinates of the closest point on the face (or 0, 0, 0 if invalid).

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 a legacy format.)

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 a legacy format’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 a legacy format.)

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 a legacy format’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 a legacy format.)

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 a legacy format’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 a legacy format.)

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 a legacy format’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.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).