---
title: DeDeUrdf 图文使用手册
description: 从导入 STL、JSON、ZIP 到编辑 link/joint、预览 URDF、导出 MuJoCo ZIP 的完整操作流程。
---

## 目的

DeDeUrdf 是一个纯 Web 端 URDF 装配工具，适合把 Fusion 360、SolidWorks、Onshape 等 CAD 软件导出的多个 STL 零件，整理成可保存、可继续编辑、可导出 URDF 的机器人模型项目。

## 访问地址与源码

| 入口 | 地址 |
| --- | --- |
| 在线体验 | [https://dedeurdf.vercel.app/](https://dedeurdf.vercel.app/) |
| 开源仓库 | [https://github.com/lintheyoung/DeDeUrdf](https://github.com/lintheyoung/DeDeUrdf) |

DeDeUrdf 是开源项目。需要本地二次开发、审计隐私边界、检查 MuJoCo ZIP 导出逻辑，或自行部署到服务器时，建议先阅读开源仓库里的 `README.md`、`PRIVACY.md` 和 `DEPLOYMENT.md`。

## RSReBot 示例文件下载

RSReBot 的 CAD 源文件、DeDeUrdf 项目文件和 MuJoCo URDF 包已经放在公开下载地址里。读者可以按自己的用途下载对应文件，不一定要全部下载。

| 文件 | 大小 | 适合场景 | 下载 |
| --- | --- | --- | --- |
| `RSReBot.f3z` | 约 17.8MB | Fusion 360 原始项目归档，适合继续编辑 CAD、检查装配关系、重新导出 STL | [下载 F3Z](https://pub-6c1e280a27614b05891bfd818585735e.r2.dev/RSReBot/RSReBot.f3z) |
| `RSReBot.step` | 约 16.3MB | 通用 CAD 交换格式，适合 SolidWorks、FreeCAD、Onshape 等工具查看或转换 | [下载 STEP](https://pub-6c1e280a27614b05891bfd818585735e.r2.dev/RSReBot/RSReBot.step) |
| `RSReBot_accurate_web_project.zip` | 约 9.6MB | DeDeUrdf 可继续编辑项目，打开 DeDeUrdf 后点击“导入 JSON/ZIP”选择它 | [下载 DeDeUrdf 项目 ZIP](https://pub-6c1e280a27614b05891bfd818585735e.r2.dev/RSReBot/RSReBot_accurate_web_project.zip) |
| `RSReBot_fluxweave_dm_mujoco_urdf.zip` | 约 20.2MB | MuJoCo 可加载的 URDF 包，包含 `urdf/` 和 `meshes/`，适合仿真验证和轨迹控制脚本 | [下载 MuJoCo URDF ZIP](https://pub-6c1e280a27614b05891bfd818585735e.r2.dev/RSReBot/RSReBot_fluxweave_dm_mujoco_urdf.zip) |

如果只是想在 DeDeUrdf 里查看和继续编辑模型，优先下载 `RSReBot_accurate_web_project.zip`。如果只是想在 MuJoCo 里加载和跑控制，优先下载 `RSReBot_fluxweave_dm_mujoco_urdf.zip`。如果要回到 CAD 源头重新测量原点、导出 STL 或修改结构，再下载 `RSReBot.f3z` 或 `RSReBot.step`。

命令行下载：

```bash
mkdir -p RSReBot-assets
curl -L -o RSReBot-assets/RSReBot.f3z \
  https://pub-6c1e280a27614b05891bfd818585735e.r2.dev/RSReBot/RSReBot.f3z
curl -L -o RSReBot-assets/RSReBot.step \
  https://pub-6c1e280a27614b05891bfd818585735e.r2.dev/RSReBot/RSReBot.step
curl -L -o RSReBot-assets/RSReBot_accurate_web_project.zip \
  https://pub-6c1e280a27614b05891bfd818585735e.r2.dev/RSReBot/RSReBot_accurate_web_project.zip
curl -L -o RSReBot-assets/RSReBot_fluxweave_dm_mujoco_urdf.zip \
  https://pub-6c1e280a27614b05891bfd818585735e.r2.dev/RSReBot/RSReBot_fluxweave_dm_mujoco_urdf.zip
```

这个工具的核心特点：

| 能力 | 说明 |
| --- | --- |
| 导入单个 STL | 快速查看某个零件的方向、尺寸和坐标位置 |
| 导入文件夹 | 一次导入 `base.stl`、`link1.stl`、`link2.stl` 等多个零件 |
| 导入项目 JSON/ZIP | 继续打开之前保存的 DeDeUrdf 项目 |
| 编辑 link | 修改 link 名称、mesh 文件、颜色和装配节点 |
| 编辑 joint | 修改 parent、child、type、axis、origin、limit 等 URDF 关节参数 |
| 3D 预览 | 查看整机或单个零件的装配效果 |
| URDF 预览 | 在浏览器里直接查看生成的 URDF 文本 |
| 导出 URDF ZIP | 导出通用 URDF 包 |
| 导出 MuJoCo ZIP | 导出更适合 MuJoCo 直接加载的 URDF 包 |

## 数据是否上传

DeDeUrdf 目前是前端本地工具。用户选择的 STL、JSON、ZIP 会在浏览器里读取、解析、预览和打包，正常使用时不会上传到 Vercel 服务器。

也就是说：

| 操作 | 是否上传到服务器 |
| --- | --- |
| 导入 STL | 不上传，浏览器本地读取 |
| 导入项目 JSON | 不上传，浏览器本地读取 |
| 导入项目 ZIP | 不上传，浏览器本地解压 |
| 3D 预览 | 不上传，浏览器本地渲染 |
| 保存 JSON | 不上传，浏览器本地下载 |
| 保存项目 ZIP | 不上传，浏览器本地打包下载 |
| 导出 URDF ZIP | 不上传，浏览器本地打包下载 |

如果未来改成带账号、云端项目管理、团队协作或服务器批处理，才需要重新设计文件上传、对象存储、权限和隐私策略。

## 首页

打开 DeDeUrdf 后，会看到顶部工具栏、左侧项目/零件区域、中间 3D STL 预览、下方装配节点，以及右侧关节和 URDF 预览。

![DeDeUrdf 首页](/images/dedeurdf/usage/01-home.png)

顶部工具栏提供常用入口：

![顶部工具栏](/images/dedeurdf/usage/06-toolbar-crop.png)

| 按钮 | 用途 |
| --- | --- |
| MuJoCo 示例 | 加载内置 RSReBot 示例模型 |
| 导入 JSON/ZIP | 打开之前保存的项目 JSON，或打开包含项目和 STL 的项目 ZIP |
| 导入文件夹 | 一次选择一个包含多个 STL 的本地文件夹 |
| 保存 JSON | 保存当前装配关系和参数，不包含 STL 实体 |
| 保存项目 ZIP | 保存项目 JSON 和当前 STL，适合继续调试 |
| 导出 URDF ZIP | 导出通用 URDF + meshes 文件夹 |
| 导出 MuJoCo ZIP | 导出更适合 MuJoCo 加载的 URDF + meshes 文件夹 |

## 推荐项目结构

如果是机械臂，建议先把 STL 文件整理成稳定、可读的命名。

```text
MyRobot/
  base.stl
  link1.stl
  link2.stl
  link3.stl
  link4.stl
  link5.stl
  link6.stl
  end.stl
```

RSReBot 当前示例使用的是这个结构：

| 文件 | 推荐含义 |
| --- | --- |
| `base.stl` | 底座 |
| `link1.stl` | 第一轴旋转座 |
| `link2.stl` | 大臂 |
| `link3.stl` | 小臂/肘后段 |
| `link4.stl` | 腕部 pitch 支架 |
| `link5.stl` | 腕部/夹爪过渡旋转件 |
| `link6.stl` | 夹爪安装基座 |
| `end.stl` | 末端夹爪或末端工具 |

如果你的机器人不是 6 轴机械臂，也可以使用自己的命名。重要的是：每个 STL 对应一个 URDF `link`，相邻 link 之间通过一个 `joint` 连接。

## 导入文件夹

点击“导入文件夹”，选择包含 STL 的目录。浏览器通常会要求确认读取整个文件夹，这是正常的。

导入后，左侧会出现零件列表，中间 3D 视图会显示整机预览。

![导入文件夹后的界面](/images/dedeurdf/usage/02-imported-folder.png)

导入后建议马上检查三件事：

| 检查项 | 目标 |
| --- | --- |
| 零件数量 | 是否和 STL 文件数量一致 |
| 整体姿态 | 是否上下、前后、左右方向大体正确 |
| 单位尺寸 | 模型是否过大或过小，是否把 mm 当成 m 使用 |

## 查看零件

点击左侧某个零件，会进入“选中部件”视图。这个视图适合检查单个 link 的 mesh、颜色、坐标位置和装配节点。

![选中部件](/images/dedeurdf/usage/03-selected-part.png)

零件面板大致长这样：

![零件面板](/images/dedeurdf/usage/08-parts-panel-crop.png)

推荐工作方式：

1. 先点击 `base`，确认底座方向正确。
2. 再按机械臂链路顺序检查 `link1` 到 `link6`。
3. 最后检查 `end` 或夹爪是否贴合在末端。
4. 如果某个零件飞到很远，优先检查它的 STL 原点、joint origin 和是否重复做了坐标变换。

## 3D 预览

3D 预览区支持整机和选中部件两种模式。

![3D 预览局部](/images/dedeurdf/usage/09-preview-panel-crop.png)

| 模式 | 适合做什么 |
| --- | --- |
| 整机 | 看整体装配是否正确 |
| 选中部件 | 单独检查某个 STL 的姿态和原点 |

如果画面里只有一个零件，看不到全部模型，通常是因为当前处在“选中部件”模式。切回“整机”即可看到完整装配。

## 装配节点

装配节点用于理解 link 和 joint 的拓扑关系。每个蓝色节点通常代表一个 link，每条连接线代表一个 joint。

![装配节点](/images/dedeurdf/usage/10-graph-panel-crop.png)

一个标准 6 轴机械臂通常是链式结构：

```text
base_link
  -> joint1 -> link1
  -> joint2 -> link2
  -> joint3 -> link3
  -> joint4 -> link4
  -> joint5 -> link5
  -> joint6 -> link6
  -> end_joint -> end_link
```

如果拓扑看起来有分叉，或者某个零件没有连接到主链路，要检查：

| 问题 | 常见原因 |
| --- | --- |
| 末端零件飞出去 | `end_joint` 的 `origin` 或 `rpy` 不对 |
| 两个 link 重叠 | 相邻 joint 的 `origin xyz` 过小或方向反了 |
| 关节旋转方向反了 | `axis` 正负号反了 |
| 整体方向歪了 | 某个 joint 的 `rpy` 坐标系变换不对 |

## 编辑关节

点击右侧“关节”区域中的某个 joint，可以编辑关节参数。

![关节列表](/images/dedeurdf/usage/11-joints-panel-crop.png)

关节编辑器如下：

![关节编辑器](/images/dedeurdf/usage/12-joint-editor-crop.png)

URDF 里最关键的是这些字段：

| 字段 | 说明 |
| --- | --- |
| `name` | 关节名，例如 `joint1` |
| `type` | 关节类型，常用 `fixed`、`revolute`、`continuous`、`prismatic` |
| `parent` | 父 link |
| `child` | 子 link |
| `origin xyz` | child 坐标系相对 parent/joint 的平移，单位通常是米 |
| `origin rpy` | child 坐标系相对 parent/joint 的旋转，单位是弧度 |
| `axis xyz` | 关节运动轴，在关节坐标系下定义 |
| `limit lower/upper` | 运动下限和上限，旋转关节单位是弧度 |
| `effort` | 最大力或力矩 |
| `velocity` | 最大速度 |

机械臂建模时，最容易出错的是 `origin xyz` 和 `origin rpy`。如果你在 Fusion 360 里测到的是毫米，需要除以 1000 后写入 URDF。例如 86.8mm 应写成 `0.086800`。

## URDF 预览

右侧 URDF 预览会显示当前项目生成的 URDF 文本。

![URDF 预览](/images/dedeurdf/usage/05-urdf-preview.png)

保存或导出前建议检查：

| 检查项 | 示例 |
| --- | --- |
| `robot name` | 是否是你的机器人名称 |
| link 名称 | 是否是 `base_link`、`link1`、`link2` 等稳定名称 |
| mesh 路径 | 是否指向 `meshes/base.stl` 或 `../meshes/base.stl` |
| joint parent/child | 是否按机械臂链路顺序连接 |
| joint origin 单位 | 是否已经从 mm 转成 m |
| joint limit | 是否有合理上下限 |

## 保存项目 JSON

“保存 JSON”会下载一个项目配置文件，适合轻量保存参数和拓扑关系。

JSON 通常包含：

| 内容 | 是否包含 |
| --- | --- |
| link 名称 | 包含 |
| joint 参数 | 包含 |
| 颜色 | 包含 |
| mesh 文件名 | 包含 |
| STL 二进制内容 | 不包含 |

因此，单独 JSON 适合和原始 STL 文件夹一起保存。如果你只发 JSON 给别人，对方还需要拿到同名 STL 文件。

## 保存项目 ZIP

“保存项目 ZIP”会把项目 JSON 和 STL 一起打包，适合多人协作和反复调试。

推荐在每次关键调整后保存一个版本：

```text
RSReBot_v01_imported.zip
RSReBot_v02_joint1_fixed.zip
RSReBot_v03_end_aligned.zip
RSReBot_v04_mujoco_ready.zip
```

以后再次打开时，点击“导入 JSON/ZIP”，选择这个 ZIP，即可恢复项目和 STL。

## 导出 URDF ZIP

点击“导出 URDF ZIP”会下载通用 URDF 包。

![导出 URDF ZIP](/images/dedeurdf/usage/13-export-urdf-button-crop.png)

典型结构如下：

```text
my_robot_urdf.zip
  robot.urdf
  meshes/
    base.stl
    link1.stl
    link2.stl
    ...
```

通用 URDF ZIP 适合 ROS、RViz、Pinocchio、Drake 或其他 URDF 解析流程。不同工具对 mesh 路径和 STL 编码格式要求不同，如果加载失败，优先检查 mesh 相对路径和 STL 是否是 binary STL。

## 导出 MuJoCo ZIP

点击“导出 MuJoCo ZIP”会下载更适合 MuJoCo 的包。

![导出 MuJoCo ZIP](/images/dedeurdf/usage/14-export-mujoco-button-crop.png)

RSReBot 示例导出的结构如下：

```text
RSReBot_fluxweave_dm_mujoco_urdf.zip
  project.fluxweave.json
  README_mujoco.txt
  urdf/
    RSReBot_fluxweave_dm_mujoco.urdf
  meshes/
    base.stl
    link1.stl
    link2.stl
    link3.stl
    link4.stl
    link5.stl
    link6.stl
    end.stl
```

MuJoCo ZIP 的目标是让用户解压后可以直接找到 URDF 和 meshes，并尽量减少路径问题。

## 从空项目开始

空项目时，左侧项目区和预览区会比较空。

![空项目面板](/images/dedeurdf/usage/15-empty-project-panel-crop.png)

![空预览区](/images/dedeurdf/usage/16-empty-preview-crop.png)

从零开始的推荐顺序：

1. 在 CAD 里导出所有 link 的 STL。
2. 确认每个 STL 的原点在对应关节或装配基准上。
3. 用统一命名整理文件夹。
4. 导入文件夹。
5. 按链路顺序建立或检查 link。
6. 按链路顺序填写 joint。
7. 先用整机预览检查外观。
8. 再用 URDF 预览检查文本。
9. 保存项目 ZIP。
10. 导出 MuJoCo ZIP。
11. 用 MuJoCo 或本仓库脚本加载测试。

## Fusion 360 导出建议

从 Fusion 360 导出 STL 前，建议先确认这些设置：

| 项目 | 推荐做法 |
| --- | --- |
| 零件原点 | 尽量放在该 link 的关节中心或装配基准 |
| 单位 | 记录当前是 mm 还是 m |
| 坐标方向 | 保持所有 link 使用同一机器人坐标习惯 |
| 文件名 | 使用稳定英文名，不要频繁改名 |
| 导出方式 | 一个 link 一个 STL，不要把整机一次性导成一个 STL |
| 尺寸核对 | 导出后用 DeDeUrdf 或其他查看器确认尺寸 |

推荐原点表：

| STL | 推荐原点 |
| --- | --- |
| `base.stl` | 底座中心，最好在第一轴旋转中心线上 |
| `link1.stl` | `joint1` 旋转中心 |
| `link2.stl` | `joint2` 旋转中心 |
| `link3.stl` | `joint3` 旋转中心 |
| `link4.stl` | `joint4` 旋转中心 |
| `link5.stl` | `joint5` 旋转中心 |
| `link6.stl` | `joint6` 或夹爪安装基准中心 |
| `end.stl` | 末端工具安装基准或 TCP 附近参考点 |

如果导出后才发现原点不合适，也可以在 DeDeUrdf 里通过 joint origin 补偿，但长期维护上更推荐在 CAD 源文件里把基准关系整理清楚。

## 给 Codex 的复制任务块

下面这段可以直接复制给 Codex，让它在本地或浏览器里帮你检查一次 DeDeUrdf 流程。

```md
请打开 https://dedeurdf.vercel.app/ 并帮我测试 DeDeUrdf：

1. 下载 DeDeUrdf 项目 ZIP：
   https://pub-6c1e280a27614b05891bfd818585735e.r2.dev/RSReBot/RSReBot_accurate_web_project.zip
2. 打开 https://dedeurdf.vercel.app/。
3. 点击“导入 JSON/ZIP”，选择刚下载的 `RSReBot_accurate_web_project.zip`。
4. 切换到“整机”预览，截图确认所有 link 都在正确位置。
5. 进入关节面板，检查 joint1 到 joint6 的 parent/child、axis、origin、limit 是否存在。
6. 点击“保存项目 ZIP”，确认能下载包含 project JSON 和 meshes 的 ZIP。
7. 点击“导出 MuJoCo ZIP”，确认 ZIP 内包含 urdf/、meshes/ 和 README_mujoco.txt。
8. 如果导出的 ZIP 可以被 MuJoCo 加载，请把加载命令、模型 body/joint/geom/mesh 数量和截图结果写回给我。
9. 同时参考开源仓库 https://github.com/lintheyoung/DeDeUrdf，确认当前线上工具和源码说明是否一致。
```

## 常见问题

| 现象 | 可能原因 | 处理方式 |
| --- | --- | --- |
| 只看到一个零件 | 当前是“选中部件”模式 | 切回“整机” |
| 夹爪飞到很远 | `end_joint` 的 `origin/rpy` 不对，或 mesh 变换重复 | 检查 joint 参数和 STL 原点 |
| 两个 link 不贴合 | 相邻关节的 `origin xyz` 不准确 | 回 CAD 测两个关节原点的相对位置 |
| 旋转方向反了 | `axis` 正负号反了 | 把 `axis` 从 `0 0 1` 改成 `0 0 -1` 或反过来 |
| MuJoCo 加载失败 | mesh 路径、STL 编码或关节参数不符合要求 | 优先导出 MuJoCo ZIP，再用本仓库脚本验证 |
| 浏览器卡顿 | STL 太大或三角面太多 | 在 CAD 中导出低一点精度的 STL |