使用 Leap Motion 和 Ultraleap — MRTK2

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

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

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 仅在 2019 Unity正式受支持。请参阅 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 (by Ultraleap) 手部跟踪

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

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

若要解决这些问题，请将位于 Plugins/LeapMotion/Core/编辑器/Hotkeys.cs 中的Hotkeys.cs脚本中的 SelectionMode.OnlyUserModifiable 更改为 SelectionMode.Editable。
将 Leap Motion Unity模块/Unity插件与 MRTK 集成
- 在项目中Unity模块/Unity插件后，导航到混合现实>Toolkit>实用工具>Leap Motion>集成 Leap Motion Unity 模块。
注意

将 Unity 模块集成到 MRTK 后，将向项目添加 10 个程序集定义，并添加对 Microsoft.MixedReality.Toolkit.Providers.LeapMotion 程序集定义的引用。确保 Visual Studio 已关闭。
添加 Leap Motion 数据提供程序
- 创建新的Unity场景
- 导航到“混合现实工具包>”“添加到场景”和“配置”，将 MRTK 添加到场景
- 在层次结构中选择 MixedRealityToolkit 游戏对象，然后选择 “复制和自定义 ”以克隆默认混合现实配置文件。
- 选择输入配置文件
- 在输入系统配置文件中选择“ 克隆 ”以启用修改。
- 打开 “输入数据提供程序” 部分。选择顶部的“ 添加数据提供程序 ”，会在列表末尾添加新的数据提供程序。打开新的数据提供程序，并将 Type 设置为 Microsoft.MixedReality.Toolkit.LeapMotion.Input > LeapMotionDeviceManager
- 选择“ 克隆 ”以更改默认的 Leap Motion 设置。
- Leap Motion 数据提供程序包含 LeapControllerOrientation 属性，该属性是 Leap Motion 控制器的位置。 LeapControllerOrientation.Headset 指示控制器已安装在头戴显示设备上。 LeapControllerOrientation.Desk 指示控制器平放在办公桌上。默认值设置为 LeapControllerOrientation.Headset。
- 每个控制器方向都包含偏移属性：
  - 头戴显示设备方向偏移属性镜像 LeapXRServiceProvider 组件中的偏移属性。有 LeapVRDeviceOffsetMode 三个选项：默认、手动头部偏移和转换。如果偏移模式为“默认”，则偏移量不会应用于 Leap Motion 控制器。手动头部偏移模式允许修改三个属性： LeapVRDeviceOffsetY、 LeapVRDeviceOffsetZ 和 LeapVRDeviceTiltX。然后，轴偏移属性值将应用于默认控制器放置。转换偏移模式包含 LeapVRDeviceOrigin Transform 属性，该属性指定 Leap Motion 控制器的新原点。
  - “桌面方向”包含LeapControllerOffset属性，该属性定义桌面跳动手的定位点位置。偏移量相对于主相机位置进行计算，默认值为 (0，-0.2,0.35) ，以确保手出现在相机的前面和视线中。
    注意
    
    应用程序启动时，配置文件中的偏移量属性将应用一次。若要在运行时修改值，请从 Leap Motion 设备管理器获取 Leap Motion 服务提供程序：
```
LeapMotionDeviceManager leapMotionDeviceManager = CoreServices.GetInputSystemDataProvider<LeapMotionDeviceManager>();
LeapXRServiceProvider leapXRServiceProvider = leapMotionDeviceManager.LeapMotionServiceProvider as LeapXRServiceProvider; 
```
- EnterPinchDistance 和 ExitPinchDistance 是收缩/空中点击手势检测的距离阈值。捏合手势是通过测量食指尖和拇指尖之间的距离来计算的。若要引发输入关闭事件，默认值 EnterPinchDistance 设置为 0.02。若要在退出收缩) (引发输入 up 事件，食指尖与拇指尖之间的默认距离为 0.05。
LeapControllerOrientation：耳机 (默认)

LeapControllerOrientation：书桌
测试 Leap Motion 数据提供程序
- 将 Leap Motion 数据提供程序添加到输入系统配置文件后，按 play，将手移到 Leap 运动控制器前，应会看到该手的关节表示形式。
生成项目
- 导航到 “文件 > 生成设置”
- 如果使用 Leap Motion 数据提供程序，则仅支持独立版本。
- 有关如何将Windows Mixed Reality头戴显示设备用于独立版本的说明，请参阅生成 MRTK 并将其部署到 WMR 头戴显示设备 (独立) 。

获取手关节

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

将 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 头戴显示设备。可以在编辑器中测试对 MRTK 应用的更改，无需头戴显示设备即可使用 Leap 手。

Leap Motion Hands 显示在编辑器中，没有插入 VR 头戴显示设备。 LeapControllerOrientation如果设置为“头戴显示设备”，则需要用一只手按住 Leap Motion 控制器，相机朝前。

注意

如果使用编辑器中的 WASD 键移动相机， LeapControllerOrientation 并且是 头戴显示设备，则手不会跟随相机。如果在设置头戴显示设备时插入 VR 头戴显示设备，LeapControllerOrientation则手会跟随相机移动。如果 LeapControllerOrientation 设置为 Desk，则 Leap 手将跟随编辑器中的相机移动。

从项目中删除 Leap Motion

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

在 Unity 2018.4 中，你可能会注意到，删除库和 Leap Motion 核心资产后，控制台中仍然存在错误。如果重新打开后记录错误，请再次重启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核心资产时，可能会记录此错误：

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/Examples/Demos/HandTracking/ 目录中的 Microsoft.MixedReality.Toolkit.Examples 包中。

另请参阅

Last updated on 2025-11-06

通过