集成指南

系统要求

安装

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

仿真与可视化

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

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（Beta 1）

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

# 左手
python -m mujoco.viewer --mjcf=hand2/hand2_beta1/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/ 与 hand/body-with-soft/ 一并装入包共享目录。请把整个仓库克隆到工作空间 src/，不要单独复制 hand/body/。仓库另含独立包 wuji_hand2_description（包根 hand2/hand2_beta1/body/），对应 Wuji Hand 2（Beta 1），用 colcon build --packages-select wuji_hand2_description 构建。

# 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

display.launch.py 加载标准 Wuji Hand 模型。构建后，软垫变体 ROS 版 URDF（hand/body-with-soft/urdf/{left,right}-ros.urdf）中的 package:// 路径同样可解析，可在自定义 launch 文件或 robot_state_publisher 中加载。Wuji Hand 2（Beta 1）的 ROS 版 URDF（hand2/hand2_beta1/body/urdf/{left,right}-ros.urdf）经其独立包 wuji_hand2_description 构建后解析。

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（Beta 1）

• 左手：hand2/hand2_beta1/body/usd/left/wujihand2.usd
• 右手：hand2/hand2_beta1/body/usd/right/wujihand2.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（Beta 1）

urdf-viz hand2/hand2_beta1/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/。安装附件 STEP 见 3.3.4 Wuji Glove 安装附件。

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

机械集成

3.3.1 机械臂适配

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

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

集成步骤

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

3.3.2 Wuji Hand 2（Beta 1）整机结构件

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

集成步骤

1. 用 FreeCAD、SolidWorks、Creo 等任意支持 STEP 的 CAD 工具打开 STEP 文件
2. 参考左右手整机装配确认安装面与对位关系

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 标准安装面。

3.3.4 Wuji Glove 安装附件

glove/attachment/ 提供 Wuji Glove 安装附件的 STEP 装配文件（AP214），用于机械集成：

集成步骤

1. 用 FreeCAD、SolidWorks、Creo 等任意支持 STEP 的 CAD 工具打开 STEP 文件
2. 参考装配结构确认安装面与对位关系
3. 按目标设备安装孔位做适配修改，完成装配