Language Language English 简体中文

unilab.base.backend

Functions

create_backend(backend_type, scene, ...)

创建仿真后端

class unilab.base.backend.SimBackend

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()

获取执行器控制范围

Return type:

ndarray

Returns:

(num_actuators, 2) 数组，列为 [low, high]

abstract get_keyframe_qpos(name)

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

Parameters:

name (str) – 关键帧名称（如 “stand”、”home”）

Return type:

ndarray

Returns:

(nq,) 数组

get_default_qpos()

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

Return type:

ndarray

abstract get_init_qvel()

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

Return type:

ndarray

Returns:

全零数组

abstract get_body_ids(names)

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

Parameters:

names (Sequence[str]) – body/link 名称序列

Return type:

ndarray

Returns:

(len(names),) int32 数组

Raises:

ValueError – 若名称未找到

get_body_id(name)

Resolve one body/link name through the backend contract.

Parameters:

name (str)

Return type:

int

get_geom_id(name)

Resolve one geom name through the backend contract.

Parameters:

name (str)

Return type:

int

get_geom_size(name)

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')

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)

Return body ids in the subtree rooted at root_body_id.

Parameters:

root_body_id (int)

Return type:

ndarray

get_geom_names()

Return backend geom names in backend id order.

Return type:

tuple[str, ...]

get_geom_body_ids()

Return the owning body id for each geom.

Return type:

ndarray

get_geom_contact_masks()

Return per-geom contact type and affinity masks.

Return type:

tuple[ndarray, ndarray]

get_geom_friction()

Return the backend geom-friction table.

Return type:

ndarray

get_gravity()

Return the backend gravity vector.

Return type:

ndarray

get_body_mass()

Return the backend body-mass table.

Return type:

ndarray

get_body_ipos()

Return the backend body inertial-position table.

Return type:

ndarray

get_dof_armature()

Return the backend dof-armature table.

Return type:

ndarray

get_motion_body_ids(names)

Resolve MuJoCo-style body IDs used by motion datasets.

Parameters:

names (Sequence[str])

Return type:

ndarray

cleanup_scene_assets()

Release cold-path scene artifacts owned by the backend.

Return type:

None

abstract get_joint_range()

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

Return type:

ndarray | None

Returns:

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

abstract step(ctrl, nsteps=1)

执行物理步进

Parameters:

• ctrl (ndarray) – 控制输入 (num_envs, nu)

• nsteps (int) – 步进次数

Return type:

dict | None

Returns:

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

set_pre_step_control(fn)

Register an env-owned policy-control to physics-control converter.

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)

设置指定环境的物理状态

Parameters:

• env_indices (ndarray) – 环境索引

• qpos (ndarray) – 位置状态

• qvel (ndarray) – 速度状态

• randomization (ResetRandomizationPayload | None) – 可选的后端随机化 payload

Return type:

None

abstract get_dr_capabilities()

Return supported domain-randomization capabilities for this backend.

Return type:

DomainRandomizationCapabilities

apply_init_randomization(plan)

Apply cold-path model/materialization randomization.

Parameters:

plan (InitRandomizationPlan)

Return type:

None

materialize()

Finalize cold-path backend resources before reset/step.

Return type:

None

abstract apply_interval_randomization(plan)

Apply a scheduled interval randomization plan.

Parameters:

plan (IntervalRandomizationPlan)

Return type:

None

apply_body_linear_velocity_delta(body_ids, velocity_delta)

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)

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()

Return backend-native play/render capabilities.

Return type:

BackendPlayCapabilities

resolve_play_render_plan(*, play_render_mode, play_steps, output_video)

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)

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)

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()

Render one frame through a backend-native interactive renderer.

Return type:

None

capture_video_frame()

Capture one RGB frame through a backend-native renderer.

Return type:

ndarray

get_physics_state()

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

Return type:

ndarray

get_playback_model(env_index=None)

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()

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

Return type:

tuple[ndarray, ndarray]

abstract get_base_pos()

获取 base 在世界系下的位置

Return type:

ndarray

Returns:

(num_envs, 3)

abstract get_base_quat()

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

Return type:

ndarray

Returns:

(num_envs, 4)

abstract get_base_lin_vel()

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

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

Return type:

ndarray

Returns:

(num_envs, 3)

abstract get_base_ang_vel()

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

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

Return type:

ndarray

Returns:

(num_envs, 3)

abstract get_dof_pos()

获取关节位置（不含 base）

Return type:

ndarray

Returns:

(num_envs, num_dof)

abstract get_dof_vel()

获取关节速度（不含 base）

Return type:

ndarray

Returns:

(num_envs, num_dof)

abstract get_body_pos_w(body_ids)

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

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

abstract get_body_quat_w(body_ids)

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

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 4)

get_body_pose_w(body_ids)

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

Parameters:

body_ids (ndarray)

Return type:

tuple[ndarray, ndarray]

abstract get_body_lin_vel_w(body_ids)

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

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

get_body_vel_w(body_ids)

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

Parameters:

body_ids (ndarray)

Return type:

tuple[ndarray, ndarray]

abstract get_body_ang_vel_w(body_ids)

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

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

get_body_state_w(body_ids)

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)

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)

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)

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

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

abstract get_body_quat_b(body_ids)

获取指定 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)

获取指定 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)

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

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

get_site_ids(names)

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

Parameters:

names (Sequence[str]) – site 名称列表

Return type:

ndarray

Returns:

shape (len(names),) 的 int32 ID 数组

get_joint_dof_indices(names)

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

Parameters:

names (Sequence[str]) – 关节名称列表

Return type:

ndarray

Returns:

shape (len(names),) 的 int32 索引数组（相对于 qvel 起始位置）

get_joint_dof_pos_indices(names)

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

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

Parameters:

names (Sequence[str]) – 关节名称列表

Return type:

ndarray

Returns:

shape (len(names),) 的 int32 索引数组（相对于 qpos 中关节部分的起始位置）

get_joint_dof_vel_indices(names)

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

Parameters:

names (Sequence[str]) – 关节名称列表

Return type:

ndarray

Returns:

shape (len(names),) 的 int32 索引数组

get_site_jacobian_w(site_id, dof_indices)

批量计算指定 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)

获取传感器数据

Parameters:

name (str) – 传感器名称

Return type:

ndarray

Returns:

传感器数据数组

get_sensor_data_rows(name, env_ids)

Get selected env rows of a sensor array.

Parameters:

• name (str)

• env_ids (ndarray)

Return type:

ndarray

get_sensor_data_batch(names)

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.create_backend(backend_type, scene, num_envs, sim_dt, **kwargs)

创建仿真后端

Parameters:

• backend_type (str) – “mujoco” 或 “motrix”

• scene (SceneCfg) – SceneCfg，静态 scene 或组合式 scene 都通过这个 contract 表达

• num_envs (int) – 环境数量

• sim_dt (float) – 仿真时间步长

• **kwargs – 其他参数（position_actuator_gains, motrix_max_iterations 等）

Return type:

SimBackend

Returns:

SimBackend 实例

unilab.base.backend.add_motrix_tracking_frame_sensors(world, *, base_name)

Add Motrix-native frame sensors matching the legacy tracking sensor contract.

Parameters:

• world (World)

• base_name (str)

Return type:

None

unilab.base.backend.materialize_motrix_hfield_attached_scene(*, model_file, terrain_cfg, fragment_files=(), hfield_name='terrain_hfield', geom_name='floor', add_body_sensors=False, base_name='base', return_surface_sampler=False)

Build a MotrixSim model with generated hfield terrain and attached robot.

Parameters:

• model_file (str)

• terrain_cfg (TerrainGeneratorCfg)

• fragment_files (Sequence[str])

• hfield_name (str)

• geom_name (str)

• add_body_sensors (bool)

• base_name (str)

• return_surface_sampler (bool)

Return type:

tuple[SceneModel, ndarray] | tuple[SceneModel, ndarray, object]

unilab.base.backend.materialize_motrix_scene(*, model_file, fragment_files=(), add_body_sensors=False, base_name='base')

Build a MotrixSim model through MSD scene composition.

Parameters:

• model_file (str)

• fragment_files (Sequence[str])

• add_body_sensors (bool)

• base_name (str)

Return type:

SceneModel

Modules

base
motrix	Motrix backend package.
motrix_camera
mujoco	MuJoCo backend package.
playback_common	Shared playback helper utilities.