Language

unilab.base.backend.mujoco.backend.MuJoCoBackend¶

class unilab.base.backend.mujoco.backend.MuJoCoBackend[source]¶

Bases: SimBackend

MuJoCo 后端实现

Parameters:

scene (SceneCfg)
num_envs (int)
sim_dt (float)
base_name (Optional[str])
add_body_sensors (bool)
position_actuator_gains (dict | None)
iterations (int | None)
push_body_name (Optional[str])
post_step_forward_sensor (bool)

Methods

`__init__`(scene, num_envs, sim_dt[, ...])
`apply_body_force`(body_ids, force)	Accumulate one external world-frame force vector per target body.
`apply_body_linear_velocity_delta`(body_ids, ...)	Apply a world-frame linear-velocity delta to specific bodies.
`apply_init_randomization`(plan)	Apply cold-path model/materialization randomization.
`apply_interval_randomization`(plan)	Apply a scheduled interval randomization plan.
`capture_video_frame`()	Capture one RGB frame through a backend-native renderer.
`cleanup_scene_assets`()	Release cold-path scene artifacts owned by the backend.
`copy_body_state_w`(body_ids, out_pos, ...)	Copy selected world-frame body state into caller-owned buffers.
`create_hfield_scanner`(*, hfield_geom_id, ...)	Create a reusable height-field scanner on the init/cold path.
`get_actuator_ctrl_range`()	获取执行器控制范围
`get_actuator_gains`()	Return per-joint (kp, kd) arrays read from the current model state.
`get_base_ang_vel`()	获取 base 在世界系下的角速度
`get_base_lin_vel`()	获取 base 在世界系下的线速度
`get_base_pos`()	获取 base 在世界系下的位置
`get_base_quat`()	获取 base 在世界系下的四元数（wxyz）
`get_body_ang_vel_b`(body_ids)	获取指定 body 在 baselink 系下的角速度
`get_body_ang_vel_w`(body_ids)	获取指定 body 在世界系下的角速度
`get_body_id`(name)	Resolve one body/link name through the backend contract.
`get_body_ids`(names)	将 body/link 名称解析为后端整数 ID
`get_body_ipos`()	Return the backend body inertial-position table.
`get_body_lin_vel_b`(body_ids)	获取指定 body 在 baselink 系下的线速度
`get_body_lin_vel_w`(body_ids)	获取指定 body 在世界系下的线速度
`get_body_mass`()	Return the backend body-mass table.
`get_body_pos_b`(body_ids)	获取指定 body 在 baselink 系下的位置
`get_body_pos_w`(body_ids)	获取指定 body 在世界系下的位置
`get_body_pose_w`(body_ids)	获取指定 body 在世界系下的位置和四元数（wxyz）
`get_body_pose_w_rows`(env_ids, body_ids)	Get selected env rows of world-frame body position and quaternion.
`get_body_quat_b`(body_ids)	获取指定 body 在 baselink 系下的四元数（wxyz）
`get_body_quat_w`(body_ids)	获取指定 body 在世界系下的四元数（wxyz）
`get_body_state_w`(body_ids)	Get selected body position, quaternion, linear velocity, and angular velocity.
`get_body_subtree_ids`(root_body_id)	Return body ids in the subtree rooted at `root_body_id`.
`get_body_vel_w`(body_ids)	获取指定 body 在世界系下的线速度和角速度
`get_default_qpos`()	Return the backend/model default qpos through a stable contract.
`get_dof_armature`()	Return the backend dof-armature table.
`get_dof_pos`()	获取关节位置（不含 base）
`get_dof_vel`()	获取关节速度（不含 base）
`get_dr_capabilities`()	Return supported domain-randomization capabilities for this backend.
`get_geom_body_ids`()	Return the owning body id for each geom.
`get_geom_contact_masks`()	Return per-geom contact type and affinity masks.
`get_geom_friction`()	Return the backend geom-friction table.
`get_geom_id`(name)	Resolve one geom name through the backend contract.
`get_geom_names`()	Return backend geom names in backend id order.
`get_geom_size`(name)	Return one geom size vector through the backend contract.
`get_gravity`()	Return the backend gravity vector.
`get_init_qvel`()	获取零初始化的 qvel 向量，维度与 set_state 期望一致
`get_joint_dof_indices`(names)	将关节名称列表转换为速度空间（qvel）的 DoF 索引数组。
`get_joint_dof_pos_indices`(names)	将关节名称列表转换为位置空间（qpos）的 DoF 索引数组。
`get_joint_dof_vel_indices`(names)	将关节名称列表转换为速度空间（qvel）的 DoF 索引数组（相对于关节部分起始）。
`get_joint_range`()	获取关节位置限制（不含浮动基座）
`get_keyframe_qpos`(name)	获取指定关键帧的完整 qpos（含浮动基座）
`get_motion_body_ids`(names)	Resolve MuJoCo-style body IDs used by motion datasets.
`get_physics_state`()	Return a physics snapshot suitable for offline playback/video export.
`get_play_capabilities`()	Return backend-native play/render capabilities.
`get_playback_model`([env_index])	Return the MuJoCo model used by playback for one vectorized env.
`get_sensor_data`(name)	获取传感器数据
`get_sensor_data_batch`(names)	Fetch multiple sensors and concatenate their flattened values.
`get_sensor_data_rows`(name, env_ids)	Get selected env rows of a sensor array.
`get_site_ids`(names)	将 site 名称列表转换为整数 ID 数组。
`get_site_jacobian_w`(site_id, dof_indices)	批量 Jacobian，shape (num_envs, 3, len(dof_indices))。
`init_renderer`([spacing, offset_mode, ...])	Initialize a backend-native renderer.
`materialize`()	Finalize cold-path backend resources before reset/step.
`push_robots`(force_range)
`render`()	Render one frame through a backend-native interactive renderer.
`resolve_play_render_plan`(*, ...)	Resolve high-level playback mode into backend-owned render parameters.
`run_playback`(*, env, initialize, step, num_steps)	Execute backend-owned playback for an env wrapper.
`set_pre_step_control`(fn)	Register an env-owned policy-control to physics-control converter.
`set_state`(env_indices, qpos, qvel[, ...])	设置指定环境的物理状态
`step`(ctrl[, nsteps])	执行物理步进

Attributes

`model`	底层物理模型
`num_actuators`	执行器数量
`num_dof_vel`	关节速度自由度数量（不含浮动基座）
`num_envs`	环境数量
`backend_type`

__init__(scene, num_envs, sim_dt, base_name=None, np_dtype=None, add_body_sensors=False, position_actuator_gains=None, iterations=None, push_body_name=None, post_step_forward_sensor=False)[source]¶

Parameters:

scene (SceneCfg)
num_envs (int)
sim_dt (float)
base_name (Optional[str])
add_body_sensors (bool)
position_actuator_gains (dict | None)
iterations (int | None)
push_body_name (Optional[str])
post_step_forward_sensor (bool)

backend_type: str¶

property num_envs: int¶: 环境数量

property model¶: 底层物理模型

property num_actuators: int¶: 执行器数量

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

get_actuator_ctrl_range()[source]¶

获取执行器控制范围

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

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

get_init_qvel()[source]¶

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

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

get_body_ids(names)[source]¶

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

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

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

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_joint_range()[source]¶

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

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

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

执行物理步进

Parameters:

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

Return type:

dict | None

Returns:

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

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

设置指定环境的物理状态

Parameters:

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

Return type:

None

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

apply_interval_randomization(plan)[source]¶

Apply a scheduled interval randomization plan.

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

push_robots(force_range)[source]¶

Parameters:: force_range (Sequence[float] | ndarray)
Return type:: None

apply_body_force(body_ids, force)[source]¶

Accumulate one external world-frame force vector per target body.

Parameters:

body_ids (ndarray) – Body ids to perturb.
force (ndarray) – Force tensor with shape (num_envs, len(body_ids), 3).

Return type:

None

Returns:

None. The force is staged in xfrc_applied for the next step.

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)
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)
camera_kwargs (dict[str, Any] | None)

Return type:

str | None

get_base_pos()[source]¶

获取 base 在世界系下的位置

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

get_base_quat()[source]¶

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

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

get_base_lin_vel()[source]¶

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

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

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

get_base_ang_vel()[source]¶

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

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

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

get_dof_pos()[source]¶

获取关节位置（不含 base）

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

get_dof_vel()[source]¶

获取关节速度（不含 base）

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

get_body_pos_w(body_ids)[source]¶

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

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

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_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]

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_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_pos_b(body_ids)[source]¶

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

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

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)

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)

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_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).

get_site_jacobian_w(site_id, dof_indices)[source]¶

批量 Jacobian，shape (num_envs, 3, len(dof_indices))。

使用 BatchEnvPool.compute_site_jacobians 原生接口，无需每 env 独立 MjData。 scalar site_id → pool 返回 (N, 3, nv)（k 维被 squeeze）。

Parameters:

site_id (int)
dof_indices (ndarray)

Return type:

tuple[ndarray, 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 MuJoCo model used by playback for one vectorized env.

Parameters:: env_index (int | None) – Optional vectorized environment index.
Returns:: The MuJoCo model assigned to that env, or the current backend model when no explicit index is requested.

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.

capture_video_frame()¶

Capture one RGB frame through a backend-native renderer.

Return type:: ndarray

cleanup_scene_assets()¶

Release cold-path scene artifacts owned by the backend.

Return type:: None

get_body_id(name)¶

Resolve one body/link name through the backend contract.

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

get_body_pose_w(body_ids)¶

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

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

get_body_vel_w(body_ids)¶

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

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

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

set_pre_step_control(fn)¶

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

get_actuator_gains()[source]¶

Return per-joint (kp, kd) arrays read from the current model state.

Return type:: tuple[ndarray, ndarray]