集成指南

系统要求

安装

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

仿真与可视化

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

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 2）

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

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

# 带安装座变体
python -m mujoco.viewer --mjcf=hand2/hand2_beta2/body/mjcf/right_with_mount.xml

Wuji Hand 2（Beta 2）MJCF 沿用下方 Beta 1 的执行器命名、碰撞策略与显示分组，差异如下：

• 模型命名为 wujihand2-beta2-{left,right}，带安装座变体为 wujihand2-beta2-{left,right}-mount
• 每指尖触觉 pad 为独立 body（{l,r}_{finger}_tip_sensor_frame，浅蓝色外观，{finger} 取值 thumb、index_finger、middle_finger、ring_finger、pinky），自带质量惯量，可直接挂 force / torque 传感器或按 body 查询位姿
• 指尖查询 site（{l,r}_{finger}_tip）与 Beta 1 相同，仍是显示组 3 中的 site

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=hand2/hand2_beta1/body/mjcf/right_with_mount.xml

Wuji Hand 2（Beta 1）MJCF 模型规格：

• 执行器按 {l,r}_{THJ|FFJ|MFJ|RFJ|LFJ}{0-3} 命名，5 个前缀依次对应拇指、食指、中指、无名指、小指，J0 为屈曲根关节，J3 为远端 DIP 关节
• 每手内置 5 个指尖查询 site：thumb_tip、index_finger_tip、middle_finger_tip、ring_finger_tip、pinky_tip（带 l_ / r_ 前缀），用于抓取点查询与指尖轨迹评估
• 碰撞几何取各链接 mesh 的凸包，全部链接参与碰撞，仅排除 10 对装配重叠（各指近节与近节外展对腕部）。指间接触与指尖-手掌接触保持有效
• 显示分组：组 1 视觉外观（银色）、组 2 碰撞几何（半透明浅紫）、组 3 指尖 site
• 指尖软体 mesh（*_tip.STL）随包提供，但未挂为碰撞几何。指尖接触由远节几何承载，接触点略偏离真实指垫

抗冲击转接座

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

MuJoCo Viewer 操作

执行效果

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

ROS2 / RViz

安装

hand/body/ 是 ROS2 包源（wuji_description），安装时会把 hand/attachment/ 与 hand/body-with-soft/ 一并装入包共享目录。请把整个仓库克隆到工作空间 src/，不要单独复制 hand/body/。仓库另含两个独立包：wuji_hand2_beta2_description（包根 hand2/hand2_beta2/body/）对应 Wuji Hand 2（Beta 2），wuji_hand2_beta1_description（包根 hand2/hand2_beta1/body/）对应 Wuji Hand 2（Beta 1）。两个包名不同，可在同一工作空间共存，分别用 colcon build --packages-select wuji_hand2_beta2_description 或 colcon build --packages-select wuji_hand2_beta1_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 的 ROS 版 URDF 经各自独立包构建后解析：Beta 2 为 hand2/hand2_beta2/body/urdf/{left,right}-ros.urdf（包 wuji_hand2_beta2_description），Beta 1 为 hand2/hand2_beta1/body/urdf/{left,right}-ros.urdf（包 wuji_hand2_beta1_description）。带安装座变体 {left,right}_with_mount-ros.urdf 与无座版共用同一 package:// 前缀，包构建一次即可加载任一变体。

RViz 操作

执行效果

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 2）

• 左手：hand2/hand2_beta2/body/usd/left/wujihand2_beta2.usd
• 右手：hand2/hand2_beta2/body/usd/right/wujihand2_beta2.usd
• 带安装座变体：hand2/hand2_beta2/body/usd/{left,right}_with_mount/wujihand2_beta2.usd

Wuji Hand 2（Beta 1）

• 左手：hand2/hand2_beta1/body/usd/left/wujihand2.usd
• 右手：hand2/hand2_beta1/body/usd/right/wujihand2.usd
• 带安装座变体：hand2/hand2_beta1/body/usd/{left,right}_with_mount/wujihand2.usd

Wuji Hand 2 USD 为分层资产（base / physics / robot / sensor 子层与 Logo 纹理），直接点击 Play 时驱动增益保持当前位姿。Beta 2 的 USD 入口为 wujihand2_beta2.usd，无座版根 prim 为 wujihand2_beta2_{side}，带安装座变体为 wujihand2_beta2_{side}_mount，与 Beta 1 资产互不冲突。当前 kp/kv 驱动增益沿用 Wuji Hand 平台标定值，Wuji Hand 2 硬件系统辨识完成后更新。

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

URDF 预览（非 ROS）

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

Wuji Hand 软体变体

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

Wuji Hand 2（Beta 2）

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

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

机械集成

机械臂适配

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

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

集成步骤

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 完成安装

Wuji Hand 2 整机结构件与掌心安装接口

hand2/hand2_beta2/body/step/ 与 hand2/hand2_beta1/body/step/ 提供 Wuji Hand 2 各修订版的整机（带安装座）STEP 源文件，用于机械集成与二次设计：

掌心安装接口

hand2/hand2_beta2/attachment/ 与 hand2/hand2_beta1/attachment/ 提供掌心安装接口交付物，用于自制机械臂侧转接件或工装。每手一对文件：

左右手文件互为镜像，Beta 2 与 Beta 1 的掌心安装接口相同。attachment/ 位于 ROS2 包根 body/ 之外，colcon 不会安装。仿真中模拟已装座的手时，加载 body/ 下的 _with_mount 模型变体。

集成步骤

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

Unitree G1 适配

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

集成说明

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

Wuji Glove 安装附件

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

集成步骤

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