ke.utils

Pure Python helpers for joint mapping, math, tensor conversion, colors, and debug drawing.

API overview

JointMapper	Resolve semantic and literal joint names against a motion skeleton.
normalize_joint_name	Lowercase a joint name and remove non-alphanumeric characters.
as_tensor	Return a tensor on the requested public API device.
as_cpu_numpy	Copy or view a value as a CPU NumPy array for CPU-native bindings.
as_sim_buffer	Return a NumPy-backed CPU or Torch-backed CUDA simulation buffer.
preset_rgba	Return a ColorLibrary preset as an RGBA list with optional alpha.

Joint Mapping

class kangengine.utils.JointSemantic(*values)[python]

Bases: str, Enum

ROOT = 'root'

HIPS = 'hips'

SPINE = 'spine'

CHEST = 'chest'

NECK = 'neck'

HEAD = 'head'

LEFT_SHOULDER = 'left_shoulder'

RIGHT_SHOULDER = 'right_shoulder'

LEFT_ELBOW = 'left_elbow'

RIGHT_ELBOW = 'right_elbow'

LEFT_WRIST = 'left_wrist'

RIGHT_WRIST = 'right_wrist'

LEFT_HAND = 'left_hand'

RIGHT_HAND = 'right_hand'

LEFT_HIP = 'left_hip'

RIGHT_HIP = 'right_hip'

LEFT_KNEE = 'left_knee'

RIGHT_KNEE = 'right_knee'

LEFT_ANKLE = 'left_ankle'

RIGHT_ANKLE = 'right_ankle'

LEFT_FOOT = 'left_foot'

RIGHT_FOOT = 'right_foot'

LEFT_TOE = 'left_toe'

RIGHT_TOE = 'right_toe'

LEFT_HEEL = 'left_heel'

RIGHT_HEEL = 'right_heel'

class kangengine.utils.JointMapper(

joint_names: list[str],

profiles: tuple[str, ...] | list[str] | None = ('geno', 'mixamo', 'kw5', 'kw', 'common'),

)[python]

Resolve semantic and literal joint names against a motion skeleton.

classmethod from_motion(

motion,

profiles: tuple[str, ...] | list[str] | None = ('geno', 'mixamo', 'kw5', 'kw', 'common'),

) → JointMapper

Return type:

JointMapper

find_name(name: str) → int | None

Return type:

int | None

find_names(names: list[str]) → list[int]

Return type:

list[int]

aliases(

semantic: JointSemantic | str,

) → tuple[str, ...]

Return type:

tuple[str, ...]

find(

semantic: JointSemantic | str,

) → int | None

Return type:

int | None

find_many(

semantics: list[JointSemantic | str],

) → list[int]

Return type:

list[int]

default_tracking_indices() → list[int]

Return type:

list[int]

default_contact_indices() → list[int]

Return type:

list[int]

kangengine.utils.normalize_joint_name(name: str) → str[python]

Lowercase a joint name and remove non-alphanumeric characters.

Return type:

str

Math Helpers

kangengine.utils.math.normalize_vector(value, fallback=None, eps: float = 1e-08) → ndarray[python]

Return a normalized float32 vector or a fallback for a near-zero input.

Return type:

ndarray

kangengine.utils.math.quat_xyzw_normalize(quat, eps: float = 1e-08) → ndarray[python]

Normalize an xyzw quaternion, falling back to identity.

Return type:

ndarray

kangengine.utils.math.quat_xyzw_multiply(a, b) → ndarray[python]

Multiply two xyzw quaternions.

Return type:

ndarray

kangengine.utils.math.quat_xyzw_conjugate(quat) → ndarray[python]

Return the conjugate of an xyzw quaternion.

Return type:

ndarray

kangengine.utils.math.quat_xyzw_rotate(quat, vector) → ndarray[python]

Rotate a 3D vector by an xyzw quaternion.

Return type:

ndarray

kangengine.utils.math.quat_xyzw_from_two_vectors(src, dst) → ndarray[python]

Return the shortest xyzw rotation from src to dst.

Return type:

ndarray

kangengine.utils.math.quat_wxyz_to_xyzw(quat) → ndarray[python]

Convert a wxyz quaternion to xyzw ordering.

Return type:

ndarray

kangengine.utils.math.quat_wxyz_twist_angle(quat, axis) → float[python]

Return the signed local-axis twist angle from a wxyz quaternion.

Return type:

float

Tensor Helpers

kangengine.utils.tensor.resolve_device(device=None) → device[python]

Return the public tensor device, defaulting to CPU.

Return type:

device

kangengine.utils.tensor.as_tensor(value, *, shape=None, device=None, dtype=torch.float32) → Tensor[python]

Return a tensor on the requested public API device.

Return type:

Tensor

kangengine.utils.tensor.as_cpu_numpy(value, *, shape=None, dtype=<class 'numpy.float32'>) → ndarray[python]

Copy or view a value as a CPU NumPy array for CPU-native bindings.

Return type:

ndarray

kangengine.utils.as_sim_buffer(

value: ndarray | Tensor,

*,

shape: tuple[int, ...] | list[int] | Size | None = None,

sim_device: str | device | None = None,

dtype: dtype | dtype | Type[generic] | str = torch.float32,

) → SimBuffer[python]

Return a NumPy-backed CPU or Torch-backed CUDA simulation buffer.

Return type:

SimBuffer

Environment Helpers

kangengine.utils.env_utils.env_id_list(

env_id: int | integer | Sequence[int] | ndarray | Tensor | None,

num_envs: int,

) → list[int][python]

Normalize scalar, sequence, tensor, or None env ids into a list.

Return type:

list[int]

kangengine.utils.env_utils.select_env_value(value, env_index: int, env_count: int, shape)[python]

Select one row from batched env values, or reshape a shared value.

kangengine.utils.env_utils.select_optional_env_value(value, env_index: int, env_count: int, shape)[python]

Select an env value unless the optional value is absent.

Color And Debug Helpers

kangengine.utils.color.preset_rgba(color_type, alpha: float = 1.0) → list[float][python]

Return a ColorLibrary preset as an RGBA list with optional alpha.

Return type:

list[float]

kangengine.utils.debug_draw.log_debug_axes(

app,

path: str,

origin,

rotation,

length: float = 0.18,

width: float = 1.5,

alpha: float = 0.95,

hidden: bool = False,

) → None[python]

Compatibility wrapper for app.debug_overlay.axes(...).

Return type:

None