unity2moveit2/UR5_UNITY_IMPORT_GUIDE.md

UR5 Unity 导入指南

本指南提供了在 Unity 中导入 UR5 URDF 机器人的详细步骤。

📋 前提条件

• ✅ Unity 2022.3.57f1c2 LTS 已安装
• ✅ URDF Importer 包已安装 (已在 manifest.json 中配置)
• ✅ UR5 文件已复制到 unity-project/Assets/URDF/UR5/

---

🚀 方法 1: 使用 Assets 右键菜单导入 (推荐)

步骤 1: 打开 Unity 项目

1. 启动 Unity Hub
2. 打开项目：unity-project/
3. 等待 Unity 编译完成 (查看右下角进度条)

步骤 2: 在 Project 窗口中定位 URDF 文件

1. 在 Unity 的 Project 窗口中导航到：

   Assets → URDF → UR5 → urdf → ur5.urdf
   

2. 右键点击 ur5.urdf 文件

步骤 3: 导入 URDF

根据您看到的菜单选项，选择以下之一：

选项 A: 如果看到 "Import Robot from Selected URDF file"

• 点击该选项
• 在导入窗口中配置：
  • Axis Type: Z Axis (ROS 标准)
  • Import Mesh: ✅ 勾选
  • Convex Method: Inherit from Parent
• 点击 Import

选项 B: 如果没有右键菜单选项

• 跳转到 方法 2

---

🛠️ 方法 2: 使用顶部菜单栏导入

步骤 1: 检查菜单位置

在 Unity 编辑器顶部菜单栏中查找以下选项之一：

1. Robotics → Import URDF
2. GameObject → 3D Object → Import URDF
3. Assets → Import Package → URDF Importer
4. Window → Robotics → URDF Importer

步骤 2: 执行导入

如果找到菜单：

1. 点击导入选项
2. 在弹出的文件选择器中，浏览到：

   D:\ros2\DockerRos2Arm-niryo_arm\Unity_MoveIt2\unity-project\Assets\URDF\UR5\urdf\ur5.urdf
   

3. 选择 ur5.urdf 并点击 Open
4. 配置导入设置（同方法 1）
5. 点击 Import

---

🔨 方法 3: 手动创建机器人 GameObject (高级)

如果前两种方法都不可用，可以手动创建：

步骤 1: 创建 UrdfRobot 脚本

在 Assets/Scripts/Core/ 中创建 UrdfRobotImporter.cs：

using UnityEngine;
using Unity.Robotics.UrdfImporter;

public class UrdfRobotImporter : MonoBehaviour
{
    [Header("URDF 导入设置")]
    [Tooltip("URDF 文件路径（相对于 Assets 文件夹）")]
    public string urdfAssetPath = "URDF/UR5/urdf/ur5.urdf";

    [Header("导入选项")]
    public ImportSettings.axisType axisType = ImportSettings.axisType.zAxis;
    public ImportSettings.convexDecomposer convexMethod = ImportSettings.convexDecomposer.unity;

    [ContextMenu("导入 URDF")]
    public void ImportUrdf()
    {
        // 设置导入选项
        ImportSettings settings = new ImportSettings
        {
            choosenAxis = axisType,
            convexMethod = convexMethod
        };

        // 导入 URDF
        GameObject robot = UrdfRobotExtensions.Create(urdfAssetPath, settings);

        if (robot != null)
        {
            Debug.Log($"[UrdfRobotImporter] 成功导入机器人: {robot.name}");
            robot.transform.position = Vector3.zero;
            robot.transform.rotation = Quaternion.identity;
        }
        else
        {
            Debug.LogError("[UrdfRobotImporter] URDF 导入失败！");
        }
    }
}

步骤 2: 使用脚本导入

1. 在 Unity Hierarchy 中创建空 GameObject：

   • 右键 → Create Empty
   • 命名为 UR5_Importer

2. 将 UrdfRobotImporter.cs 脚本附加到该对象

3. 在 Inspector 中：

   • 确认 Urdf Asset Path 为 URDF/UR5/urdf/ur5.urdf
   • 设置 Axis Type 为 Z Axis

4. 右键点击脚本组件 → 选择 "导入 URDF"

5. 检查 Console 输出确认导入成功

---

✅ 验证导入成功

导入成功后，您应该看到：

Hierarchy 窗口

ur5
├── base_link
├── shoulder_link
├── upper_arm_link
├── forearm_link
├── wrist_1_link
├── wrist_2_link
├── wrist_3_link
└── tool0

Inspector 窗口（选中 ur5 对象）

• ✅ 包含 Articulation Body 组件（如果使用 Articulation）
• ✅ 各个子对象包含 Mesh Renderer
• ✅ 包含 Collider 组件

Scene 窗口

• ✅ 能看到蓝色/灰色的 UR5 机器人模型
• ✅ 机器人处于默认姿态

---

🔧 配置机器人适配器

导入成功后，添加必要的组件：

步骤 1: 添加 UniversalRobotAdapter

1. 选中 Hierarchy 中的 ur5 根对象
2. 在 Inspector 中点击 Add Component
3. 搜索并添加 Universal Robot Adapter
4. 配置参数：

   DOF: 6
   Base Link: base_link (拖拽 Hierarchy 中的对象)
   End Effector: tool0 (拖拽 Hierarchy 中的对象)
   Robot Config Path: configs/robots/ur5.yaml
   

步骤 2: 添加 ROSTCPBridge（如需要）

如果场景中还没有 ROS 连接器：

1. 创建空 GameObject：

   • 右键 Hierarchy → Create Empty
   • 命名为 ROSConnection

2. 添加 ROS TCP Bridge 组件：

   • IP Address: 127.0.0.1
   • Port: 10000

步骤 3: 保存场景

1. File → Save As
2. 命名为 UR5_Test.unity
3. 保存到 Assets/Scenes/

---

🧪 测试机器人

测试 1: 关节运动

1. 选中 ur5 对象
2. 在 Inspector 中展开各个子对象
3. 找到 shoulder_pan_joint 的 Articulation Body
4. 在 Play 模式下，尝试修改 Target Position 值
5. 观察机器人运动

测试 2: ROS 连接

1. 确保 Docker 容器运行：

   cd docker
   docker-compose ps
   

2. 点击 Unity 的 Play 按钮

3. 检查 Console 输出：

   • 应看到 [ROSTCPBridge] Connected to ROS2

测试 3: 末端控制器

1. 添加 Interactive End Effector Controller 组件到 tool0 对象
2. 在 Play 模式下，在 Scene 视图中拖拽末端执行器
3. 验证 IK 求解是否工作

---

❌ 常见问题排查

问题 1: 找不到 URDF 导入菜单

可能原因：

• URDF Importer 包未正确加载
• Unity 需要重新编译

解决方案：

1. 关闭 Unity
2. 删除项目中的 Library 文件夹
3. 重新打开项目，等待重新编译
4. 检查 Package Manager (Window → Package Manager)
   - 确认 "URDF Importer" 状态为已安装

问题 2: 导入后模型不可见

可能原因：

• 网格路径错误
• 材质缺失

解决方案：

1. 检查 URDF 中的 mesh 路径是否为相对路径
2. 确认 meshes 文件夹与 urdf 文件夹在同一层级
3. 在 Scene 视图中调整相机位置查看模型

问题 3: 关节不动

可能原因：

• Articulation Body 配置错误
• 关节限位设置问题

解决方案：

1. 检查每个关节的 Articulation Body:
   - Joint Type: Revolute
   - Anchor Position/Rotation: 正确设置
   - Drive: 配置为 Position 或 Velocity 模式
2. 验证 URDF 中的 joint 定义正确

问题 4: 编译错误

错误信息：Assembly 'Unity.Robotics.UrdfImporter' not found

解决方案：

# 在 Unity 编辑器中
1. Window → Package Manager
2. 找到 "URDF Importer"
3. 点击 "Remove" 然后 "Add package from git URL"
4. 输入：https://github.com/Unity-Technologies/URDF-Importer.git?path=/com.unity.robotics.urdf-importer#v0.5.2
5. 等待安装完成

---

📚 参考资源

• Unity Robotics Hub
• URDF Importer 文档
• ROS-TCP-Connector 文档
• 项目主文档：CLAUDE.md

---

📞 获取帮助

如果遇到问题：

1. 检查 Unity Console 中的错误日志
2. 查看 SYSTEM_DESIGN.md 中的架构说明
3. 运行集成测试：python test_ur5_integration.py
4. 查看 Docker 日志：docker logs unity-ros2-system

---

祝您导入成功！ 🚀