Language

`unilab.base.backend` — Simulation Backends¶

UniLab abstracts two CPU-side physics backends behind a single SimBackend contract.

Backend	Strengths	Notes
MuJoCo (`mujoco-uni`)	Mature, broad asset support, deterministic	Default for research
Motrix (`motrixsim-core`)	High-throughput, multithread step, snapshot/playback	Cross-platform; required for video export on macOS

Pick a backend per task via the top-level --sim <backend> CLI flag — see Simulation Backends.

class unilab.base.backend.base.SimBackend[source]¶

Bases: ABC

仿真后端统一接口

backend_type: str¶

abstract property num_envs: int¶: 环境数量

abstract property model¶: 底层物理模型

abstract property num_actuators: int¶: 执行器数量

abstract property num_dof_vel: int¶: 关节速度自由度数量（不含浮动基座）

abstract get_actuator_ctrl_range()[source]¶

获取执行器控制范围

Return type:: ndarray
Returns:: (num_actuators, 2) 数组，列为 [low, high]

abstract get_keyframe_qpos(name)[source]¶

获取指定关键帧的完整 qpos（含浮动基座）

Parameters:: name (str) – 关键帧名称（如 “stand”、”home”）
Return type:: ndarray
Returns:: (nq,) 数组

get_default_qpos()[source]¶

Return the backend/model default qpos through a stable contract.

Return type:: ndarray

abstract get_init_qvel()[source]¶

获取零初始化的 qvel 向量，维度与 set_state 期望一致

Return type:: ndarray
Returns:: 全零数组

abstract get_body_ids(names)[source]¶

将 body/link 名称解析为后端整数 ID

Parameters:: names (Sequence[str]) – body/link 名称序列
Return type:: ndarray
Returns:: (len(names),) int32 数组
Raises:: ValueError – 若名称未找到

get_body_id(name)[source]¶

Resolve one body/link name through the backend contract.

Parameters:: name (str)
Return type:: int

get_geom_id(name)[source]¶

Resolve one geom name through the backend contract.

Parameters:: name (str)
Return type:: int

get_geom_size(name)[source]¶

Return one geom size vector through the backend contract.

Parameters:: name (str)
Return type:: ndarray

create_hfield_scanner(*, hfield_geom_id, offsets, frame_body_id, alignment='yaw', output='height')[source]¶

Create a reusable height-field scanner on the init/cold path.

Backends that support height-field terrain scan must override this method.

Parameters:

hfield_geom_id (int)
offsets (ndarray)
frame_body_id (int)
alignment (str)
output (str)

Return type:

BackendHeightScanner

get_body_subtree_ids(root_body_id)[source]¶

Return body ids in the subtree rooted at root_body_id.

Parameters:: root_body_id (int)
Return type:: ndarray

get_geom_names()[source]¶

Return backend geom names in backend id order.

Return type:: tuple[str, ...]

get_geom_body_ids()[source]¶

Return the owning body id for each geom.

Return type:: ndarray

get_geom_contact_masks()[source]¶

Return per-geom contact type and affinity masks.

Return type:: tuple[ndarray, ndarray]

get_geom_friction()[source]¶

Return the backend geom-friction table.

Return type:: ndarray

get_gravity()[source]¶

Return the backend gravity vector.

Return type:: ndarray

get_body_mass()[source]¶

Return the backend body-mass table.

Return type:: ndarray

get_body_ipos()[source]¶

Return the backend body inertial-position table.

Return type:: ndarray

get_dof_armature()[source]¶

Return the backend dof-armature table.

Return type:: ndarray

get_motion_body_ids(names)[source]¶

Resolve MuJoCo-style body IDs used by motion datasets.

Parameters:: names (Sequence[str])
Return type:: ndarray

cleanup_scene_assets()[source]¶

Release cold-path scene artifacts owned by the backend.

Return type:: None

abstract get_joint_range()[source]¶

获取关节位置限制（不含浮动基座）

Return type:: ndarray | None
Returns:: (num_dof, 2) 数组，列为 [low, high]；若后端不支持则返回 None

abstract step(ctrl, nsteps=1)[source]¶

执行物理步进

Parameters:

ctrl (ndarray) – 控制输入 (num_envs, nu)
nsteps (int) – 步进次数

Return type:

dict | None

Returns:

可选的 dict，可包含 “timing” key 记录各阶段耗时（ms）

set_pre_step_control(fn)[source]¶

The callback receives (backend, ctrl) so owner code can read the backend’s freshly-updated sensor contract before every physics substep. It must return backend-native actuator control with the same shape. Position-actuator envs leave this unset and keep the direct control path.

Parameters:: fn (Callable[[Any, ndarray], ndarray] | None)
Return type:: None

abstract set_state(env_indices, qpos, qvel, randomization=None)[source]¶

设置指定环境的物理状态

Parameters:

env_indices (ndarray) – 环境索引
qpos (ndarray) – 位置状态
qvel (ndarray) – 速度状态
randomization (ResetRandomizationPayload | None) – 可选的后端随机化 payload

Return type:

None

abstract get_dr_capabilities()[source]¶

Return supported domain-randomization capabilities for this backend.

Return type:: DomainRandomizationCapabilities

apply_init_randomization(plan)[source]¶

Apply cold-path model/materialization randomization.

Parameters:: plan (InitRandomizationPlan)
Return type:: None

materialize()[source]¶

Finalize cold-path backend resources before reset/step.

Return type:: None

abstract apply_interval_randomization(plan)[source]¶

Apply a scheduled interval randomization plan.

Parameters:: plan (IntervalRandomizationPlan)
Return type:: None

apply_body_linear_velocity_delta(body_ids, velocity_delta)[source]¶

Apply a world-frame linear-velocity delta to specific bodies.

Parameters:

body_ids (ndarray) – Body ids whose linear velocities should be perturbed.
velocity_delta (ndarray) – Velocity delta with shape (num_envs, len(body_ids), 3).

Return type:

None

Returns:

None. Backends that support this mutate their pending simulation state.

apply_body_force(body_ids, force)[source]¶

Apply a world-frame force to specific bodies for the upcoming step.

Parameters:

body_ids (ndarray) – Body ids whose external forces should be perturbed.
force (ndarray) – Force values with shape (num_envs, len(body_ids), 3).

Return type:

None

Returns:

None. Backends that support this mutate their pending simulation state.

get_play_capabilities()[source]¶

Return backend-native play/render capabilities.

Return type:: BackendPlayCapabilities

resolve_play_render_plan(*, play_render_mode, play_steps, output_video)[source]¶

Resolve high-level playback mode into backend-owned render parameters.

Parameters:

play_render_mode (str | None)
play_steps (int | None)
output_video (str | PathLike[str] | None)

Return type:

BackendPlayRenderPlan

run_playback(*, env, initialize, step, num_steps, output_video=None, render_spacing=None, render_offset_mode=None, headless=None, record_video=None, frame_state_getter=None, camera_kwargs=None, extra_data_getter=None)[source]¶

Execute backend-owned playback for an env wrapper.

Parameters:

env (Any)
initialize (Callable[[], Any])
step (Callable[[Any], Any])
num_steps (int | None)
output_video (str | PathLike[str] | None)
render_spacing (float | None)
render_offset_mode (str | None)
headless (bool | None)
record_video (bool | None)
frame_state_getter (Callable[[], ndarray] | None)
camera_kwargs (dict[str, Any] | None)
extra_data_getter (Callable[[], ndarray | None] | None)

Return type:

str | None

init_renderer(spacing=1.0, *, offset_mode='grid', headless=False, capture=False, width=1280, height=720, camera_kwargs=None)[source]¶

Initialize a backend-native renderer.

headless controls whether a native window is opened. capture controls whether capture_video_frame is valid for the renderer.

Parameters:

spacing (float)
offset_mode (str)
headless (bool)
capture (bool)
width (int)
height (int)
camera_kwargs (dict[str, Any] | None)

Return type:

None

render()[source]¶

Render one frame through a backend-native interactive renderer.

Return type:: None

capture_video_frame()[source]¶

Capture one RGB frame through a backend-native renderer.

Return type:: ndarray

get_physics_state()[source]¶

Return a physics snapshot suitable for offline playback/video export.

Return type:: ndarray

get_playback_model(env_index=None)[source]¶

Return the playback model for a specific env when variants exist.

Parameters:: env_index (int | None) – Optional vectorized environment index.
Return type:: Any
Returns:: The backend model object used by playback tooling.

get_actuator_gains()[source]¶

Return per-joint (kp, kd) arrays from the backend model.

Return type:: tuple[ndarray, ndarray]

abstract get_base_pos()[source]¶

获取 base 在世界系下的位置

Return type:: ndarray
Returns:: (num_envs, 3)

abstract get_base_quat()[source]¶

获取 base 在世界系下的四元数（wxyz）

Return type:: ndarray
Returns:: (num_envs, 4)

abstract get_base_lin_vel()[source]¶

获取 base 在世界系下的线速度

即广义速度 qvel 的前 3 维，表达在世界坐标系中。

Return type:: ndarray
Returns:: (num_envs, 3)

abstract get_base_ang_vel()[source]¶

获取 base 在世界系下的角速度

即广义速度 qvel 的第 3-5 维，表达在世界坐标系中。注意与陀螺仪（gyro）读数的区别：陀螺仪返回的是角速度在 body/sensor 局部坐标系下的分量（即 body frame 表达），而本接口返回的是世界系表达。若需要 body frame 下的角速度，请使用对应的传感器接口gyro。

Return type:: ndarray
Returns:: (num_envs, 3)

abstract get_dof_pos()[source]¶

获取关节位置（不含 base）

Return type:: ndarray
Returns:: (num_envs, num_dof)

abstract get_dof_vel()[source]¶

获取关节速度（不含 base）

Return type:: ndarray
Returns:: (num_envs, num_dof)

abstract get_body_pos_w(body_ids)[source]¶

获取指定 body 在世界系下的位置

Parameters:: body_ids (ndarray) – body 索引数组
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

abstract get_body_quat_w(body_ids)[source]¶

获取指定 body 在世界系下的四元数（wxyz）

Parameters:: body_ids (ndarray) – body 索引数组
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 4)

get_body_pose_w(body_ids)[source]¶

获取指定 body 在世界系下的位置和四元数（wxyz）

Parameters:: body_ids (ndarray)
Return type:: tuple[ndarray, ndarray]

abstract get_body_lin_vel_w(body_ids)[source]¶

获取指定 body 在世界系下的线速度

Parameters:: body_ids (ndarray) – body 索引数组
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

get_body_vel_w(body_ids)[source]¶

获取指定 body 在世界系下的线速度和角速度

Parameters:: body_ids (ndarray)
Return type:: tuple[ndarray, ndarray]

abstract get_body_ang_vel_w(body_ids)[source]¶

获取指定 body 在世界系下的角速度

Parameters:: body_ids (ndarray) – body 索引数组
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

get_body_state_w(body_ids)[source]¶

Get selected body position, quaternion, linear velocity, and angular velocity.

Parameters:: body_ids (ndarray)
Return type:: tuple[ndarray, ndarray, ndarray, ndarray]

copy_body_state_w(body_ids, out_pos, out_quat, out_lin_vel, out_ang_vel)[source]¶

Copy selected world-frame body state into caller-owned buffers.

Parameters:

body_ids (ndarray)
out_pos (ndarray)
out_quat (ndarray)
out_lin_vel (ndarray)
out_ang_vel (ndarray)

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

get_body_pose_w_rows(env_ids, body_ids)[source]¶

Get selected env rows of world-frame body position and quaternion.

Parameters:

env_ids (ndarray)
body_ids (ndarray)

Return type:

tuple[ndarray, ndarray]

abstract get_body_pos_b(body_ids)[source]¶

获取指定 body 在 baselink 系下的位置

Parameters:: body_ids (ndarray) – body 索引数组
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

abstract get_body_quat_b(body_ids)[source]¶

获取指定 body 在 baselink 系下的四元数（wxyz）

Parameters:: body_ids (ndarray) – body 索引数组
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 4)

abstract get_body_lin_vel_b(body_ids)[source]¶

获取指定 body 在 baselink 系下的线速度

Parameters:: body_ids (ndarray) – body 索引数组
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

abstract get_body_ang_vel_b(body_ids)[source]¶

获取指定 body 在 baselink 系下的角速度

Parameters:: body_ids (ndarray) – body 索引数组
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

get_site_ids(names)[source]¶

将 site 名称列表转换为整数 ID 数组。

Parameters:: names (Sequence[str]) – site 名称列表
Return type:: ndarray
Returns:: shape (len(names),) 的 int32 ID 数组

get_joint_dof_indices(names)[source]¶

将关节名称列表转换为速度空间（qvel）的 DoF 索引数组。

Parameters:: names (Sequence[str]) – 关节名称列表
Return type:: ndarray
Returns:: shape (len(names),) 的 int32 索引数组（相对于 qvel 起始位置）

get_joint_dof_pos_indices(names)[source]¶

将关节名称列表转换为位置空间（qpos）的 DoF 索引数组。

仅支持单自由度关节（非 free joint）。

Parameters:: names (Sequence[str]) – 关节名称列表
Return type:: ndarray
Returns:: shape (len(names),) 的 int32 索引数组（相对于 qpos 中关节部分的起始位置）

get_joint_dof_vel_indices(names)[source]¶

将关节名称列表转换为速度空间（qvel）的 DoF 索引数组（相对于关节部分起始）。

Parameters:: names (Sequence[str]) – 关节名称列表
Return type:: ndarray
Returns:: shape (len(names),) 的 int32 索引数组

get_site_jacobian_w(site_id, dof_indices)[source]¶

批量计算指定 site 相对于指定 DoF 列的世界系 Jacobian。

Parameters:

site_id (int) – site 整数 ID
dof_indices (ndarray) – 要提取的 DoF 列索引，shape (n_dof,)

Return type:

tuple[ndarray, ndarray]

Returns:

(jacp, jacr)，各为 shape (num_envs, 3, n_dof) 的平移/旋转 Jacobian

abstract get_sensor_data(name)[source]¶

获取传感器数据

Parameters:: name (str) – 传感器名称
Return type:: ndarray
Returns:: 传感器数据数组

get_sensor_data_rows(name, env_ids)[source]¶

Get selected env rows of a sensor array.

Parameters:

name (str)
env_ids (ndarray)

Return type:

ndarray

get_sensor_data_batch(names)[source]¶

Fetch multiple sensors and concatenate their flattened values.

Parameters:: names (Sequence[str]) – Sensor names in output order.
Return type:: ndarray
Returns:: Array with shape (num_envs, total_sensor_values).

`unilab.base.backend.mujoco`	MuJoCo backend package.
`unilab.base.backend.motrix`	Motrix backend package.

Shared playback helper utilities.

unilab.base.backend.playback_common.env_cfg_value(env, name, default)[source]¶

Parameters:

env (Any)
name (str)
default (Any)

Return type:

Any

class unilab.base.backend.motrix_camera.MotrixTrackingCamera[source]¶

Bases: object

MotrixTrackingCamera(env_idx: ‘int’, distance: ‘float’, elevation: ‘float’, azimuth: ‘float’)

Parameters:

env_idx (int)
distance (float)
elevation (float)
azimuth (float)

env_idx: int¶

distance: float¶

elevation: float¶

azimuth: float¶

__init__(env_idx, distance, elevation, azimuth)¶

Parameters:

env_idx (int)
distance (float)
elevation (float)
azimuth (float)

class unilab.base.backend.motrix_camera.MotrixCameraView[source]¶

Bases: object

MotrixCameraView(lookat: ‘list[float]’, distance: ‘float’, elevation: ‘float’, azimuth: ‘float’, tracking: ‘MotrixTrackingCamera | None’ = None)

Parameters:

lookat (list[float])
distance (float)
elevation (float)
azimuth (float)
tracking (MotrixTrackingCamera | None)

lookat: list[float]¶

distance: float¶

elevation: float¶

azimuth: float¶

tracking: MotrixTrackingCamera | None = None¶

__init__(lookat, distance, elevation, azimuth, tracking=None)¶

Parameters:

lookat (list[float])
distance (float)
elevation (float)
azimuth (float)
tracking (MotrixTrackingCamera | None)

unilab.base.backend.motrix_camera.render_offsets(num_envs, spacing, offset_mode='grid')[source]¶

Parameters:

num_envs (int)
spacing (float)
offset_mode (str)

Return type:

list[list[float]]

unilab.base.backend.motrix_camera.tracking_camera_lookat(base_positions, tracking_camera, offsets)[source]¶

Parameters:

base_positions (ndarray)
tracking_camera (MotrixTrackingCamera)
offsets (ndarray)

Return type:

list[float]

unilab.base.backend.motrix_camera.resolve_system_camera_view(num_envs, base_positions, offsets, camera_kwargs)[source]¶

Parameters:

num_envs (int)
base_positions (ndarray | None)
offsets (Sequence[Sequence[float]])
camera_kwargs (dict[str, Any] | None)

Return type:

MotrixCameraView

unilab.base.backend — Simulation Backends¶

`unilab.base.backend` — Simulation Backends¶