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

把「关节模组」（行星轮系）在本地用 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/report_spec.md
后端 / 本地方（跑流水线、改脚本）	docs/architecture.md + 各脚本头部注释
只想知道怎么跑	下一节「一条命令跑起来」

---

2. 一条命令跑起来

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/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 第 8 节。