Inverse Unity Package 入门指南

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

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

版本支持

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 反向服务处于正常运行状态。
在启动场景之前，请确认您的Inverse3 和VerseGrip设备已连接并完成校准。

备注

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

安装

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

打开“编辑”>“项目设置”>“包管理器”，添加一个新的作用域注册表，并填写：
- 名称：Haply Robotics
- 网址：https://unitypackages.haply.co
- 作用域（Scope(s)）：co.haply
进入 窗口 > 软件包管理器，点击加上按钮，然后选择 按名称添加软件包。输入 co.haply.inverse，然后点击添加。

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

设置 Haptic Rig

要创建 Haptic Rig，请依次选择“GameObject” > “Haply Inverse” > “Haptic Rig（单手）”。此操作将组装一个完整的环境，其中包含Inverse3 控制器和VerseGrip。

该场景现在将包含：

Haptic Device Mapper：使用Haply 反向服务来管理设备分配。
触觉原点：在场景中缩放并定位触觉设置。
触觉控制器：根据 Inverse3 和VerseGrip设备的数据来管理光标的力或位置。
光标：包含用于场景渲染的Inverse3 光标和VerseGrip光标组件。

单手触觉测试装置

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

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

Inverse3 查看面板

手柄查看面板

力控制模式

创建一个 ForceControl.cs C# 脚本，并将其挂载到 触觉起源 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# 脚本，并将其挂载到 触觉起源 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脚本或控制设备的任何其他脚本。

位置控制

与前面的示例类似：

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

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

但两者存在以下差异：

OnDeviceStateChanged 在每个触觉帧期间，从视图面板中获取位置向量，并将它与 WorkspaceCenterLocalPosition 相加，并通过 CursorSetLocalPosition 请将其发送至Inverse3。

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

注意

调整位置时，Inverse3 会随之移动。请确保工作区域内没有贵重物品，并始终握住光标。更多详细信息，请参阅《安全使用指南》。

光标设置位置

版本支持​

先决条件​

安装​

设置 Haptic Rig​

力控制模式​

脚本说明​

使用方法​

位置控制模式​