Implementation:Haosulab ManiSkill CommonUtils

Knowledge Sources	Haosulab_ManiSkill
Domains	Robotics, Simulation, Data Processing
Last Updated	2026-02-15 08:00 GMT

Overview

Concrete tool for common tensor, array, dictionary, and quaternion utility functions used throughout ManiSkill.

Description

The common.py module provides foundational utility functions that are used pervasively across the ManiSkill codebase. The utilities are organized into three main categories:

Tensor and Array Utilities:

• to_tensor() -- Converts arrays, numpy arrays, lists, or dicts of them to torch tensors, automatically handling device placement (CPU or GPU depending on whether physx GPU is enabled) and dtype conversion (e.g., float64 to float32, uint16 to int32).
• to_numpy() / to_cpu_tensor() -- Convert data back to numpy or CPU tensors.
• batch() / unbatch() -- Add or remove a leading batch dimension from tensors, arrays, or nested dicts thereof.
• torch_clone_dict() -- Deep-clone all torch tensors in a nested dictionary.

Dictionary Utilities:

• dict_merge() -- In-place recursive merge of two dicts.
• merge_dicts() -- Merge a sequence of dicts with the same keys into a single dict of lists.
• append_dict_array() / index_dict_array() -- Concatenate or index into nested dict-of-arrays structures.
• flatten_state_dict() / flatten_dict_keys() -- Flatten nested state dicts into 1D arrays or flat key paths.

Vector and Quaternion Utilities:

• normalize_vector() / np_normalize_vector() -- Normalize vectors with epsilon handling.
• compute_angle_between() / np_compute_angle_between() -- Compute angles between vector pairs.
• quat_diff_rad() -- Compute rotational difference between quaternions in radians.

Usage

Import specific functions from mani_skill.utils.common whenever you need device-agnostic tensor conversion, dictionary manipulation, or geometric computations in task or environment code.

Code Reference

Source Location

• Repository: Haosulab_ManiSkill
• File: mani_skill/utils/common.py

Signature

def to_tensor(array: Array, device: Optional[Device] = None) -> torch.Tensor: ...
def to_numpy(array: Union[Array, Sequence], dtype=None) -> np.ndarray: ...
def batch(*args: Tuple[Union[Array, Sequence]]) -> Union[Array, tuple]: ...
def unbatch(*args: Tuple[Union[Array, Sequence]]) -> Union[Array, tuple]: ...
def flatten_state_dict(state_dict: dict, use_torch=False, device=None) -> Array: ...
def normalize_vector(x: torch.Tensor, eps=1e-6) -> torch.Tensor: ...
def quat_diff_rad(a: torch.Tensor, b: torch.Tensor) -> torch.Tensor: ...
def dict_merge(dct: dict, merge_dct: dict) -> None: ...
def merge_dicts(ds: Sequence[dict], asarray=False) -> dict: ...

Import

from mani_skill.utils import common
# or
from mani_skill.utils.common import to_tensor, to_numpy, batch, unbatch

I/O Contract

Inputs

Name	Type	Required	Description
array	Union[torch.Tensor, np.ndarray, list, dict]	Yes	Data to convert (for to_tensor/to_numpy)
device	Union[str, torch.device]	No	Target device for tensor placement
state_dict	dict	Yes	Nested dictionary of states (for flatten_state_dict)

Outputs

Name	Type	Description
return	torch.Tensor or np.ndarray	Converted tensor or array
return	dict	Merged/flattened dictionary

Usage Examples

Basic Usage

from mani_skill.utils.common import to_tensor, to_numpy, batch, unbatch, quat_diff_rad

# Convert numpy to torch tensor on appropriate device
import numpy as np
arr = np.array([1.0, 2.0, 3.0])
tensor = to_tensor(arr, device="cuda")

# Batch a single observation
obs = to_tensor(np.zeros(42))
batched_obs = batch(obs)  # shape: (1, 42)

# Compute quaternion difference
import torch
q1 = torch.tensor([[1.0, 0, 0, 0]])
q2 = torch.tensor([[0.707, 0.707, 0, 0]])
angle = quat_diff_rad(q1, q2)

Related Pages

• Environment:Haosulab_ManiSkill_Python_SAPIEN_Core
• Haosulab_ManiSkill_Pose