ke.animation

Skeleton hierarchies, motion clips, pose state, and skinning helpers.

Scene/render visual bridge classes are documented under kangengine.visual. The native binding may still contain implementation types for these bridges, but the public kangengine.animation module removes them. Python code should use ke.visual.ArticulationVisual or ke.visual.SkeletalVisual for viewer-side objects.

API overview

SkeletonTree	Read-only skeleton hierarchy and local bind transforms.
SkeletonMotion	Sampled skeleton animation with root motion and local rotations.
SkeletonState	Skeleton pose stored as root translation and S node rotations.
Transform	Forward-kinematics transform result.
cpu_skin	CPU-skin bind-space positions and normals.

kangengine.animation.cpu_skin(

bind_positions: npt.ArrayLike | torch.Tensor,

bind_normals: npt.ArrayLike | torch.Tensor,

skin_bone_indices: npt.ArrayLike | torch.Tensor,

skin_bone_weights: npt.ArrayLike | torch.Tensor,

skin_bone_node_indices: npt.ArrayLike | torch.Tensor,

inverse_bind_matrices: npt.ArrayLike | torch.Tensor,

skeleton_global_matrices: npt.ArrayLike | torch.Tensor,

) → dict[str, numpy.typing.NDArray[numpy.float32]][native]

CPU-skin bind-space positions and normals.

Shapes use V=vertices, B=skin bones, and S=skeleton nodes.

Parameters:

• bind_positions – Float32 vertex positions with shape (V, 3).

• bind_normals – Float32 vertex normals with shape (V, 3).

• skin_bone_indices – Int32 skin-bone indices with shape (V, 4).

• skin_bone_weights – Float32 skin-bone weights with shape (V, 4).

• skin_bone_node_indices – Bone-to-node map with shape (B,).

• inverse_bind_matrices – Float32 transforms with shape (B, 4, 4).

• skeleton_global_matrices – Skeleton globals with shape (S, 4, 4).

Returns:

Float32 positions and normals arrays with shape (V, 3).

kangengine.animation.compute_skinning_matrices(

skin_bone_node_indices: npt.ArrayLike | torch.Tensor,

inverse_bind_matrices: npt.ArrayLike | torch.Tensor,

skeleton_global_matrices: npt.ArrayLike | torch.Tensor,

) → numpy.typing.NDArray[numpy.float32][native]

Return skinning matrices (B, 4, 4) from B skin bones and S nodes.

kangengine.animation.compute_skinning_matrices_into(

skin_bone_node_indices: npt.ArrayLike | torch.Tensor,

inverse_bind_matrices: npt.ArrayLike | torch.Tensor,

skeleton_global_matrices: npt.ArrayLike | torch.Tensor,

output: npt.ArrayLike | torch.Tensor,

) → numpy.typing.NDArray[numpy.float32][native]

Write and return skinning matrices using output shape (B, 4, 4).

class kangengine.animation.SkeletonTree[native]

Read-only skeleton hierarchy and local bind transforms.

local_rotation(index: int) → Quat

Return a node’s local bind rotation.

local_translation(index: int) → Vec3

Return a node’s local bind translation.

node_name(index: int) → str

Return a skeleton node name.

node_names() → list[str]

Return S skeleton node names.

num_joints() → int

Return S, the number of skeleton nodes.

parent_index(index: int) → int

Return the parent node index, or -1 for the root.

parent_indices() → list[int]

Return S parent indices.

print() → None

Print the hierarchy for debugging.

class kangengine.animation.SkeletonMotion[native]

Sampled skeleton animation with root motion and local rotations.

duration() → float

Return duration in seconds.

fps() → float

Return frames per second.

frame(frame_index: int) → SkeletonState

Return the pose at one frame.

static from_arrays(

skeleton_tree: SkeletonTree,

root_translations: npt.ArrayLike | torch.Tensor,

local_rotations_wxyz: npt.ArrayLike | torch.Tensor,

fps: float,

motion_name: str = 'Motion',

) → SkeletonMotion

Create a motion from root (F, 3) and WXYZ rotations (F, J, 4).

global_angular_accelerations() → _Float32Array

Compute global joint angular accelerations with shape (F, J, 3).

global_angular_velocities() → _Float32Array

Compute global joint angular velocities with shape (F, J, 3).

global_linear_accelerations() → _Float32Array

Compute global joint linear accelerations with shape (F, J, 3).

global_linear_velocities() → _Float32Array

Compute global joint linear velocities with shape (F, J, 3).

global_matrices() → _Float32Array

Compute global transforms with shape (F, J, 4, 4).

global_positions() → _Float32Array

Compute global joint positions with shape (F, J, 3).

global_rotations_wxyz() → _Float32Array

Compute WXYZ global joint rotations with shape (F, J, 4).

local_rotation(frame: int, joint: int) → Quat

Return one node’s local rotation at one frame.

local_rotations_wxyz() → _Float32Array

Return WXYZ local rotations with shape (F, J, 4).

local_rotations_wxyz_flat() → list[float]

Return flattened WXYZ rotations with logical shape (F, S, 4).

motion_name() → str

Return the clip name.

node_names() → list[str]

Return S skeleton node names.

num_frames() → int

Return F, the number of frames.

num_joints() → int

Return S, the number of skeleton nodes.

parent_indices() → list[int]

Return S parent indices.

root_linear_accelerations() → _Float32Array

Compute root linear accelerations with shape (F, 3).

root_linear_velocities() → _Float32Array

Compute root linear velocities with shape (F, 3).

root_translation(frame: int) → Vec3

Return the root translation at one frame.

root_translations() → _Float32Array

Return root translations with shape (F, 3).

root_translations_flat() → list[float]

Return flattened root translations with logical shape (F, 3).

sample(time: float, loop: bool = True) → SkeletonState

Sample a pose at time in seconds.

property skeleton_tree

Return the motion’s read-only skeleton hierarchy.

SkeletonMotion is the canonical public motion container. Importers such as BVHLoader and AMASSLoader return it directly; preprocessing code should construct edited clips with SkeletonMotion.from_arrays(). Batched FK, linear/angular velocity, and acceleration arrays are computed through its global_* and root_* methods.

class kangengine.animation.Transform[native]

Forward-kinematics transform result.

property rotation

Return the transform rotation.

property translation

Return the transform translation.

class kangengine.animation.SkeletonState[native]

Skeleton pose stored as root translation and S node rotations.

compute_global_matrices() → _Float32Array

Return global float32 matrices with shape (S, 4, 4).

compute_global_positions() → list[Vec3]

Return S global node positions.

compute_global_transforms() → list[Transform]

Return S global forward-kinematics transforms.

static from_rotation_and_root_translation(

tree: SkeletonTree,

rotations_wxyz: npt.ArrayLike | torch.Tensor,

root_translation: npt.ArrayLike | torch.Tensor,

is_local: bool = True,

) → SkeletonState

Create a pose from WXYZ rotations (S, 4) and root (3,).

is_local() → bool

Return whether rotations are local to parent nodes.

num_joints() → int

Return S, the number of skeleton nodes.

print_global_positions() → None

Print global node positions for debugging.

root_translation() → Vec3

Return the root translation.

rotation(index: int) → Quat

Return one stored node rotation.

set_root_translation(translation: npt.ArrayLike | torch.Tensor) → None

Set the root translation from shape (3,).

set_rotation(index: int, rotation: npt.ArrayLike | torch.Tensor) → None

Set one node rotation from an XYZW array with shape (4,).