Language Language English 简体中文

unilab.base.backend.motrix.backend

Classes

MotrixBackend

MotrixSim 后端实现

class unilab.base.backend.motrix.backend.MotrixBackend

Bases: SimBackend

MotrixSim 后端实现

Parameters:

• scene (SceneCfg)

• num_envs (int)

• sim_dt (float)

• base_name (str)

• add_body_sensors (bool)

• max_iterations (int | None)

• push_body_name (str | None)

__init__(scene, num_envs, sim_dt, base_name='base', np_dtype=<class 'numpy.float32'>, add_body_sensors=False, max_iterations=3, push_body_name=None)

Parameters:

• scene (SceneCfg)

• num_envs (int)

• sim_dt (float)

• base_name (str)

• add_body_sensors (bool)

• max_iterations (int | None)

• push_body_name (str | None)

get_motion_body_ids(names)

Resolve MuJoCo-style body IDs used by motion datasets.

Parameters:

names (Sequence[str])

Return type:

ndarray

property num_envs: int

环境数量

property model

底层物理模型

property data

property num_actuators: int

执行器数量

property num_dof_vel: int

关节速度自由度数量（不含浮动基座）

get_actuator_ctrl_range()

获取执行器控制范围

Return type:

ndarray

Returns:

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

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

get_init_qvel()

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

Return type:

ndarray

Returns:

全零数组

get_body_ids(names)

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

Parameters:

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

Return type:

ndarray

Returns:

(len(names),) int32 数组

Raises:

ValueError – 若名称未找到

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

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

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

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

Return type:

ndarray | None

Returns:

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

step(ctrl, nsteps=1)

执行物理步进

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)

设置指定环境的物理状态

Parameters:

• env_indices (ndarray) – 环境索引

• qpos (ndarray) – 位置状态

• qvel (ndarray) – 速度状态

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

Return type:

None

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

apply_interval_randomization(plan)

Apply a scheduled interval randomization plan.

Parameters:

plan (IntervalRandomizationPlan)

Return type:

None

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)

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

获取 base 在世界系下的位置

Return type:

ndarray

Returns:

(num_envs, 3)

get_base_quat()

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

Return type:

ndarray

Returns:

(num_envs, 4)

get_base_lin_vel()

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

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

Return type:

ndarray

Returns:

(num_envs, 3)

get_base_ang_vel()

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

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

Return type:

ndarray

Returns:

(num_envs, 3)

get_dof_pos()

获取关节位置（不含 base）

Return type:

ndarray

Returns:

(num_envs, num_dof)

get_dof_vel()

获取关节速度（不含 base）

Return type:

ndarray

Returns:

(num_envs, num_dof)

get_body_pos_w(body_ids)

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

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

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

get_body_pose_w(body_ids)

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

Parameters:

body_ids (ndarray)

Return type:

tuple[ndarray, ndarray]

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_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_vel_w(body_ids)

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

Parameters:

body_ids (ndarray)

Return type:

tuple[ndarray, ndarray]

get_body_pos_b(body_ids)

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

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

get_body_quat_b(body_ids)

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

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

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

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

push_robots(force_range)

apply_body_force(body_ids, force)

Apply absolute world-frame external forces through Motrix Link API.

Parameters:

• body_ids (ndarray)

• force (ndarray)

Return type:

None

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

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

Initialize a Motrix renderer, optionally enabling system-camera capture.

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 current state (interactive visualization)

capture_video_frame()

Capture one RGB frame from Motrix’s system camera.

Return type:

ndarray

get_actuator_gains()

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

Return type:

tuple[ndarray, ndarray]