Isaac Sim 导入 URDF 问题排查记录

本文记录一次将 jaka_zu3.urdf 导入 Isaac Sim 的排查过程，目标是生成可用的 USD 机器人模型。

0. 前提

本文使用的本地目录结构如下：

jaka_zu3/
├── jaka_zu3.urdf
└── meshes/
    └── jaka_zu3_meshes/
        ├── Link_0.STL
        ├── Link_1.STL
        ├── Link_2.STL
        ├── Link_3.STL
        ├── Link_4.STL
        ├── Link_5.STL
        └── Link_6.STL

1. 基本导入流程

1.1 启用 URDF Importer

在 Isaac Sim 中打开：

  • Window -> Extensions
  • 搜索并启用 isaacsim.asset.importer.urdf

1.2 打开导入窗口

进入：

  • File -> Import

然后选择 jaka_zu3.urdf。

1.3 初始导入参数

推荐先使用以下保守配置：

  • Referenced Model
  • Static Base
  • Default Density = 1000
  • 初次导入时先关闭：
    • Collision From Visuals
    • Allow Self-Collision
  • 如果模型包含 mimic 关节，可先勾选：
    • Ignore Mimic

1.4 设置 USD 输出目录（可选）

URDF Importer 只能选择输出目录，不能直接命名 USD 文件。Isaac Sim 会自动生成如下结构：

输出目录/URDF文件名/URDF文件名.usd

例如，若输出目录选择为：

~/robot-assets/isaac_assets/

则最终生成的文件通常为：

~/robot-assets/isaac_assets/jaka_zu3/jaka_zu3.usd

2. 主要问题与处理方法

这次导入失败主要集中在以下几类问题：

  • USD 输出目录中已存在旧文件
  • mesh 文件缺失或目录结构不匹配
  • URDF 中的 mesh 路径写法错误
  • Linux 下文件扩展名大小写不一致
  • STL 模型本身不包含材质信息

2.1 USD 输出路径冲突

最初导入时出现如下报错：

A layer already exists with identifier '.../jaka_zu3.usd'

原因： 目标路径下已经存在同名 USD 文件。Importer 会调用 CreateNew，不会直接覆盖旧文件。

处理方法： 删除旧输出目录或旧 USD 文件后重新导入。例如：

rm -rf ~/robot-assets/isaac_assets/jaka_zu3

2.2 只有 URDF，没有 mesh

起初目录中只有：

  • jaka_zu3.urdf

缺少 mesh 文件时，导入容易失败，或者导入后显示为空。

处理方法： 从 JAKA ROS2 仓库补齐 mesh 文件。需要的目录为：

src/jaka_description/meshes/jaka_zu3_meshes

2.3 mesh 目录结构与 URDF 引用不一致

URDF 中引用的路径必须与本地目录结构严格一致，否则需要改 URDF 源码路径。

本文使用的本地目录结构如下：

jaka_zu3/
├── jaka_zu3.urdf
└── meshes/
    └── jaka_zu3_meshes/
        ├── Link_0.STL
        ├── Link_1.STL
        ├── Link_2.STL
        ├── Link_3.STL
        ├── Link_4.STL
        ├── Link_5.STL
        └── Link_6.STL

如果本地目录层级与 URDF 中的引用不一致，即使文件已经下载完成，Importer 仍然无法正确解析资源。

2.4 package:// 写法错误

最初 URDF 中使用了如下写法：

<mesh filename="package://meshes/jaka_zu3_meshes/Link_0.STL"/>

这类写法在当前场景下是错误的。

原因： package:// 表示 ROS package 路径，而不是普通本地相对路径。package://meshes/... 等价于“存在一个名为 meshes 的 ROS 包”，但当前这里只是本地文件夹，并不是 ROS package。

更稳妥的写法： 如果直接从本地目录导入 Isaac Sim，建议使用相对 URDF 文件所在目录的相对路径：

<mesh filename="meshes/jaka_zu3_meshes/Link_0.STL"/>

2.5 Linux 下文件名大小写不一致

这是本次排查中最容易忽略、但影响最大的一个问题。

磁盘中的实际文件名为：

  • Link_0.STL
  • Link_1.STL
  • …

但 URDF 中最初写成了：

  • Link_0.stl
  • Link_1.stl

在 Linux 下，Link_0.stl 和 Link_0.STL 是两个不同文件。结果是 Importer 无法找到 mesh，并最终报错：

RuntimeError: Used null prim

处理方法： 将 URDF 中所有 .stl 统一改为 .STL，保证与磁盘文件名完全一致。

2.6 STL 不包含材质，导入后模型会显示为白色

导入成功后，机械臂模型显示为全白。

原因： JAKA 提供的 ROS 模型只有 .STL 文件，没有：

  • .dae
  • .fbx
  • 贴图
  • 材质文件

STL 只包含几何信息，不包含真实材质。

结论： 模型显示为白色并不代表导入失败，而是“缺少材质信息”这一格式特性带来的正常现象。

3. 可工作的 URDF mesh 写法示例

<visual>
  <origin xyz="0 0 0" rpy="0 0 0" />
  <geometry>
    <mesh filename="meshes/jaka_zu3_meshes/Link_0.STL" />
  </geometry>
</visual>

<collision>
  <origin xyz="0 0 0" rpy="0 0 0" />
  <geometry>
    <mesh filename="meshes/jaka_zu3_meshes/Link_0.STL" />
  </geometry>
</collision>

关键点如下：

  • 不使用 package://
  • 路径与本地目录严格一致
  • 文件扩展名大小写严格一致

4. 导入成功后的补充说明

4.1 颜色与材质

由于 STL 不带材质，导入完成后如需调整外观，需要在 Isaac Sim 中手动赋材质，例如：

  • 创建 OmniPBR
  • 修改 Albedo / Base Color
  • 将材质绑定到对应 link 或整个机器人

4.2 如果希望保留真实外观

需要使用支持材质信息的格式，例如：

  • .dae
  • .fbx
  • .usd

如果官方仓库只提供 STL，则只能在 Isaac Sim 或 Blender 中自行补做材质。

isaac-sim-urdf