Rokid UXR3.0 手势算法与接入实践（v3.0.3）—设备适配、能力边界与示例代码

一、背景：从"通用手势链路"到"UXR3.0 实际可用能力"

在计算机视觉领域，通用的单目 3D 手势识别通常包含：手部检测→关键点/骨骼回归→（可选）Mesh 拟合→时序稳定→手势状态机→交互事件。但该链路仅作为原理性背景。实际开发需以"平台 SDK 提供的手势能力与接口"为准，避免超出当前设备与版本的支持范围。

二、版本与设备适配矩阵

三、UXR3.0（v3.0.3）手势开发入门

1）工程前置

已导入并接入 RKInput 组件，将多模态交互设置为 Gesture。
手势交互依赖 Max Pro 眼镜；连接并确认追踪正常。

2）自定义手势组件（以 RKHand 为例）

方式 A：将 RKHand 预制体拖入场景层级视图进行修改，事件输入模块会优先使用场景中的 RKHand。
方式 B：将 "Rokid Unity XR SDK/Runtime/Resources/Prefabs/Interactor/" 下的 RKHand 复制到 "Assets/Resources/Prefabs/Interactor/" 并修改；加载程序会优先加载项目 Resources 路径下的 RKHand，从而覆盖默认配置。
具体参数请参考 RKHand 基础组件说明。

四、手势类型、掌心朝向与骨骼数据（UXR3.0 API 概览）

1）手势类型

复制代码

public enum GestureType
{
    None = -1,
    Grip = 1, // 握拳
    Palm = 2, // 手掌
    Pinch = 3, // 捏合
    OpenPinch = 4 // 捏合松开
}

获取当前手的手势类型：

复制代码

GestureType type = GesEventInput.Instance.GetGestureType(HandType.LeftHand);
// HandType: LeftHand / RightHand

2）掌心朝向

复制代码

public enum HandOrientation
{
    None = -1,
    Palm = 0, // 掌心面向使用者
    Back = 1  // 掌心远离使用者
}
HandOrientation face = GesEventInput.Instance.GetHandOrientation(HandType.RightHand);

3）骨骼点信息（26 节点）

可通过 GetSkeletonPose(SkeletonIndexFlag, HandType) 获取位姿；节点包含 WRIST、PALM、五指 MCP/PIP/DIP/TIP 与掌骨 METACARPAL_* 等。

复制代码

Pose pose = GesEventInput.Instance.GetSkeletonPose(SkeletonIndexFlag.INDEX_FINGER_TIP, HandType.LeftHand);

五、实用代码示例

1）基于骨骼向量的简易手势判断（Grip/Pinch 演示）

复制代码

private Pose GetSkeletonPose(SkeletonIndexFlag index, HandType hand)
{
    return GesEventInput.Instance.GetSkeletonPose(index, hand);
}

private GestureType JudgeGesType(HandType hand)
{
    Vector3 indexForward = (GetSkeletonPose(SkeletonIndexFlag.INDEX_FINGER_TIP, hand).position
                           - GetSkeletonPose(SkeletonIndexFlag.INDEX_FINGER_MCP, hand).position).normalized;
    Vector3 middleForward = (GetSkeletonPose(SkeletonIndexFlag.MIDDLE_FINGER_TIP, hand).position
                            - GetSkeletonPose(SkeletonIndexFlag.MIDDLE_FINGER_MCP, hand).position).normalized;
    Vector3 ringForward = (GetSkeletonPose(SkeletonIndexFlag.RING_FINGER_TIP, hand).position
                          - GetSkeletonPose(SkeletonIndexFlag.RING_FINGER_MCP, hand).position).normalized;
    Vector3 pinkyForward = (GetSkeletonPose(SkeletonIndexFlag.PINKY_TIP, hand).position
                           - GetSkeletonPose(SkeletonIndexFlag.PINKY_MCP, hand).position).normalized;
    Vector3 handForward = (GetSkeletonPose(SkeletonIndexFlag.MIDDLE_FINGER_MCP, hand).position
                          - GetSkeletonPose(SkeletonIndexFlag.WRIST, hand).position).normalized;

    float d1 = Vector3.Dot(handForward, indexForward);
    float d2 = Vector3.Dot(handForward, middleForward);
    float d3 = Vector3.Dot(handForward, ringForward);
    float d4 = Vector3.Dot(handForward, pinkyForward);

    if (d1 < 0f && d2 < 0f && d3 < 0f && d4 < 0f) return GestureType.Grip;
    if (d1 < 0.5f && d1 > 0f && d2 > 0.5f && d3 > 0.5f && d4 > 0.5f) return GestureType.Pinch;

    return GestureType.None;
}

2）近/远场交互切换（可选自定义规则）

默认提供自适应远近场切换。若仅在部分场景禁用动态切换：禁用 RKHand/LeftHandInteractors 上的 InteractorStateChange 脚本，并通过其 OnPokeInteractorHover / OnPokeInteractorUnHover 事件在需要时切换近/远场。
若只保留某种交互且不恢复动态切换：可移除上述脚本。

六、交互设计建议与回退策略（面向设备差异）

1）目标设备支持手势：使用 UXR3.0 内置手势（Pinch/Grip/Palm/OpenPinch）映射到 UI 点击、抓取/释放等操作；必要时基于骨骼数据扩展自定义手势。

2）目标设备不支持手势（如 Studio Lite / 部分 glasses）：默认采用射线指针 + 语音；在 UI 层提供"手势占位"与能力检测，能力不可用时自动隐藏相关入口，避免误导用户。

3）多模态策略：允许用户在"手势/射线/语音"之间快速切换；在手势追踪质量下降时自动回退到射线或语音。

七、常见问题（QA）

Q1：为何获取不到手势？

A：确认硬件为 Max Pro，并已正确启用 RKInput 与 Gesture 模式；检查设备权限与追踪状态。

Q2：Pinch 与 OpenPinch 区别？

A：Pinch 表示捏合成立；OpenPinch 表示捏合松开，可用于触发"释放/点击抬起"。

Q3：掌心朝向如何用在交互上？

A：常用于"掌心面向相机时才允许菜单呼出"等姿态过滤，降低误触。

Q4：骨骼坐标的世界/局部坐标？

A：以 API 返回的 Pose 为准，必要时做坐标系转换与滤波。

八、结论

本文基于 UXR3.0（v3.0.3）明确了"手势能力的设备边界"与"可落地的开发路径"。请在对外与对内文档中同步标注：手势交互依赖 Max Pro，不适用于 Studio Lite 与部分 glasses；若不满足硬件条件，应采用射线/语音等替代方案。