内容
# Mirage
**基于 AI 的 3D 渲染器 + 轻量级物理模拟器** — 旨在由编程代理（如通过 [MCP](https://modelcontextprotocol.io) 的 Claude Code）驱动，主要用于机器人和合成数据用例。
> **状态：** 🌱 早期框架（`v0.0.1`），现正在调整。数据模型和基于 AI 的控制界面已在无依赖的 *null* 后端上实现；`v0.1` 方向 — **以 OpenUSD 作为场景真实源，搭配小型接口的真实引擎（MuJoCo/Newton 物理，Hydra/Cycles 渲染）** — 在 [docs/design.md](docs/design.md) 中有详细说明。
## 图库
以下每个图像都是通过原生网格内核重放一次操作日志，并使用存储库内的路径追踪器拍摄的 — 无需外部 DCC，无需伪造。
**超越基本图元** — 一架客机完全由引擎自身的运算符建模：通过拉伸创建的表面为机身，带有翼尖的弯曲机翼，带有支撑的圆柱形引擎，全部镜像以实现对称，并赋予每个面不同的涂装，然后进行路径追踪。可以通过 `uv run python examples/airplane.py` 重现。
核心运算符，每个面板（使用 `uv run python docs/gallery/render_gallery.py` 重新生成）：
| | 运算符 | 说明 |
|---|---|---|
| **1** | `screw` | 螺旋扫描 — 在 *沿轴移动* 的过程中旋转一个截面 → 弹簧、螺纹、螺旋钻 |
| **2** | `curvature` 选择器 | 通过平均二面角进行选择查询：扁平的盖子与圆柱主体分离 |
| **3** | `profile` | 一等 2D 生成线 — 一个 **开放** 的线框旋转形成单壁空心花瓶 |
| **4** | `boolean` | 真实的 BSP 网格-网格 CSG（联合 / 差集 / 交集）— 这里是一个立方体减去一个圆柱孔 |
每个建模运算符都在 **C++ 核心和 Python 内核中字节级相同** 实现，并通过差分测试固定，因此一个操作日志在两个引擎中构建相同的网格。
## 为什么
强大的 DCC 工具（如 Blender）具有较大的、带状态的自动化接口，不适合程序化/代理控制。完整的机器人模拟器非常优秀，但很重量级。Mirage 则采取相反的策略：
- **场景 = 普通数据。** 整个世界是一个可序列化的对象（目前为 JSON，以后为 USD）。代理可以读取、差异、编辑和确定性地重现它。
- **小而可替换的后端。** 后端只需消耗一个 `Scene`：`render(scene, camera)` 或 `step(scene, dt)`。从零依赖的空后端开始；在相同接口后插入真实的渲染器（Cycles/Embree/OIDN — 均为许可）或物理引擎（例如 MuJoCo）。
- **基于 AI 的控制界面。** 一等 MCP 服务器将构建/步骤/渲染循环公开为几个正交工具，因此 Claude Code 可以开箱即用地驱动 Mirage。
- **轻量、快速、许可。** Python 协调的核心负责调度；繁重的工作交给原生引擎（OpenUSD、MuJoCo、Hydra/Cycles）的小接口后面。Apache-2.0，无 GPL 纠缠。
## 快速开始
```bash
git clone https://github.com/saofund/mirage
cd mirage
pip install -e .
python examples/falling_box.py
```
## 与 Claude Code 一起使用
此存储库附带了一个 **项目范围** 的 MCP 配置（`.mcp.json`），因此当您将此文件夹作为工作区打开时，Claude Code 会自动拾取 Mirage：
```bash
pip install -e ".[usd,mujoco,mcp,demos]" # 完整功能：USD 场景 + MuJoCo 物理/渲染 + MCP
cd mirage # 项目根目录，.mcp.json 位于此处
claude # 在提示时批准 'mirage' MCP 服务器
```
然后 `/mcp` 显示 `mirage` 已连接。代理可以 **创建** (`add_box`、`add_sphere`、`add_cylinder`、`add_plane`、`add_camera`、`add_light`)、**编辑** (`move`、`set_transform`、`set_material`、`set_velocity`、`remove`、`rename`)、**检查和重现** (`get`、`list_objects`、`get_scene`、`set_scene`、`diff_scene`、`save_scene`、`load_scene`、`get_log`、`replay_log`)，以及 **模拟和查看** (`step`、`render`)。每个工具都返回结构化的 JSON；`render` 返回代理可以查看的 PNG。
独立运行服务器（用于任何其他 MCP 客户端）：
```bash
python -m mirage.mcp_server
```
## 架构
参见 [docs/design.md](docs/design.md) 获取 `v0.1` 设计和路线图（以及 [docs/architecture.md](docs/architecture.md) 获取当前框架）。在一个图表中：
```
代理（Claude Code）
│ MCP 工具
▼
┌───────────┐ 读取 / 写入 ┌──────────┐
│ 引擎 │◀───────────────────▶ │ 场景 │ （JSON / USD）
└───────────┘ └──────────┘
│ │
step() │ │ render()
▼ ▼
物理后端 渲染后端
（空 → MuJoCo） （空 → Cycles/Embree）
```
## 许可证
[Apache-2.0](LICENSE)。
