Utilities

General utilities used across the codebase.

Shared utilities: validation decorator, batching, JSON I/O, seeding, tensor conversion.

kimodo.tools.validate(validator, save_args=False, super_init=False)

Create a decorator function for validating user inputs.

Parameters:

• validator – the function to validate (pydantic dataclass)

• save (bool) – save all the attributes to the obj [args[0]]

• super_init (bool) – init parent with no arguments (useful for using save on a nn.Module)

Returns:

the decorator function

Return type:

decorator

kimodo.tools.ensure_batched(**spec)

Decorator to flatten complex batch dimensions.

Fixes included: 1. Handles 1D tensors (tail_ndim=0) correctly without slicing errors. 2. Skips .reshape() if the input is already purely flat (Optimization).

kimodo.tools.to_numpy(obj)

Recursively convert tensors in dicts/lists/tuples to numpy arrays; leave other types unchanged.

kimodo.tools.to_torch(obj, device=None, dtype=None)

Recursively convert numpy arrays in dicts/lists/tuples to torch tensors; optionally move to device/dtype.

kimodo.tools.seed_everything(seed, deterministic=False)

Seed all random number generators.

kimodo.tools.load_json(path)

Load a JSON file and return its contents.

Parameters:

path (str | Path) – Path to the JSON file.

Returns:

Parsed JSON content (dict, list, etc.).

Return type:

Any

Raises:

• FileNotFoundError – If the file does not exist.

• ValueError – If the file is not valid JSON.

kimodo.tools.save_json(path, data)

Save data to a JSON file.

Parameters:

• path (str | Path) – Path to the JSON file.

• data (Any) – Data to save (must be JSON serializable).

Raises:

ValueError – If the data is not JSON serializable.

Rotation and representation conversions: axis-angle, quaternion, matrix, 6D continuous.

kimodo.geometry.angle_to_Y_rotation_matrix(angle)

Build a rotation matrix around the Y axis from a scalar angle (radians).

Shape: angle.shape + (3, 3).

kimodo.geometry.matrix_to_cont6d(matrix)

Convert rotation matrix to 6D continuous representation (first two columns).

Shape: (…, 3, 3) -> (…, 6).

kimodo.geometry.cont6d_to_matrix(cont6d)

Convert 6D continuous representation to rotation matrix (Gram–Schmidt on two columns).

Last dim must be 6.

kimodo.geometry.axis_angle_to_matrix(axis_angle)

Convert axis-angle to rotation matrix.

Parameters:

axis_angle – (…, 3) axis-angle vectors (angle = norm, axis = normalized)

Returns:

(…, 3, 3) rotation matrices

Return type:

rotmat

kimodo.geometry.matrix_to_axis_angle(R)

Convert rotation matrix to axis-angle via quaternions (more numerically stable).

Parameters:

R – (…, 3, 3) rotation matrices

Returns:

(…, 3)

Return type:

axis_angle

kimodo.geometry.quaternion_to_axis_angle(quat)

Convert quaternion to axis-angle representation.

Parameters:

quat – (…, 4) quaternions with real part first (w, x, y, z)

Returns:

(…, 3)

Return type:

axis_angle

kimodo.geometry.matrix_to_quaternion(matrix)

Convert rotations given as rotation matrices to quaternions.

Parameters:

matrix – Rotation matrices as tensor of shape (…, 3, 3).

Returns:

quaternions with real part first, as tensor of shape (…, 4).

kimodo.geometry.quaternion_to_matrix(quaternions)

Convert rotations given as quaternions to rotation matrices.

Parameters:

quaternions – quaternions with real part first, as tensor of shape (…, 4).

Returns:

Rotation matrices as tensor of shape (…, 3, 3).

Text prompt sanitization for motion generation (whitespace, punctuation, capitalization).

kimodo.sanitize.sanitize_text(text, paragraph=True)

Sanitize a text prompt: strip, collapse spaces, capitalize, trim non-alphanumeric, add/fix final punctuation.

Parameters:

• text – Input text prompt.

• paragraph – If True, capitalize after each sentence break and normalize spacing between sentences.

Returns:

Sanitized text.

kimodo.sanitize.sanitize_texts(texts)

Sanitize each text prompt in the list (see sanitize_text).

Parameters:

texts – List of input text prompts.

Returns:

List of sanitized texts.