OrcaGym API Manual: orca_gym/core

📖 这是什么文档？
这是 orca_gym/core 模块的完整 API 参考手册，采用”索引 + 详情”的版式设计，便于快速查找和深入学习。

📚 文档说明

文档特点

• 索引优先：每个模块和类都提供索引表格，方便快速浏览和定位
• 详情展开：点击或展开详情部分，查看完整的方法签名、参数说明和使用示例
• 面向本地环境：本手册主要覆盖本地环境实现，远程环境相关内容已省略
• 仅公开接口：只列出 public 符号（不以下划线开头），聚焦实际可用的 API

如何使用本手册

1. 快速查找：使用下方的模块索引表格，找到你需要的模块
2. 浏览类列表：进入模块后，先看”Classes（索引）”表格，了解有哪些类
3. 查看方法：每个类都有”方法索引”表格，快速了解可用方法
4. 深入阅读：展开”方法详情”部分，查看完整的签名、参数说明和使用示例

相关文档

• 快速概览：查看 API_REFERENCE.md 了解整体架构和典型调用链
• 详细参考：查看 api_detail/core.md 获取自动生成的完整 API 签名列表
• Environment 模块：查看 api_manual/environment.md 了解环境层接口

📦 Modules（索引）

快速浏览所有模块，点击模块名跳转到详细内容：

orca_gym/core/orca_gym_data.py

OrcaGymData - 动态状态容器

Module docstring

动态状态容器（本地副本）。

用途：

• 保存仿真过程中的动态状态（时间、关节状态、偏置力等）。
• 在 update_data()（backend 同步）后由上层调用更新到该容器，供观测构建、奖励/调试读取。

字段与 shape（与 model.nq/nv 对齐）：

• time: 标量仿真时间
• qpos: (nq,) 广义坐标（关节位置/位姿参数）
• qvel: (nv,) 广义速度
• qacc: (nv,) 广义加速度
• qfrc_bias: (nv,) 偏置力（如重力/科里奥利/离心等项）

Classes（索引）

Classes（详情）

class OrcaGymData

动态状态容器（本地副本）

字段：

• time: 标量仿真时间
• qpos: (nq,) 广义坐标
• qvel: (nv,) 广义速度
• qacc: (nv,) 广义加速度
• qfrc_bias: (nv,) 偏置力

方法索引：

方法详情：

OrcaGymData.update_qpos_qvel_qacc

同步关节状态（qpos/qvel/qacc）。

参数：

• qpos: (nq,) 广义坐标
• qvel: (nv,) 广义速度
• qacc: (nv,) 广义加速度

说明：

• 通常在 backend 完成数据同步后调用，用于刷新本地副本。
• 该方法仅更新字段，不做一致性计算；需要运动学/传感器派生量一致时，应由上层按既定链路调用 mj_forward() 等接口。

OrcaGymData.update_qfrc_bias

同步偏置力 qfrc_bias。

参数：

• qfrc_bias: (nv,) 偏置力向量（如重力/科里奥利/离心等项）

说明：

• 通常由 backend 计算并在数据同步后刷新到本地副本。

orca_gym/core/orca_gym_local.py

OrcaGymLocal - 本地 MuJoCo Backend

Module docstring

核心层：Model/Data/Local backend 与 MuJoCo 控制查询接口。

Classes（索引）

Classes（详情）

class AnchorType

锚点类型枚举

术语说明:

• 锚点 (Anchor): 用于物体操作的虚拟连接点
• NONE: 无锚定，释放物体
• WELD: 焊接锚定，完全固定位置和姿态
• BALL: 球关节锚定，固定位置但允许旋转

使用示例:

# 使用焊接锚定抓取物体
self.anchor_actor("object_name", AnchorType.WELD)

# 使用球关节锚定
self.anchor_actor("object_name", AnchorType.BALL)

# 释放物体
self.release_body_anchored()  # 内部使用 AnchorType.NONE

class CaptureMode

视频捕获模式枚举

术语说明:

• 同步模式 (SYNC): 每个相机帧都与仿真步进对齐，性能较低但帧对齐
• 异步模式 (ASYNC): 相机帧独立捕获，性能较高但可能不完全对齐

使用示例:

# 开始保存视频，使用异步模式（默认，性能更好）
env.begin_save_video("output.mp4", CaptureMode.ASYNC)

# 使用同步模式（帧对齐，但性能较低）
env.begin_save_video("output.mp4", CaptureMode.SYNC)

class OrcaGymLocal

OrcaGym 本地仿真接口

负责与本地 MuJoCo 仿真器的交互，包括模型加载、仿真控制、状态查询等。 这是 OrcaGymLocalEnv 的核心通信对象，通过 gRPC 与 OrcaSim 服务器通信。

核心功能:

1. 模型管理: 加载 XML 模型、初始化 MuJoCo 模型和数据
2. 仿真控制: 步进、重置、前向计算等
3. 状态查询: 查询 body、joint、site、sensor 等状态
4. 物体操作: 通过 mocap body 和等式约束操作物体
5. 文件管理: 下载和缓存模型文件、mesh 等资源

方法索引（主要方法）：

注意：OrcaGymLocal 类包含大量方法（50+），完整的方法列表请查看 api_detail/core.md。

方法详情（主要方法）：

OrcaGymLocal.load_model_xml

从服务器加载模型 XML 文件。

从 OrcaSim 服务器获取模型 XML 文件，下载依赖的资源文件（mesh、hfield等），并返回本地文件路径。

Returns:

• model_xml_path: 模型 XML 文件的本地路径

使用示例:

# 在环境初始化时调用
model_xml_path = await self.gym.load_model_xml()
# 返回: "/path/to/model.xml"

OrcaGymLocal.init_simulation

初始化 MuJoCo 仿真。

从 XML 文件加载 MuJoCo 模型，创建数据对象，初始化所有模型信息容器（body、joint、actuator、site、sensor 等），并创建封装的 model 和 data 对象。

Args:

• model_xml_path: 模型 XML 文件的路径

使用示例:

# 在环境初始化时调用
model_xml_path = await self.gym.load_model_xml()
await self.gym.init_simulation(model_xml_path)

# 之后可以访问模型和数据
self.model = self.gym.model
self.data = self.gym.data

OrcaGymLocal.mj_step

执行 MuJoCo 仿真步进。

执行 nstep 次物理仿真步进，每次步进的时间为 timestep。在调用前需要先设置控制输入 (set_ctrl)。

Args:

• nstep: 步进次数，通常为 1 或 frame_skip

使用示例:

# 在 do_simulation 中调用
self.gym.set_ctrl(ctrl)
self.gym.mj_step(nstep=5)  # 步进 5 次

orca_gym/core/orca_gym_model.py

OrcaGymModel - 静态模型信息容器

Module docstring

静态模型信息容器（MuJoCo 模型的封装）。

用途：

• 存储模型的静态信息（body、joint、actuator、site、sensor、等式约束、mocap 等）。
• 提供名称与 ID 的双向映射（body_name2id、joint_name2id 等）。
• 提供结构查询接口（get_body_names、get_actuator_ctrlrange 等），用于环境初始化与观测构建。

关键字段（维度参数）：

• nq：qpos 长度（广义坐标数）
• nv：qvel/qacc 长度（自由度数）
• nu：执行器数量（动作空间维度）
• ngeom：几何体数量

Classes（索引）

Classes（详情）

class OrcaGymModel

静态模型信息容器（MuJoCo 模型的封装）

方法索引（主要方法）：

注意：OrcaGymModel 类包含大量方法（40+），完整的方法列表请查看 api_detail/core.md。

方法详情（主要方法）：

OrcaGymModel.get_body_names

获取所有 body 名称列表。

返回：

• body 名称列表

使用示例:

# 获取所有 body 名称
body_names = list(self.model.get_body_names())

OrcaGymModel.body_name2id

Body 名称转ID。

将 body 名称转换为对应的 ID，用于需要 ID 的底层操作。

Args:

• body_name: body 名称

Returns:

• body ID

使用示例:

# 在更新等式约束时使用
body_id = self.model.body_name2id(actor_name)
eq["obj2_id"] = body_id

orca_gym/core/orca_gym_opt_config.py

OrcaGymOptConfig - MuJoCo 仿真器优化配置

Module docstring

OrcaGymOptConfig - MuJoCo 仿真器优化配置

本模块提供 MuJoCo 仿真器优化参数的封装类，用于配置物理仿真器的各种参数。 这些参数影响仿真的精度、稳定性和性能。

使用场景:

• 在环境初始化时从服务器获取配置
• 通过 env.gym.opt 访问配置对象
• 调整物理仿真精度和性能平衡

典型用法:

# 配置通过 OrcaGymLocal 的初始化自动获取
env = OrcaGymLocalEnv(...)
# 访问配置
timestep = env.gym.opt.timestep
gravity = env.gym.opt.gravity
solver = env.gym.opt.solver

Classes（索引）

Classes（详情）

class OrcaGymOptConfig

MuJoCo 仿真器优化配置容器

主要属性：

说明：

• 该对象在环境初始化时从服务器获取（通过 query_opt_config()）。
• 通过 env.gym.opt 访问；修改配置需调用 set_opt_config() 同步到本地模型。

使用示例：

# 访问配置
timestep = env.gym.opt.timestep
gravity = env.gym.opt.gravity
solver = env.gym.opt.solver

# 修改配置（需要同步到模型）
env.gym.opt.timestep = 0.002
env.gym.set_opt_config()  # 同步到本地模型

更多详细信息，请查看 api_detail/core.md。