Extension 扩展

Extension 是 FastSim 的可插拔功能层。录制、回放、数据采集、HTTP 服务化、Benchmark 等能力均以扩展的形式存在——它们不侵入仿真核心，而是通过在生命周期的特定时机注册回调来介入仿真流程。

扩展如何运作

每个扩展实现 Extension.enable(sim) 方法，在初始化时向仿真实例注册所需的回调：

text

setup_all_before_loop()
  └─ ExtensionManager.enable_all_extensions()
       ├─ data_collect.enable(sim)   → 注册 observer，准备采集接口
       ├─ record.enable(sim)         → 注册 step_callback + terminate_callback
       ├─ server.enable(sim)         → 启动 Flask 服务线程
       └─ benchmark.enable(sim)      → 注册控制线程，驱动 episode 循环

扩展挂接的时机：

回调类型	触发时机	典型使用方
`step_callback`	每帧 `post_physics_update` 之后	record（逐帧写入数据）
`terminate_callback`	仿真终止时	record（后处理导出 HDF5/视频）
`controller_thread`	独立线程，与主循环并行	benchmark（episode 编排）

源码：fastsim/extensions/extension.py、fastsim/extensions/extension_manager.py

启用顺序与依赖

扩展按配置字典的键顺序依次启用，顺序错误会导致运行时报错。当前已知的依赖关系：

text

data_collect  ──────→  record
                  └──→  benchmark（若依赖观测采集）

record 在 enable() 时会主动获取已启用的 DataCollector 实例。如果 data_collect 尚未启用，会立即报错。

正确的配置顺序：

yaml

extension:
  extension_cfg_dict:
    data_collect:          # ← 必须在 record 之前
      enable: true
      ...
    record:
      enable: true
      ...
    server:
      enable: true
      ...

内置扩展

data_collect：观测采集

data_collect 是录制与 Benchmark 的基础设施。它按配置注册一组 observer，每个 observer 负责从场景中采集特定类型的数据（RGB 图像、深度图、关节状态、末端位姿等），并将其打包为 Observation 对象。

两种采集接口：

方法	适用场景
`collect_observations()`	在仿真主线程中直接调用
`request_observations()`	在控制线程中安全请求，内部封装为 Command

Observation 的数据格式按 observer 类型决定：JSON（状态数据）、JPEG（RGB 图像）、NPY（深度/数组数据）。

源码：fastsim/extensions/data_collect/

record：录制与导出

record 依赖 data_collect，将每帧采集的 Observation 异步写入本地文件系统，并在仿真终止时执行后处理，生成结构化产物。

生命周期挂接：

text

每帧 step_callback:
  DataCollector.collect_observations()
  → 异步写入原始帧数据（rgb.jpeg / depth.npy / state.json）

terminate_callback:
  postprocess()
  → 合并帧数据 → 生成 record.h5 + 视频 + 预览视频

导出目录结构：

text

recordings/
└─ {group}/
   └─ {name}/
      ├─ 000001/
      │   ├─ rgb.jpeg
      │   ├─ depth.npy
      │   └─ state.json
      ├─ 000002/
      │   └─ ...
      └─ record.h5       ← 后处理合并产物

postprocess_list 配置字段决定生成哪些产物（h5、视频、深度可视化等）。

源码：fastsim/extensions/record/

replay：轨迹回放

replay 从 record.h5 中读取轨迹数据，并在仿真中驱动实体按录制轨迹运动，用于可视化验证、数据审查或生成对比视频。

核心对象：

TrajectoryLoader：将 HDF5 文件解析为 Trajectory 对象，按 observer 分 TrajectoryTrack
Replayer：消费 TrajectoryTrack，逐帧通过 Command 驱动对应实体

HDF5 文件结构：

text

record.h5
├─ joint_states/          ← 关节状态轨迹
│   ├─ timestamps
│   └─ data
├─ ee_pose/               ← 末端位姿轨迹
└─ wrist_cam/             ← 相机图像序列

可通过 spawnable_names 配置限制只回放指定实体的轨迹。

源码：fastsim/extensions/replay/

server：REST API 服务化

server 扩展启动一个 Flask HTTP 服务，将所有标注了 @apiclass 的控制器方法自动注册为 HTTP POST 路由，使得外部程序可以通过网络调用 FastSim 的控制接口。

路由规则：

text

POST /{apiclass_name}/{method_name}

例如：POST /robot_controller/move_robot_to_ee_pose

请求与响应格式：

json

// 请求体
{ "robot_name": "arm", "target_pose": [...] }

// 响应体（Result 的 JSON 序列化）
{ "success": true, "msg": "", "data": {...} }

启用后，FastSim 的完整控制能力均可通过网络调用，适合与外部策略网络、ROS 节点或 Web 前端集成。

源码：fastsim/extensions/servitize/、fastsim/annotations/api_class.py

benchmark：Episode 评估

benchmark 以 episode 为单位循环运行策略，并在每个 episode 结束后评估 goal 条件是否满足，输出成功率等统计指标。它在独立控制线程中运行，不阻塞主仿真循环。

典型流程：

text

控制线程:
  for episode in range(num_episodes):
      reset_scene()                   ← 随机化或固定初始状态
      policy.run(sim)                 ← 执行策略
      result = evaluate_goals(sim)    ← 检查目标是否达成
      log_result(episode, result)     ← 记录结果
  generate_report()                   ← 输出统计报告

配置字段定义见 fastsim/extensions/benchmark/benchmark_cfg.py，详细用法参考示例：Benchmark 与数据采集。

teleop：实时遥操作

teleop 扩展支持从多种外部输入设备实时控制仿真中的机器人，适用于人类示教、数据采集和远程操控场景。

支持的输入驱动：

Driver	说明
`keyboard`	键盘控制，带 GUI 界面
`spacemouse`	3Dconnexion SpaceMouse 6-DOF 控制
`web`	WebSocket 浏览器控制页面
`gello`	GELLO 硬件遥操作臂（USB 串口）
`vr`	VR 控制器（SteamVR/OpenXR），支持 Quest 3 远程中继

控制模式：

ee_absolute：直接设置末端执行器目标位姿
ee_delta：增量式末端执行器位姿控制
joint_position：直接设置关节目标角度

teleop 以可配置的频率（control_frequency）轮询驱动器输入并生成控制命令，支持速率限制以避免命令队列拥塞。

源码：fastsim/extensions/teleop/

pipeline：批量任务管线

pipeline 扩展在单次仿真器会话中顺序执行多个配置文件定义的任务（job），适合大规模数据采集或批量实验。

核心特性：

从 JSON 文件加载 job 列表，每个 job 指向一个配置文件
单次仿真器启动，按序执行所有 job
每个 job 独立加载场景和任务配置
支持 stop_on_failure 模式：某个 job 失败时中止后续任务
自动聚合各 job 的执行结果（成功/失败/消息）

yaml

extension:
  extension_cfg_dict:
    pipeline:
      stereotype: pipeline
      enable: true
      job_list_path: ./pipeline_jobs.json
      stop_on_failure: false
      skip_postprocess: false

job 列表文件格式：

json

[
  "./job_config_1.yaml",
  "./job_config_2.yaml",
  "./job_config_3.yaml"
]

源码：fastsim/extensions/pipeline/

snapshot：仿真状态快照

snapshot 扩展提供完整的仿真状态保存与恢复能力，支持将某一时刻的仿真状态序列化为 .npz 文件，后续可从快照恢复仿真继续执行。

保存的状态包括：

所有实体的位姿（位置、旋转）
机器人关节状态（位置、速度）
柔体粒子状态
规划器的物体附着（attach）信息
任务执行上下文（当前 action 索引等元数据）

典型用法：

yaml

extension:
  extension_cfg_dict:
    snapshot:
      stereotype: snapshot
      enable: true
      snapshot_path: ./snapshots/before_place_action.npz

snapshot 常与 task_executor 配合使用，实现任务断点恢复——从特定 action 的快照恢复后，跳过已完成的步骤继续执行。

源码：fastsim/extensions/snapshot/

task_executor：自动任务执行

task_executor 扩展在独立控制线程中自动运行配置文件定义的任务，替代了 CLI 中的 --run_task 参数。

字段	说明
`stop_sim_on_task_end`	任务结束后是否终止仿真
`assert_task_success`	任务失败时是否抛出断言
`debug`	启用交互式调试器（action 失败时进入 REPL）
`restore_snapshot_before_run`	执行前先恢复快照
`restore_action_index`	从快照中的第几个 action 继续执行

yaml

extension:
  extension_cfg_dict:
    task_executor:
      stereotype: task_executor
      enable: true
      stop_sim_on_task_end: true
      debug: false

源码：fastsim/extensions/task_executor/

domain_randomization：域随机化

domain_randomization 扩展在每个 episode 中对场景进行随机化处理，用于增强策略的泛化能力。

支持的随机化类型：

类型	说明
位姿随机化	随机化物体和机器人的初始位姿
光照随机化	随机化光源的强度、颜色和方向
纹理随机化	随机化物体的视觉材质和纹理
物理参数随机化	随机化质量、摩擦系数等物理属性

源码：fastsim/extensions/domain_randomization/

ros_bridge：ROS 2 桥接

ros_bridge 扩展实现 FastSim 与 ROS 2 的实时双向通信，支持将仿真中的传感器数据发布为 ROS 话题，并接收外部 ROS 节点的控制指令。

源码：fastsim/extensions/ros_bridge/

Record → Replay 完整数据链路

以下是从录制到回放的完整端到端流程：

text

① 启用 data_collect
   注册 observer（关节状态、相机图像、末端位姿等）

② 启用 record
   每帧自动采集并异步写入原始帧数据

③ 仿真运行 + 终止
   terminate_callback 触发 postprocess，合并生成 record.h5

④ 启用 replay，指向 record.h5
   TrajectoryLoader 解析轨迹
   Replayer 逐帧驱动实体按录制轨迹运动

⑤（可选）导出对比视频
   原始录制视频 vs 回放渲染视频

这条链路覆盖了机器人学习数据采集的完整流程：在仿真中执行演示 → 录制传感器数据与状态 → 导出为标准格式 → 可视化验证数据质量。

交互式调试器

FastSim 提供了交互式调试器（Interactive Debugger），当任务 action 执行失败时可自动进入 REPL 环境，方便开发者现场检查和修复问题。

REPL 命令：

命令	说明
`state`	打印当前场景中所有实体的状态
`inspect <entity>`	查看指定实体的详细信息
`save [name]`	创建内存中的快照
`restore <name>`	从内存快照恢复仿真状态
`eval <expr>`	执行 Python 表达式
`retry`	重试当前失败的 action
`skip`	跳过当前 action 继续执行
`continue`	继续执行后续 action
`quit`	终止仿真

通过在 task_executor 配置中设置 debug: true 启用调试器。调试器还支持在每个 action 执行前自动保存快照，便于回溯。

源码：fastsim/utils/debugger.py