使用 Leap Motion 和 Ultraleap - MRTK2

  • 项目

需要 Leap Motion 控制器才能使用此数据提供程序。

Leap Motion 数据提供程序支持 VR 的清晰手部跟踪，并且可用于编辑器中的快速原型制作。 可以将数据提供程序配置为使用安装在头戴显示设备上或面朝上放在桌面上的 Leap Motion 控制器。

LeapMotionIntroGif

在独立平台上，此提供程序可在编辑器和设备上使用。 它还可以在 UWP 平台上的编辑器中使用，但不能在 UWP 内部版本中使用。

MRTK 版本 支持 Leap Motion Unity 模块版本
2.6.x 4.5.0, 4.5.1
2.7.0 - 2.7.2 4.5.0, 4.5.1, 4.6.0, 4.7.0, 4.7.1, 4.8.0
2.7.3 4.5.0, 4.5.1, 4.6.0, 4.7.0, 4.7.1, 4.8.0, 4.9.1（参阅以下说明）

注意

Unity 模块 4.9.1 需要 Gemini 5.2 跟踪服务或更高版本。 Unity 插件 V4.9.1 仅在 Unity 2019 上受到官方支持。 请参阅 4.9.1 发行说明

Unity 模块在 V5.0.0 中被重命名为 Unity 插件。

MRTK 版本 支持的 Ultraleap Unity 插件版本
2.8.0 5.3.0（参阅以下说明）

注意

任何版本的 MRTK 都不支持 Unity 插件版本 5.0.0、5.1.0 和 5.2.0。 建议用户升级到 5.3.0。 Unity 插件 5.3.0 需要 Gemini 5.2 跟踪服务或更高版本。

在 MRTK 中使用 Leap Motion（通过 Ultraleap）手部跟踪

  1. 导入 MRTK 和 Leap Motion Unity 模块/Unity 插件

    • 安装最新的 Leap 运动跟踪软件 以获取跟踪服务（如果尚未安装）
    • 将 Microsoft.MixedReality.Toolkit.Foundation 包导入 Unity 项目。
    • 下载最新版本的 Leap Motion Unity 模块/Unity 插件并将其导入到项目中
      • 对于 Unity 模块：仅导入项目中的核心包
      • 对于 Unity 插件：仅导入项目中的跟踪包。 目前仅支持 .unitypackage。

    重要

    Unity 2019.4.19 后 Unity 弃用的 OnlyUserModifiable SelectionMode，这会导致 Ultraleap Hotkeys.cs 脚本中出现以下错误：Assets\Plugins\LeapMotion\Core\Editor\Hotkeys.cs(24,91)：错误 CS0619：“SelectionMode.OnlyUserModifiable”已过时：“OnlyUserModifiable”已过时。 请改用“可编辑”。 (UnityUpgradeable) ->“可编辑”。

    若要解决这些问题，请将位于 Plugins/LeapMotion/Core/Editor/Hotkeys.cs 中的 Hotkeys.cs 脚本中的 SelectionMode.OnlyUserModifiable 更改为 SelectionMode.Editable。

  2. 将 Leap Motion Unity 模块/Unity 插件与 MRTK 集成

    • Unity 模块/Unity 插件在项目中后，导航到“混合现实”>“工具包”>“实用工具”>“Leap Motion”>“集成 Leap Motion Unity 模块”。

    注意

    将 Unity 模块集成到 MRTK 会将 10 个程序集定义添加到项目，并添加对 Microsoft.MixedReality.Toolkit.Providers.LeapMotion 程序集定义的引用。 确保已关闭 Visual Studio。

    LeapMotionIntegration

  3. 添加 Leap Motion 数据提供程序

    • 新建 Unity 场景
    • 导航到“混合现实工具包”>“添加到场景并配置”，将 MRTK 添加到场景中
    • 在层次结构中选择 MixedRealityToolkit 游戏对象，然后选择“复制和自定义”以克隆默认的混合现实配置文件。

    LeapMotionProfileClone

    • 选择“输入”配置配置文件

    Input Configuration Profile 1

    • 在输入系统配置文件中选择“克隆”以启用修改。

    LeapMotionInputProfileClone

    • 打开“输入数据提供程序”部分，选择顶部的“添加数据提供程序”，新的数据提供程序将添加到列表末尾。 打开新的数据提供程序，将“类型”设置为“Microsoft.MixedReality.Toolkit.XRSDK.Oculus”“OculusXRSDKDeviceManager”>

    Leap Add Data Provider

    • 选择克隆以更改默认的 Leap Motion 设置。

    LeapDataProviderPreClone

    • Leap Motion 数据提供程序包含 LeapControllerOrientation 属性，该属性是 Leap Motion 控制器的位置。 LeapControllerOrientation.Headset 指示控制器已装载在头戴显示设备上。 LeapControllerOrientation.Desk 指示控制器平放在桌面上。 默认值设置为 LeapControllerOrientation.Headset。

    • 每个控制器方向都包含偏移属性：

      • 头戴显示设备方向偏移属性反映了在 LeapXRServiceProvider 组件中的偏移属性。 LeapVRDeviceOffsetMode 有三个选项：默认、手动头部偏移和转换。 如果偏移模式为默认，则偏移量将不会应用于 Leap Motion 控制器。 手动头部偏移模式允许修改三个属性：LeapVRDeviceOffsetY、LeapVRDeviceOffsetZ 和 LeapVRDeviceTiltX。 然后，轴偏移属性值将应用于默认控制器位置。 转换偏移模式包含 LeapVRDeviceOrigin 转换属性，该属性指定了 Leap Motion 控制器的新原点。

      • 桌面方向包含定义桌面 leap 定位位置的 LeapControllerOffset 属性。 偏移量是相对于摄像头的主位置计算的，默认值为 (0,-0.2, 0.35)，以确保手显示在摄像头的正面和下方。

        注意

        应用程序启动时，将应用配置文件中的偏移属性一次。 若要在运行时修改值，请从 Leap Motion 设备管理器获取 Leap Motion 服务提供程序：

        LeapMotionDeviceManager leapMotionDeviceManager = CoreServices.GetInputSystemDataProvider<LeapMotionDeviceManager>();
LeapXRServiceProvider leapXRServiceProvider = leapMotionDeviceManager.LeapMotionServiceProvider as LeapXRServiceProvider;

    • EnterPinchDistance 和 ExitPinchDistance 是用于收缩/敲击手势检测的距离阈值。 收缩手势是通过测量食指指尖和拇指指尖之间的距离计算的。 若要引发 on input down 事件，则默认值 EnterPinchDistance 设置为 0.02。 若要引发 on input up 事件（退出收缩），食指指尖和拇指指尖之间的默认距离为 0.05。

    LeapControllerOrientation：头戴显示设备（默认值）

    LeapHeadsetGif

    LeapHeadsetInspector

    LeapControllerOrientation：桌面

    LeapDeskGif

    LeapDeskInspector

  4. 测试 Leap Motion 数据提供程序

    • 将 Leap Motion 数据提供程序添加到输入系统配置文件后，按“播放”，将手移到 Leap Motion 控制器的前面，应会看到手的关节呈现。

  5. 生成项目

    • 导航到“文件”>“生成设置”
    • 如果使用 Leap Motion 数据提供程序，则仅支持独立内部版本。
    • 有关如何使用独立内部版本 Windows Mixed Reality 头戴显示设备的说明，请参阅生成 MRTK 并部署到独立 WMR 头戴显示设备。

获取手关节

使用 Leap Motion 数据提供程序获取关节与 MRTK Articulated Hand 手关节检索相同。 有关详细信息，请参阅手部跟踪。

使用 Unity 场景中的 MRTK 以及作为输入数据提供程序添加到输入系统配置文件中的 Leap Motion 数据提供程序，创建一个空游戏对象并附加以下示例脚本。

此脚本是一个简单的示例，演示了如何在 Leap Motion Hand 中检索手掌关节的姿势。 球体跟随左 Leap 手，而立方体跟随右 Leap 手。

using Microsoft.MixedReality.Toolkit;
using Microsoft.MixedReality.Toolkit.Input;
using Microsoft.MixedReality.Toolkit.Utilities;
using System.Collections.Generic;
using UnityEngine;

public class LeapHandJoints : MonoBehaviour, IMixedRealityHandJointHandler
{
    private GameObject leftHandSphere;
    private GameObject rightHandCube;

    private void Start()
    {
        // Register the HandJointHandler as a global listener
        CoreServices.InputSystem.RegisterHandler<IMixedRealityHandJointHandler>(this);

        // Create a sphere to follow the left hand palm position
        leftHandSphere = GameObject.CreatePrimitive(PrimitiveType.Sphere);
        leftHandSphere.transform.localScale = Vector3.one * 0.03f;

        // Create a cube to follow the right hand palm position
        rightHandCube = GameObject.CreatePrimitive(PrimitiveType.Cube);
        rightHandCube.transform.localScale = Vector3.one * 0.03f;
    }

    public void OnHandJointsUpdated(InputEventData<IDictionary<TrackedHandJoint, MixedRealityPose>> eventData)
    {
        if (eventData.Handedness == Handedness.Left)
        {
            Vector3 leftHandPalmPosition = eventData.InputData[TrackedHandJoint.Palm].Position;
            leftHandSphere.transform.position = leftHandPalmPosition;
        }

        if (eventData.Handedness == Handedness.Right)
        {
            Vector3 rightHandPalmPosition = eventData.InputData[TrackedHandJoint.Palm].Position;
            rightHandCube.transform.position = rightHandPalmPosition;
        }
    }
}

Unity 编辑器工作流提示

使用 Leap Motion 数据提供程序不需要 VR 头戴显示设备。 可以使用 Leap 手 在编辑器中测试对 MRTK 应用的更改，而无需头戴显示设备。

Leap Motion Hands 会显示在编辑器中，无需插入 VR 头戴显示设备。 如果 LeapControllerOrientation 设置为“头戴显示设备”，则需要用一只手将 Leap Motion 控制器举起，摄像头朝向前方。

注意

如果使用编辑器中的 WASD 键来移动摄像头并且 LeapControllerOrientation 为“头戴显示设备”，则手不会跟随摄像头。 只有在 LeapControllerOrientation 设置为“头戴显示设备”时插入了 VR 头戴显示设备，手才会跟随摄像头移动。 如果 LeapControllerOrientation 设置为“桌面”，则在编辑器中，Leap 手会跟随摄像机移动。

从项目中删除 Leap Motion

  1. 导航到“混合现实工具包”>“Leap Motion”>“独立 Leap Motion Unity 模块”
    • 在此步骤中修改 Microsoft.MixedReality.Toolkit.Providers.Oculus.asmdef 文件中的引用后，让 Unity 刷新
  2. 关闭 Unity
  3. 关闭 Visual Studio（如果已打开）
  4. 打开文件资源管理器并导航到 MRTK Unity 项目的根目录
    • 删除 UnityProjectName/Library 目录
    • 删除 UnityProjectName/Assets/Plugins/LeapMotion 目录
    • 删除 UnityProjectName/Assets/Plugins/LeapMotion 文件
  5. 重新打开 Unity

在 Unity 2018.4 中，你可能会注意到，删除库和 Leap Motion Core 资产后，控制台中仍然存在错误。 如果在重新打开后记录了错误，请再次重启 Unity。

常见错误

Leap Motion 未与 MRTK 集成

测试 Leap Motion Unity 模块是否与 MRTK 集成：

  • 导航到“混合现实工具包”>“实用程序”>“Leap Motion”>“查看集成状态”
    • 此时会显示一个弹出窗口，其中包含有关 Leap Motion Unity 模块是否已与 MRTK 集成的消息。
  • 如果消息显示资产尚未集成：
    • 确保 Leap Motion Unity 模块在项目中
    • 确保支持所添加的版本，请参阅页面顶部的表格了解支持的版本。
    • 试用“混合现实工具包”>“实用程序”>“Leap Motion”>“集成 Leap Motion Unity 模块”

复制程序集多人游戏 HLAPI 失败

导入 Leap Motion Unity Core 资产时，可能会记录此错误：

Copying assembly from 'Temp/com.unity.multiplayer-hlapi.Runtime.dll' to 'Library/ScriptAssemblies/com.unity.multiplayer-hlapi.Runtime.dll' failed

解决方案

  • 短期解决方案是重启 Unity。 有关详细信息，请参阅问题 7761。

Leap Motion 示例场景

示例场景使用 DefaultLeapMotionConfiguration 配置文件，并确定 Unity 项目是否正确配置为使用 Leap Motion 数据提供程序。

示例场景包含在“MRTK/example/Demos/HandTracking/” 目录中的 “MixedReality”包中。

另请参阅