# 关节模组仿真平台 —— 快速上手

把「关节模组」（行星轮系）在本地用 MuJoCo 跑通，并留好三个接口给网页团队，最终让
「平台内置的关节模组」和「用户上传的关节模组」都能在浏览器里跑仿真、出报告。

> 团队三模块分工：关节模组（本仓库）/ 机械臂 / 四足机器狗。网页用 MuJoCo WASM
> （`@mujoco/mujoco`）展示，引擎与本地 Python 是同一个 C++ 核心，**MJCF（.xml）是统一模型格式**。

**只花 30 秒，先看「目录地图」和「一条命令跑起来」两节就够。**

---

## 1. 目录地图（先读哪个）

```
planetary_joint_split_motor_demo_urdf/
├── README.md                 ★ 你正在看的这份：一页看懂
├── docs/                     ── 给「网页团队」的接口契约 + 详细架构说明
│   ├── schema.md             接口② 配置 schema（观测接口：输入/输出/减速比/限位）
│   ├── report_spec.md        接口③ 报告计算规范（指标 → 公式）
│   └── architecture.md       详细版：脚本语义 / 网页接入 / 用户上传流程 / 占位参数
├── scripts/                  ── 给「后端」的 Python 流水线
│   ├── validate_module.py    一键入口（编排下面三步）
│   ├── urdf_to_mjcf.py       ① URDF → MJCF
│   ├── generate_schema.py    ② URDF → schema
│   └── simulate_report.py    ③ schema → 仿真报告
├── urdf/                     ── 输入案例（原始 URDF + 原始网格，不动）
│   └── planetary_joint_split_motor_demo.urdf
└── output/                   ── 生成产物（每次重跑覆盖）
    ├── planetary_joint_split_motor_demo.xml   MJCF 模型
    ├── planetary_joint_split_motor_demo.json  schema
    ├── report.txt / timeseries.csv / report_curves.png
    └── meshes/               自包含网格副本
```

| 你是谁 | 先读什么 |
|---|---|
| 刚接手、想整体了解 | 本 README 全文（一页） |
| 网页团队（对接三接口） | [docs/schema.md](docs/schema.md) → [docs/report_spec.md](docs/report_spec.md) |
| 后端 / 本地方（跑流水线、改脚本） | [docs/architecture.md](docs/architecture.md) + 各脚本头部注释 |
| 只想知道怎么跑 | 下一节「一条命令跑起来」 |

---

## 2. 一条命令跑起来

```bash
cd scripts
python3 validate_module.py \
    --urdf ../urdf/planetary_joint_split_motor_demo.urdf \
    --input sun_input_joint --output carrier_output_joint \
    --work-dir ../output --plot
```

产出（都在 `../output/`）：MJCF、schema、报告 `report.txt`、观测 `timeseries.csv`、曲线 `report_curves.png`。

依赖：`mujoco`、`numpy`（绘图另需 `matplotlib`，转换另需 `trimesh`）。

> 常用可调参数：`--load-torque`（输出端负载，默认 -3 N·m）、`--damping`（关节阻尼，默认 0.01）、
> `--mode`（`normal` / `overload`）、`--torque-limit`（输入力矩限位，默认 ±10 N·m）。

---

## 3. 三接口契约（给网页团队）

| 接口 | 文件 | 是什么 |
|---|---|---|
| ① 自包含 MJCF | `output/*.xml` + `output/meshes/` | 浏览器加载的模型，含网格/质量/惯量/齿轮约束/电机 |
| ② 配置 schema | [docs/schema.md](docs/schema.md) | 输入/输出关节名、减速比、限位、仿真参数 |
| ③ 报告规范 | [docs/report_spec.md](docs/report_spec.md) | 报告要测哪些值、怎么算 |

一句话：**MJCF 管「怎么动」，schema 管「观测什么」，报告规范管「算出什么」。**

---

## 4. 我要改 X，去哪找

| 想改什么 | 去这里 |
|---|---|
| 材料密度 / 力矩限位 / 阻尼等常数 | `scripts/urdf_to_mjcf.py` 顶部（`DENSITIES`、`TORQUE_LIMIT`、`JOINT_DAMPING`） |
| 减速比来源 / 仿真默认参数 | `scripts/generate_schema.py` 顶部 `DEFAULTS` |
| 报告指标怎么算 | `docs/report_spec.md`（规范）+ `scripts/simulate_report.py`（参考实现） |
| 流水线怎么编排 | `scripts/validate_module.py` |

---

## 5. 待填的占位参数

1. **力矩限位**（默认 ±10 N·m，对应 URDF `effort="1"` 占位）：填真实电机额定值。
2. **关节阻尼**（`JOINT_DAMPING = 0.01`）：报告里 ~98% 的「效率损失」来自这个阻尼，真实摩擦/效率需用实际参数建模。
3. **材料密度**（`urdf_to_mjcf.py` 顶部）：目前无真值。

详见 [docs/architecture.md](docs/architecture.md) 第 8 节。