# 架构设计

## 设计目标

SimKit 是一个**仿真器无关**的场景工具包，旨在提供统一的接口来接入多种机器人仿真器，支持**仿真测试**和**数据生成**两大核心应用场景。

### 设计原则

1. **仿真器无关性**：核心模块与具体仿真器解耦，通过标准化接口接入不同仿真后端
2. **模块化设计**：各功能模块可独立替换、组合使用
3. **快速接入**：支持多种接入方式（文件格式、API 接口、函数调用）
4. **统一数据格式**：定义通用的场景描述格式，实现跨仿真器复用

---

## 整体架构

```
+------------------------------------------------------------------+
|                    上层应用 (Applications)                        |
|  +---------------------+       +---------------------+            |
|  |   仿真测试           |       |   数据生成          |            |
|  |   Simulation Test   |       |   Data Generation   |            |
|  +---------------------+       +---------------------+            |
+------------------------------------------------------------------+
                              ^
                              |
+------------------------------------------------------------------+
|                  仿真器无关模块 (Simulator-Agnostic)               |
|  +--------------+  +--------------+  +--------------+            |
|  |  场景定义     |  |  资产生成     |  |  产品布局     |            |
|  |Scene Schema  |  |Asset Gen     |  |Layout Gen    |            |
|  +--------------+  +--------------+  +--------------+            |
|  +--------------+  +--------------+  +--------------+            |
|  |  坐标变换     |  |  通用工具     |  |  配置管理     |            |
|  |Transforms    |  |Utilities     |  |Config        |            |
|  +--------------+  +--------------+  +--------------+            |
+------------------------------------------------------------------+
                              ^
                              |
+------------------------------------------------------------------+
|               仿真器适配层 (Simulator Adapters)                   |
|  +------------+  +------------+  +------------+  +-----------+   |
|  | ManiSkill  |  | SAPIEN     |  | MuJoCo     |  | ISAC      |   |
|  | Adapter    |  | Adapter    |  | Adapter    |  | Adapter   |   |
|  +------------+  +------------+  +------------+  +-----------+   |
|  +------------+  +------------+  +------------+                  |
|  | Isaac Gym  |  | PyBullet   |  | ...        |                  |
|  | Adapter    |  | Adapter    |  | (可扩展)    |                  |
|  +------------+  +------------+  +------------+                  |
+------------------------------------------------------------------+
```

---

## 仿真器接入方式

SimKit 支持**三种**仿真器接入方式：

### 方式 1：文件格式接入

通过标准化的场景文件（YAML/JSON）描述场景，各仿真器适配器负责解析：

```yaml
# scene.yaml
scene:
  objects:
    - name: table
      asset: assets/table.urdf
      pose: [0, 0, 0, 0, 0, 0, 1]
    - name: cube
      asset: assets/cube.urdf
      pose: [0.5, 0, 0.5, 0, 0, 0, 1]
  lighting:
    type: directional
    intensity: 1000
```

**优点：**
- 仿真器无关，易于分享和版本控制
- 可离线生成，批量创建场景
- 支持人工编辑和程序生成

**支持格式：** YAML, JSON, USD, MJCF, URDF

---

### 方式 2：API 接口接入

通过统一的 Python API 动态创建场景：

```python
from simkit.core.scene import SceneBuilder

scene = SceneBuilder()
scene.add_object("table", pose=[0, 0, 0])
scene.add_object("cube", pose=[0.5, 0, 0.5])
scene.save("scene.yaml")

# 加载到仿真器
from simkit.simulators.maniskill import ManiSkillAdapter
adapter = ManiSkillAdapter()
env = adapter.create_env(scene)
```

**优点：**
- 程序化控制，灵活生成复杂场景
- 支持运行时动态修改
- 易于集成到现有工作流

---

### 方式 3：模块化/函数接入

直接调用仿真器特定的函数或模块：

```python
from simkit.simulators.maniskill import create_pick_env
from simkit.simulators.mujoco import load_mjcf

# ManiSkill 专用函数
env = create_pick_env(object_type="cube")

# MuJoCo 专用函数
model = load_mjcf("scene.xml")
```

**优点：**
- 充分利用仿真器特性
- 性能最优（无转换开销）
- 适合深度集成场景

---

## 端到端任务流程

### 仿真测试流程

1. 定义场景 (YAML/API)
2. 选择仿真器
3. 加载场景到仿真器
4. 运行控制算法
5. 收集观测数据
6. 分析结果

### 数据生成流程

1. 配置场景参数
2. 设置相机和渲染配置
3. 批量生成场景变体
4. 并行渲染
5. 导出标注数据 (RGB/D/Seg/BBox)

---

## 扩展指南

### 添加新仿真器

1. 创建适配器类继承 `SimulatorAdapter`
2. 实现场景加载接口
3. 实现观测/动作接口
4. 注册到仿真器列表

### 添加新模块

1. 确定模块类型 (仿真器无关/相关)
2. 遵循模块接口规范
3. 编写单元测试
4. 更新文档