Description 使用说明

1. 概述

wuji-description 是 Wuji Hand 及相关硬件的模型描述包，提供 URDF、MuJoCo (MJCF)、Isaac Sim USD 与 STEP/CAD 资源，用于仿真、可视化和机械集成。

覆盖范围

关联仓库

wuji-description 作为模型仓库，被以下项目作为依赖引用：

这些仓库通过 Git Submodule 机制引用 wuji-description，确保模型文件版本一致。如需更新模型，可在各仓库中执行：

git submodule update --remote

2. 系统要求

3. 集成指南

3.1 安装

git clone https://github.com/wuji-technology/wuji-description.git
cd wuji-description

3.2 仿真与可视化

本仓库为主流仿真/可视化生态提供模型资源，按所用工具选择对应小节。

3.2.1 MuJoCo

Wuji Hand

# 右手
python -m mujoco.viewer --mjcf=hand/body/mjcf/right.xml

# 左手
python -m mujoco.viewer --mjcf=hand/body/mjcf/left.xml

Wuji Hand 软垫变体

# 右手
python -m mujoco.viewer --mjcf=hand/body-with-soft/mjcf/right.xml

# 左手
python -m mujoco.viewer --mjcf=hand/body-with-soft/mjcf/left.xml

# 简化碰撞变体（加速接触仿真）
python -m mujoco.viewer --mjcf=hand/body-with-soft/mjcf/right_simplified.xml

Wuji Hand 2

# 右手
python -m mujoco.viewer --mjcf=hand2/body/mjcf/right.xml

# 左手
python -m mujoco.viewer --mjcf=hand2/body/mjcf/left.xml

抗冲击转接座

python -m mujoco.viewer --mjcf=hand/attachment/impact-resistant-attachment/mjcf/docking.xml

MuJoCo Viewer 操作

执行效果

以左手为示例，其他模型按上述命令自行加载查看。

3.2.2 ROS2 / RViz

安装

hand/body/ 是 ROS2 包源（wuji_description），安装时会把 hand/attachment/ 作为兄弟资源一并安装。请把整个仓库克隆到工作空间 src/，不要单独复制 hand/body/。

# 1. 加载 ROS2 环境，替换 <distro> 为实际安装的 ROS2 发行版
source /opt/ros/<distro>/setup.bash

# 2. 创建工作空间（如不存在）
mkdir -p ~/ros2_ws/src

# 3. 克隆仓库
cd ~/ros2_ws/src
git clone https://github.com/wuji-technology/wuji-description.git

# 4. 初始化 rosdep（首次使用，已初始化可跳过）
sudo rosdep init
rosdep update

# 5. 安装依赖
cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y

# 6. 构建并 source
colcon build --packages-select wuji_description
source install/setup.bash

可视化

# 左手（默认）
ros2 launch wuji_description display.launch.py

# 右手
ros2 launch wuji_description display.launch.py hand:=right

RViz 操作

执行效果

3.2.3 Isaac Sim USD

仓库提供以下 Isaac Sim USD 资源：

Wuji Hand

• 左手：hand/body/usd/left/wujihand.usd
• 右手：hand/body/usd/right/wujihand.usd

Wuji Hand 软垫变体

• 左手：hand/body-with-soft/usd/left/wujihand.usd
• 右手：hand/body-with-soft/usd/right/wujihand.usd
• 简化碰撞变体：hand/body-with-soft/usd/{left,right}_simplified/wujihand.usd

Wuji Hand 2

• 左手：hand2/body/usd/left/wujihand.usd
• 右手：hand2/body/usd/right/wujihand.usd

在 Isaac Sim 中打开对应 .usd 文件即可加载。完整仿真示例参见 isaaclab-sim。

3.2.4 URDF 预览（非 ROS）

不安装 ROS 时，可用任意 URDF 查看器（如 urdf-viz）直接预览 URDF 模型。

Wuji Hand 软垫变体

urdf-viz hand/body-with-soft/urdf/right.urdf

Wuji Hand 2

urdf-viz hand2/body/urdf/right.urdf

抗冲击转接座

urdf-viz hand/attachment/impact-resistant-attachment/urdf/docking.urdf

Wuji Glove

glove/body/ 提供用于手部动作追踪的 Wuji Glove 模型。每只手由 URDF 骨架描述（五指共 21 个 revolute 关节），腕部装有 EMF 发射底座（base_link_TX.STL），指尖各装有接收线圈（base_link_RX.STL）。发射器顶盖 STEP 与装配 PDF 在 glove/body/step/。

urdf-viz glove/body/urdf/right.urdf

3.3 机械集成

3.3.1 机械臂适配

hand/attachment/step/ 提供两种适配器，用于将 Wuji Hand 安装到机械臂末端法兰：

抗冲击转接座的工作原理与组件名称详见 5.3 抗冲击转接座。

集成步骤

1. 用 FreeCAD、SolidWorks、Creo 等任意支持 STEP 的 CAD 工具打开 STEP 文件
2. 按目标机械臂法兰孔位做适配修改
3. 参考装配 PDF 图纸（wuji-hand&*-assembled-v1.pdf）确认装配关系
4. 按 Adapter-Installation-Instructions.md 完成安装

3.3.2 Wuji Hand 2 结构件与适配挂载件

hand2/body/step/ 提供 Wuji Hand 2 的 STEP 源文件，用于机械集成与二次设计：

集成步骤

1. 用 FreeCAD、SolidWorks、Creo 等任意支持 STEP 的 CAD 工具打开 STEP 文件
2. 参考左右手结构件装配确认安装面与对位关系
3. 按目标机械臂法兰孔位修改适配挂载件，完成装配

3.3.3 Unitree G1 适配

hand/attachment/unitree-g1-attachment/unitree-g1-docking-adapter.stl 用于将 Wuji Hand 安装到 Unitree G1 人形机器人末端。

集成说明

文件为 STL 格式，可直接 3D 打印（建议尼龙或 PETG 材质保证刚性）。打印件一端对接 G1 末端法兰，另一端连接 Wuji Hand 标准安装面。

4. 相关仓库

4.1 MuJoCo 仿真示例

mujoco-sim 提供了在 MuJoCo 物理仿真器中加载和控制 Wuji Hand 的最小示例。

运行命令

git clone --recursive https://github.com/wuji-technology/mujoco-sim.git
cd mujoco-sim
pip install -r requirements.txt
python run_sim.py

预期效果

脚本启动后将加载右手模型（默认），循环播放 data/wave.npy 中预录制的挥手动作轨迹。如需切换为左手，修改 run_sim.py 中的 side 变量为 "left"。

4.2 Isaac Lab 仿真示例

isaaclab-sim 提供了在 NVIDIA Isaac Lab 环境中使用 Wuji Hand 的仿真示例，支持 GPU 加速的大规模并行仿真，适用于强化学习训练场景。

运行命令

git clone --recurse-submodules https://github.com/wuji-technology/isaaclab-sim.git
cd isaaclab-sim
# 按照 Isaac Lab 官方文档配置环境后执行
python run_sim.py

预期效果

脚本启动后将加载右手模型（默认），循环播放 data/wave.npy 中预录制的挥手动作轨迹。如需切换为左手，运行 python run_sim.py --side left。

4.3 手势 Retargeting

wuji-retargeting 是基于自适应解析优化的高精度手势 Retargeting 系统，将人手姿态映射到灵巧手关节位置，支持 Apple Vision Pro 实时手部追踪。

运行命令

git clone --recurse-submodules https://github.com/wuji-technology/wuji-retargeting.git
cd wuji-retargeting
pip install -r requirements.txt
pip install -e .

# 仿真示例（使用预录制数据）
cd example
python teleop_sim.py --play data/avp1.pkl --hand left

# 真机示例（需连接 Vision Pro）
python teleop_real.py --input visionpro --ip <vision-pro-ip> --hand right

预期效果

仿真模式下，灵巧手将回放预录制的手势数据。真机模式下，灵巧手将实时跟随 Vision Pro 捕获的手部动作。系统采用 Huber loss + NLopt SLSQP 优化算法，在捏合和张开手势之间自适应切换以提高精度。

5. 故障排查

RViz 不显示模型

确保执行 source install/setup.bash。

rosdep 未初始化

执行 rosdep install 时若提示 rosdep has not been initialized，首次使用前需要初始化 rosdep：

sudo rosdep init
rosdep update