chenshijue
4240bb889a
- 三接口契约：自包含 MJCF / 配置 schema / 报告计算规范 - Python 流水线：urdf_to_mjcf → generate_schema → simulate_report（validate_module 一键编排） - 输入案例 urdf + 生成产物 output（自包含 MJCF/schema/报告/网格副本） - 详细架构说明 docs/architecture.md
94 lines
4.5 KiB
Markdown
94 lines
4.5 KiB
Markdown
# 关节模组仿真平台 —— 快速上手
|
||
|
||
把「关节模组」（行星轮系）在本地用 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 节。
|