Inverse Unity Package 入门指南

本指南概述了基本设置，并提供一个简单示例，演示 Haply Inverse Unity Package 的基本用法，包括安装软件包、搭建 Haptic Rig，以及编写用于力控制和位置控制的简单脚本。

如需全面的细节和高级技巧，请参阅教程。

版本支持

Unity 2021.3.x LTS： 支持
Unity 2022.1.x LTS： 支持
Unity 6000.x LTS： 支持
Haply Inverse SDK：3.1.0 或更高版本

前提条件

安装 Haply Inverse SDK 3.1.0 或更高版本。
确保 Haply Inverse Service 处于正常运行状态。
在启动场景之前，请确认你的 Inverse3 和 VerseGrip 设备已连接并完成校准。

备注

该软件包正在持续开发中，以增强对 Inverse3 的支持。如需支持、反馈或提出请求，请联系我们。

安装

Inverse Unity 包可通过 Unity 的作用域注册表获取。要集成该软件包：

打开 Edit > Project Settings > Package Manager，添加一个新的作用域注册表，并填写：
- 名称：Haply Robotics
- URL：https://unitypackages.haply.co
- 作用域（Scope(s)）：co.haply
进入 Window > Package Manager，点击 add + 按钮，然后选择 Add package by name。输入 co.haply.inverse，然后点击 Add。

安装成功后，包管理器将显示 Inverse 包。

设置 Haptic Rig

要创建 Haptic Rig，请导航至 GameObject > Haply Inverse > Haptic Rig (one hand)。此操作将组装一个完整环境，包含 Inverse3 控制器和 VerseGrip。

场景中现在将包含：

Haptic Device Mapper：使用 Haply Inverse Service 管理设备分配。
Haptic Origin：在场景中缩放并定位触觉设置。
Haptic Controller：根据 Inverse3 和 VerseGrip 设备数据管理光标的力或位置。
Cursor：包含用于场景呈现的 Inverse3 Cursor 和 VerseGrip Cursor 组件。

单手 Haptic Rig

有关包组件的更多详情，请参阅全局架构文档页面。

在 Play 模式下，球体将与 Inverse3 光标同步移动和旋转，并跟随 VerseGrip 的姿态。

Inverse3 检视面板

手柄检视面板

力控制模式

创建一个 ForceControl.cs C# 脚本，并将其挂载到 Haptic Origin GameObject 上。该脚本允许你通过检视面板中的滑块，向 Inverse3 设备施加力。

using Haply.Inverse;
using UnityEngine;

public class ForceControl : MonoBehaviour
{
    [Range(-2, 2)]
    public float forceX;
    [Range(-2, 2)]
    public float forceY;
    [Range(-2, 2)]
    public float forceZ;

    private Inverse3 _inverse3;

    private void Awake()
    {
        _inverse3 = GetComponentInChildren<Inverse3>();
    }

    protected void OnEnable()
    {
        _inverse3.DeviceStateChanged += OnDeviceStateChanged;
    }

    protected void OnDisable()
    {
        _inverse3.DeviceStateChanged -= OnDeviceStateChanged;
        _inverse3.Release();
    }

    private void OnDeviceStateChanged(object sender, Inverse3EventArgs args)
    {
        var inverse3 = args.DeviceController;
        inverse3.SetCursorLocalForce(new Vector3(forceX, forceY, forceZ));
    }
}

力控制

脚本说明

forceX, Y, Z：通过滑块调节的力矢量分量，在传递给 CursorSetForce 方法之前，确保力保持在安全范围内。也可以改用标准的 Vector3 字段。
Awake()：从当前 GameObject 或其子对象中获取 Inverse3 组件。
OnEnable()：在 Awake 方法调用之后，以及每次脚本启用时，在独立线程中注册触觉更新中的 OnDeviceStateChanged 回调。
OnDisable()：当脚本被禁用或应用程序停止时，注销回调并重置力。
OnDeviceStateChanged：从检视面板中获取 force 矢量，并通过 CursorSetForce 方法将其转发给 Inverse3。

重要：该回调由触觉线程以高频率触发，频率范围为 1kHz 至 8kHz。务必确保该回调中的所有代码都经过高度优化。

使用方法

进入 Play 模式之前，请确保你正握持着光标。设备应切换到 Force Control 状态，并亮起绿灯。随后，你可以通过滑块调节力输出，在设备工作空间中进行操作。

注意

调节力会使 Inverse3 发生移动。请确保工作空间内没有障碍物，并始终握持光标。有关安全准则，请参阅安全使用文章。

光标设置力

位置控制模式

同样地，请创建一个用于控制设备位置的 PositionControl.cs C# 脚本，并将其挂载到 Haptic Origin GameObject 上。

using Haply.Inverse;
using UnityEngine;

public class PositionControl : MonoBehaviour
{
   [Range(-0.1f, 0.1f)]
   public float positionX;
   [Range(-0.1f, 0.1f)]
   public float positionY;
   [Range(-0.1f, 0.1f)]
   public float positionZ;

   private Inverse3 _inverse3;

   private void Awake()
   {
     _inverse3 = GetComponentInChildren<Inverse3>();
   }

   protected void OnEnable()
   {
     _inverse3.DeviceStateChanged += OnDeviceStateChanged;
   }

   protected void OnDisable()
   {
     _inverse3.DeviceStateChanged -= OnDeviceStateChanged;
     _inverse3.Release();
   }

   private void OnDeviceStateChanged(object sender, Inverse3EventArgs args)
   {
     var inverse3 = args.DeviceController;
     inverse3.SetCursorLocalPosition(inverse3.WorkspaceCenterLocalPosition + new Vector3(positionX, positionY, positionZ));
   }
}

请确保禁用 ForceControl 脚本或控制设备的任何其他脚本。

position-control

与前面的示例类似：

在运行模式下，使用 positionX, Y, and Z 并通过滑块调整位置。

所选的 Range(-0.1, 0.1) 大致对应于可达到的最大位置。
Awake 方法获取 Inverse3 组件。
OnEnable 方法在 Awake 方法调用之后以及每次启用脚本时，在单独的线程中从触觉更新中注册 OnDeviceStateChanged 回调。
OnDisable 方法在脚本被禁用或应用程序停止时注销回调并重置力。

但两者存在以下差异：

OnDeviceStateChanged 回调在每个触觉帧期间，从检视面板中获取位置向量，将其与 WorkspaceCenterLocalPosition 相加，并通过 CursorSetLocalPosition 方法将其发送到 Inverse3。

进入运行模式之前，请握持光标使其靠近中心位置。设备应切换至 位置控制 状态（指示灯呈蓝色）。然后，您可以使用滑块调整位置输出，探索设备的工作空间。

注意

调整位置时，Inverse3 将会移动。请确保工作空间内没有任何贵重物品，并始终握持光标。更多详细信息，请参阅安全使用文章。

cursor-set-position

版本支持​

前提条件​

安装​

设置 Haptic Rig​

力控制模式​

脚本说明​

使用方法​

位置控制模式​