DeDeUrdf 图文使用手册

目的

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

访问地址与源码

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

RSReBot 示例文件下载

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

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

命令行下载：

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

这个工具的核心特点：

数据是否上传

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

也就是说：

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

首页

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

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

推荐项目结构

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

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

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

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

导入文件夹

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

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

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

查看零件

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

零件面板大致长这样：

推荐工作方式：

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

3D 预览

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

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

装配节点

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

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

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

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

编辑关节

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

关节编辑器如下：

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

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

URDF 预览

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

保存或导出前建议检查：

保存项目 JSON

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

JSON 通常包含：

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

保存项目 ZIP

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

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

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 包。

典型结构如下：

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 的包。

RSReBot 示例导出的结构如下：

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，并尽量减少路径问题。

从空项目开始

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

从零开始的推荐顺序：

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 前，建议先确认这些设置：

推荐原点表：

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

给 Codex 的复制任务块

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

请打开 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，确认当前线上工具和源码说明是否一致。

常见问题