Erste Schritte mit dem Inverse Unity Package

Dieser Leitfaden beschreibt die grundlegende Einrichtung und zeigt an einem einfachen Beispiel die Grundfunktionen des Haply Inverse Unity Package: die Installation des Pakets, die Einrichtung eines Haptic Rig sowie das Erstellen einfacher Skripte für Kraft- und Positionssteuerung.

Ausführliche Details und fortgeschrittene Techniken finden Sie in den Tutorials.

Versionsunterstützung

• Unity 2021.3.x LTS: unterstützt
• Unity 2022.1.x LTS: unterstützt
• Unity 6000.x LTS: unterstützt
• Haply Inverse SDK: 3.1.0 oder neuer

Voraussetzungen

• Installieren Sie das Haply Inverse SDK in Version 3.1.0 oder neuer.
• Stellen Sie sicher, dass Haply Inverse Service betriebsbereit ist.
• Vergewissern Sie sich, dass Ihre Inverse3- und VerseGrip-Geräte verbunden und kalibriert sind, bevor Sie die Szene starten.

hinweis

Das Paket wird laufend weiterentwickelt, um die Unterstützung für Inverse3 zu verbessern. Für Support, Feedback oder Anfragen kontaktieren Sie uns.

Installation

Das Inverse Unity-Paket ist über die Scoped Registry von Unity verfügbar. Gehen Sie zur Integration des Pakets wie folgt vor:

1. Öffnen Sie Edit > Project Settings > Package Manager. Fügen Sie eine neue Scoped Registry mit folgenden Angaben hinzu:

   • Name: Haply Robotics
   • URL: https://unitypackages.haply.co
   • Scope(s): co.haply

   

2. Rufen Sie Window > Package Manager auf, klicken Sie auf die Schaltfläche add + und wählen Sie Add package by name. Geben Sie co.haply.inverse ein und klicken Sie auf Add.

   

Nach erfolgreicher Installation zeigt der Package Manager das Inverse-Paket an.

Einrichten des Haptic Rig

Um ein Haptic Rig zu erstellen, navigieren Sie zu GameObject > Haply Inverse > Haptic Rig (one hand). Dabei wird eine vollständige Umgebung mit dem Inverse3-Controller und dem VerseGrip zusammengestellt.

Ihre Szene enthält anschließend:

• Haptic Device Mapper: Verwaltet die Gerätezuordnung über Haply Inverse Service.
• Haptic Origin: Skaliert und positioniert das Haptik-Setup innerhalb der Szene.
• Haptic Controller: Verwaltet Cursorkraft bzw. Cursorposition auf Basis der Gerätedaten von Inverse3 und VerseGrip.
• Cursor: Enthält die Komponenten Inverse3 Cursor und VerseGrip Cursor für die Darstellung in der Szene.

Weitere Details zu den Komponenten des Pakets finden Sie auf der Seite Globale Architektur.

Im Play-Modus bewegt und dreht sich die Kugel synchron mit dem Cursor des Inverse3 und der Orientierung des VerseGrip.

Force-Control-Modus

Erstellen Sie ein C#-Skript ForceControl.cs und hängen Sie es an das GameObject Haptic Origin an. Dieses Skript ermöglicht es Ihnen, über Schieberegler im Inspector Kräfte auf das Gerät Inverse3 anzuwenden.

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));
    }
}

Erläuterung des Skripts

• forceX, Y, Z: Über Schieberegler anpassbare Komponenten des Kraftvektors; sie stellen sicher, dass die Kräfte vor der Übergabe an die Methode CursorSetForce innerhalb sicherer Grenzen bleiben. Alternativ könnte ein Standardfeld Vector3 verwendet werden.

• Awake(): Ruft die Komponente Inverse3 vom aktuellen GameObject oder einem seiner untergeordneten Objekte ab.

• OnEnable(): Registriert den Callback OnDeviceStateChanged für das haptische Update in einem separaten Thread, nachdem die Methode Awake aufgerufen wurde, und jedes Mal, wenn das Skript aktiviert wird.

• OnDisable(): Hebt die Registrierung des Callbacks auf und setzt die Kraft zurück, wenn das Skript deaktiviert oder die Anwendung beendet wird.

• OnDeviceStateChanged: Ruft den Vektor force aus dem Inspector-Fenster ab und leitet ihn mithilfe der Methode CursorSetForce an das Inverse3 weiter.

  WICHTIG: Der Callback wird vom Haptik-Thread mit hoher Frequenz ausgelöst, im Bereich von 1kHz bis 8kHz. Es ist entscheidend, dass der gesamte Code in diesem Callback stark optimiert ist.

Verwendung

Stellen Sie vor dem Wechsel in den Play-Modus sicher, dass Sie den Cursor halten. Das Gerät sollte in den Zustand Force Control wechseln, erkennbar an einer grünen Leuchte. Anschließend können Sie den Arbeitsbereich des Geräts durchfahren, indem Sie die Kraftausgabe über die Schieberegler anpassen.

warnung

Das Anpassen der Kräfte führt dazu, dass Inverse3 sich bewegt. Stellen Sie sicher, dass Ihr Arbeitsbereich frei ist, und halten Sie den Cursor jederzeit fest. Sicherheitshinweise finden Sie im Artikel zur sicheren Verwendung.

Position-Control-Modus

Erstellen Sie ebenso ein C#-Skript PositionControl.cs zur Steuerung der Position des Geräts und hängen Sie es an das GameObject Haptic Origin an.

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));
   }
}

Stellen Sie sicher, dass das ForceControl-Skript oder andere Skripte, die das Gerät steuern, deaktiviert sind.

Ähnlich wie im vorherigen Beispiel:

• Verwenden Sie positionX, Y, and Z, um die Position während des Play-Modus über Schieberegler anzupassen.

  Der ausgewählte Bereich Range(-0.1, 0.1) entspricht ungefähr der maximal erreichbaren Position.

• Die Methode Awake ruft die Komponente Inverse3 ab.
• Die Methode OnEnable registriert den Callback OnDeviceStateChanged aus dem haptischen Update in einem separaten Thread nach dem Aufruf der Methode Awake und jedes Mal, wenn das Skript aktiviert wird.
• Die Methode OnDisable hebt die Registrierung des Callbacks auf und setzt die Kraft zurück, wenn das Skript deaktiviert wird oder die Anwendung beendet wird.

Es gibt jedoch Unterschiede:

• Der Callback OnDeviceStateChanged nimmt während jedes haptischen Frames den Positionsvektor aus dem Inspector-Fenster, addiert ihn zu WorkspaceCenterLocalPosition und sendet ihn mithilfe der Methode CursorSetLocalPosition an Inverse3.

Halten Sie den Cursor vor dem Wechsel in den Play-Modus nahe an der Mittelposition. Das Gerät sollte in den Zustand Positionssteuerung wechseln (angezeigt durch ein blaues Licht). Anschließend können Sie den Arbeitsbereich des Geräts erkunden, indem Sie die Positionsausgabe mit den Schiebereglern anpassen.

warnung

Beim Anpassen der Position bewegt sich Inverse3. Stellen Sie sicher, dass der Arbeitsbereich frei von Wertgegenständen ist, und halten Sie den Cursor jederzeit fest. Weitere Details finden Sie im Artikel zur sicheren Verwendung.