Python API Reference

This page provides detailed documentation for the Python API of the py-dem-bones package. For a high-level overview of the API, see the API Reference page.

Core Classes

class py_dem_bones.DemBones

Bases: pybind11_object

Smooth skinning decomposition with rigid bones and sparse, convex weights

__init__(self: py_dem_bones._py_dem_bones.DemBones) → None
classmethod __new__(*args, **kwargs)
clear(self: py_dem_bones._py_dem_bones.DemBones) → None
compute(self: py_dem_bones._py_dem_bones.DemBones) → None
computeTranformations(self: py_dem_bones._py_dem_bones.DemBones) → None
computeWeights(self: py_dem_bones._py_dem_bones.DemBones) → None
property fStart
property fv
get_animated_poses(self: py_dem_bones._py_dem_bones.DemBones) → numpy.ndarray[numpy.float64[m, n]]
get_rest_pose(self: py_dem_bones._py_dem_bones.DemBones) → numpy.ndarray[numpy.float64[m, n]]
get_transformations(self: py_dem_bones._py_dem_bones.DemBones) → numpy.ndarray[numpy.float64]
get_weights(self: py_dem_bones._py_dem_bones.DemBones) → numpy.ndarray[numpy.float64]
init(self: py_dem_bones._py_dem_bones.DemBones) → None
property iter
property iterTransformations
property iterWeights
property lockM
property lockW
property m
property nB
property nF
property nInitIters
property nIters
property nS
property nTransIters
property nV
property nWeightsIters
property nnz
rmse(self: py_dem_bones._py_dem_bones.DemBones) → float
set_animated_poses(self: py_dem_bones._py_dem_bones.DemBones, arg0: numpy.ndarray[numpy.float64[m, n]]) → None
set_rest_pose(self: py_dem_bones._py_dem_bones.DemBones, arg0: numpy.ndarray[numpy.float64[m, n]]) → None
set_transformations(self: py_dem_bones._py_dem_bones.DemBones, arg0: numpy.ndarray[numpy.float64[m, n]]) → None
set_weights(self: py_dem_bones._py_dem_bones.DemBones, arg0: numpy.ndarray[numpy.float64[m, n]]) → None
property subjectID
property transAffine
property transAffineNorm
property u
property v
property weightEps
property weightsSmooth
property weightsSmoothStep
class py_dem_bones.DemBonesExt

Bases: pybind11_object

Extended class to handle hierarchical skeleton with local rotations/translations and bind matrices

__init__(self: py_dem_bones._py_dem_bones.DemBonesExt) → None
classmethod __new__(*args, **kwargs)
property bind
property bindUpdate
property boneName
clear(self: py_dem_bones._py_dem_bones.DemBonesExt) → None
compute(self: py_dem_bones._py_dem_bones.DemBonesExt) → None
computeRTB(self: py_dem_bones._py_dem_bones.DemBonesExt) → None
computeTranformations(self: py_dem_bones._py_dem_bones.DemBonesExt) → None
computeWeights(self: py_dem_bones._py_dem_bones.DemBonesExt) → None
property fStart
property fTime
property fv
get_animated_poses(self: py_dem_bones._py_dem_bones.DemBonesExt) → numpy.ndarray[numpy.float64[m, n]]
get_bone_names(self: py_dem_bones._py_dem_bones.DemBonesExt) → list[str]
get_rest_pose(self: py_dem_bones._py_dem_bones.DemBonesExt) → numpy.ndarray[numpy.float64[m, n]]
get_transformations(self: py_dem_bones._py_dem_bones.DemBonesExt) → numpy.ndarray[numpy.float64]
get_weights(self: py_dem_bones._py_dem_bones.DemBonesExt) → numpy.ndarray[numpy.float64]
init(self: py_dem_bones._py_dem_bones.DemBonesExt) → None
property iter
property iterTransformations
property iterWeights
property lockM
property lockW
property m
property nB
property nF
property nInitIters
property nIters
property nS
property nTransIters
property nV
property nWeightsIters
property nnz
property parent
rmse(self: py_dem_bones._py_dem_bones.DemBonesExt) → float
set_animated_poses(self: py_dem_bones._py_dem_bones.DemBonesExt, arg0: numpy.ndarray[numpy.float64[m, n]]) → None
set_bone_names(self: py_dem_bones._py_dem_bones.DemBonesExt, arg0: list[str]) → None
set_rest_pose(self: py_dem_bones._py_dem_bones.DemBonesExt, arg0: numpy.ndarray[numpy.float64[m, n]]) → None
set_transformations(self: py_dem_bones._py_dem_bones.DemBonesExt, arg0: numpy.ndarray[numpy.float64[m, n]]) → None
set_weights(self: py_dem_bones._py_dem_bones.DemBonesExt, arg0: numpy.ndarray[numpy.float64[m, n]]) → None
property subjectID
property transAffine
property transAffineNorm
property u
property v
property weightEps
property weightsSmooth
property weightsSmoothStep

Wrapper Classes

class py_dem_bones.DemBonesWrapper

Bases: object

Python wrapper for the DemBones C++ class.

This class provides a more Pythonic interface to the C++ DemBones class, adding support for named bones, error handling, and convenience methods.

__init__()

Initialize a new DemBonesWrapper instance.

property num_bones

Get the number of bones.

property num_vertices

Get the number of vertices.

property num_frames

Get the number of animation frames.

property num_targets

Get the number of target poses.

property num_iterations

Get the total number of iterations.

property weight_smoothness

Get the weight smoothness parameter.

property max_influences

Get the maximum number of non-zero weights per vertex.

property bone_names

Get all bone names as a list, ordered by bone index.

get_bone_names()

Get all bone names as a list.

Returns:

List of bone names

Return type:

list

get_bone_index(name)

Get the index for a bone name.

Parameters:

name (str) – The bone name

Returns:

The bone index

Return type:

int

Raises:

NameError – If the bone name is not found

set_bone_name(name, index=None)

Set a bone name to index mapping.

Parameters:

  • name (str) – The bone name

  • index (int, optional) – The bone index. If None, uses the next available index.

Returns:

The assigned bone index

Return type:

int

set_bone_names(*names)

Set multiple bone names at once.

Parameters:

*names – Variable number of bone names

Returns:

The assigned bone indices

Return type:

list

property target_names

Get all target names as a list, ordered by target index.

get_target_names()

Get all target names as a list.

Returns:

List of target names

Return type:

list

get_target_index(name)

Get the index for a target name.

Parameters:

name (str) – The target name

Returns:

The target index

Return type:

int

Raises:

NameError – If the target name is not found

set_target_name(name, index=None)

Set a target name to index mapping.

Parameters:

  • name (str) – The target name

  • index (int, optional) – The target index. If None, uses the next available index.

Returns:

The assigned target index

Return type:

int

get_bind_matrix(bone)

Get the bind matrix for a bone.

Parameters:

bone (str or int) – The bone name or index

Returns:

The 4x4 bind matrix

Return type:

numpy.ndarray

set_bind_matrix(bone, matrix)

Set the bind matrix for a bone.

Parameters:

  • bone (str or int) – The bone name or index

  • matrix (numpy.ndarray) – The 4x4 transform matrix

get_weights()

Get the weight matrix.

Returns:

The weights matrix with shape [num_bones, num_vertices]

Return type:

numpy.ndarray

set_weights(weights)

Set the weight matrix.

Parameters:

weights (numpy.ndarray) – The weights matrix with shape [num_bones, num_vertices]

set_rest_pose(vertices)

Set the rest pose vertices.

Parameters:

vertices (numpy.ndarray) – The rest pose vertices with shape [3, num_vertices]

set_target_vertices(target, vertices)

Set the vertices for a target pose.

Parameters:

  • target (str or int) – The target name or index

  • vertices (numpy.ndarray) – The target vertices with shape [3, num_vertices]

get_transformations()

Get the transformation matrices for all bones.

Returns:

Array of 4x4 transformation matrices with shape [num_frames, 4, 4]

Return type:

numpy.ndarray

set_transformations(transformations)

Set the transformation matrices for all bones.

Parameters:

transformations (numpy.ndarray) – Array of 4x4 transformation matrices with shape [num_frames, 4, 4]

compute()

Compute the skinning weights and transformations.

Returns:

True if computation succeeded

Return type:

bool

Raises:

ComputationError – If the computation fails

clear()

Clear all data and reset the computation.

class py_dem_bones.DemBonesExtWrapper

Bases: DemBonesWrapper

Python wrapper for the DemBonesExt C++ class.

This class extends DemBonesWrapper with additional functionality provided by the DemBonesExt C++ class, such as advanced skinning algorithms.

property bone_names

Get all bone names as a list, ordered by bone index.

clear()

Clear all data and reset the computation.

compute()

Compute the skinning weights and transformations.

Returns:

True if computation succeeded

Return type:

bool

Raises:

ComputationError – If the computation fails

get_bind_matrix(bone)

Get the bind matrix for a bone.

Parameters:

bone (str or int) – The bone name or index

Returns:

The 4x4 bind matrix

Return type:

numpy.ndarray

get_bone_index(name)

Get the index for a bone name.

Parameters:

name (str) – The bone name

Returns:

The bone index

Return type:

int

Raises:

NameError – If the bone name is not found

get_bone_names()

Get all bone names as a list.

Returns:

List of bone names

Return type:

list

get_target_index(name)

Get the index for a target name.

Parameters:

name (str) – The target name

Returns:

The target index

Return type:

int

Raises:

NameError – If the target name is not found

get_target_names()

Get all target names as a list.

Returns:

List of target names

Return type:

list

get_transformations()

Get the transformation matrices for all bones.

Returns:

Array of 4x4 transformation matrices with shape [num_frames, 4, 4]

Return type:

numpy.ndarray

get_weights()

Get the weight matrix.

Returns:

The weights matrix with shape [num_bones, num_vertices]

Return type:

numpy.ndarray

property max_influences

Get the maximum number of non-zero weights per vertex.

property num_bones

Get the number of bones.

property num_frames

Get the number of animation frames.

property num_iterations

Get the total number of iterations.

property num_targets

Get the number of target poses.

property num_vertices

Get the number of vertices.

set_bind_matrix(bone, matrix)

Set the bind matrix for a bone.

Parameters:

  • bone (str or int) – The bone name or index

  • matrix (numpy.ndarray) – The 4x4 transform matrix

set_bone_name(name, index=None)

Set a bone name to index mapping.

Parameters:

  • name (str) – The bone name

  • index (int, optional) – The bone index. If None, uses the next available index.

Returns:

The assigned bone index

Return type:

int

set_bone_names(*names)

Set multiple bone names at once.

Parameters:

*names – Variable number of bone names

Returns:

The assigned bone indices

Return type:

list

set_rest_pose(vertices)

Set the rest pose vertices.

Parameters:

vertices (numpy.ndarray) – The rest pose vertices with shape [3, num_vertices]

set_target_name(name, index=None)

Set a target name to index mapping.

Parameters:

  • name (str) – The target name

  • index (int, optional) – The target index. If None, uses the next available index.

Returns:

The assigned target index

Return type:

int

set_target_vertices(target, vertices)

Set the vertices for a target pose.

Parameters:

  • target (str or int) – The target name or index

  • vertices (numpy.ndarray) – The target vertices with shape [3, num_vertices]

set_transformations(transformations)

Set the transformation matrices for all bones.

Parameters:

transformations (numpy.ndarray) – Array of 4x4 transformation matrices with shape [num_frames, 4, 4]

set_weights(weights)

Set the weight matrix.

Parameters:

weights (numpy.ndarray) – The weights matrix with shape [num_bones, num_vertices]

property target_names

Get all target names as a list, ordered by target index.

property weight_smoothness

Get the weight smoothness parameter.

__init__()

Initialize a new DemBonesExtWrapper instance.

property bind_update

Get the bind update parameter.

Exception Classes

class py_dem_bones.DemBonesError

Bases: Exception

Base class for all py-dem-bones exceptions.

__init__(*args, **kwargs)
classmethod __new__(*args, **kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class py_dem_bones.ParameterError

Bases: DemBonesError

Exception raised for invalid parameter values.

This exception is raised when a function or method receives a parameter with an invalid value, such as incorrect array shapes, types, or ranges.

__init__(*args, **kwargs)
classmethod __new__(*args, **kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class py_dem_bones.ComputationError

Bases: DemBonesError

Exception raised when computation fails.

This exception is raised when the core computation algorithm fails, for example due to numerical instability or invalid input data.

__init__(*args, **kwargs)
classmethod __new__(*args, **kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class py_dem_bones.IndexError

Bases: DemBonesError

Exception raised for invalid indices.

This exception is raised when an index is out of range, for example when trying to access a bone index that exceeds the number of bones.

__init__(*args, **kwargs)
classmethod __new__(*args, **kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class py_dem_bones.NameError

Bases: DemBonesError

Exception raised for name-related errors.

This exception is raised when a name-to-index mapping fails, for example when trying to retrieve a bone index for a non-existent bone name.

__init__(*args, **kwargs)
classmethod __new__(*args, **kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class py_dem_bones.ConfigurationError

Bases: DemBonesError

Exception raised for configuration errors.

This exception is raised when there are problems with the configuration of the algorithm or incompatible settings.

__init__(*args, **kwargs)
classmethod __new__(*args, **kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class py_dem_bones.NotImplementedError

Bases: DemBonesError

Exception raised for unimplemented features.

This exception is raised when a feature described in the API is not yet implemented.

__init__(*args, **kwargs)
classmethod __new__(*args, **kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class py_dem_bones.IOError

Bases: DemBonesError

Exception raised for input/output errors.

This exception is raised when operations involving file I/O or data exchange with external software fail.

__init__(*args, **kwargs)
classmethod __new__(*args, **kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Utility Functions

py_dem_bones.numpy_to_eigen(array)

Convert a numpy array to an Eigen-compatible format.

Parameters:

array (numpy.ndarray) – Input numpy array

Returns:

Array in Eigen-compatible format

Return type:

numpy.ndarray

py_dem_bones.eigen_to_numpy(array, shape=None)

Convert an Eigen matrix to a numpy array.

Parameters:

  • array – Eigen matrix (already converted to numpy by pybind11)

  • shape (tuple, optional) – Reshape the array to this shape

Returns:

Numpy array

Return type:

numpy.ndarray

Interfaces

class py_dem_bones.DCCInterface

Bases: ABC

Abstract base class for DCC software integration.

This class defines methods that must be implemented by any class that wants to provide integration between py-dem-bones and a specific DCC software application.

abstractmethod from_dcc_data(**kwargs)

Import data from DCC software into DemBones.

This method should convert data structures specific to the DCC software into the format required by the DemBones library.

Parameters:

**kwargs – DCC-specific parameters

Returns:

True if import was successful

Return type:

bool

abstractmethod to_dcc_data(**kwargs)

Export DemBones data to DCC software.

This method should convert DemBones data structures into the format required by the DCC software.

Parameters:

**kwargs – DCC-specific parameters

Returns:

True if export was successful

Return type:

bool

abstractmethod convert_matrices(matrices, from_dcc=True)

Convert between DCC-specific and DemBones matrix formats.

Many DCC software applications use different coordinate systems, matrix layouts, or conventions than those used by DemBones. This method handles the conversion between these formats.

Parameters:

  • matrices – The matrices to convert

  • from_dcc (bool) – If True, convert from DCC format to DemBones format, otherwise convert from DemBones format to DCC format

Returns:

The converted matrices

apply_coordinate_system_transform(data, from_dcc=True)

Apply coordinate system transformations.

This is a utility method to handle coordinate system differences between DCC software and DemBones. The base implementation is a no-op that returns the data unchanged. Subclasses should override this method if the DCC software uses a different coordinate system.

Parameters:

  • data – The data to transform

  • from_dcc (bool) – If True, transform from DCC to DemBones coordinate system, otherwise transform from DemBones to DCC coordinate system

Returns:

The transformed data