Unity
=====

This guide provides detailed instructions to download, set up, and run the AMFITRACK SteamVR driver in Unity 6.

This guide is written with the express purpose of being simple and only covers how to recive pose data (not buttons and analog inputs). However there are many other ways to connect to the AMFITRACK SteamVR driver in Unity. Since the AMFITRACK driver uses steamVR, any method of reading data from steamVR should work. For futher information consult the `official steamVR github <https://valvesoftware.github.io/steamvr_unity_plugin/tutorials/intro.html>`_.

Prerequisites
-------------

Before you begin, ensure the following prerequisites are met:

- **Unity**: Download and install Unity from the `official Unity site <https://unity.com/>`_.
- **AMFITRACK SteamVR driver**: Follow the installation instructions in the :doc:`AMFITRACK SteamVR documentation <SteamVR>`.

Unity Setup
-----------

Follow these steps to set up Unity, install the SteamVR plugin, and add a Tracked Pose Driver. These instructions are based on Unity 6.

Create a New Unity Project
~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Open **Unity Hub** and click **New Project**.
2. Select the **3D** template.
3. Name your project (e.g., ``SteamVR_Setup``) and click **Create**.
4. This guide has been tested with Unity 6.

Install the SteamVR Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Open the **Unity Asset Store**:
   
   - Navigate to **Window** > **Asset Store** in Unity or visit the `Unity Asset Store <https://assetstore.unity.com/>`_ online.

2. Search for **SteamVR Plugin**:
   
   - Look for "SteamVR Plugin" by Valve Corporation.

3. Download and Import:
   
   - Click **Download**, then **Import** to add the plugin to your Unity project.
   - Ensure all required assets are selected in the import dialog and click **Import**.

4. Configure the Project:
   
   - After importing, Unity may prompt you to configure **OpenVR** settings.
   - Accept the changes, such as enabling **Virtual Reality Supported** in **XR Settings**.

Configure XR Plug-in Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Open the **Project Settings**:
   
   - Go to **Edit** > **Project Settings**.

2. Enable XR Plug-in Management:
   
   - In the **Project Settings** window, navigate to the **XR Plug-in Management** section.
   - Under the **PC, Mac & Linux Standalone** tab, enable **OpenXR**.

3. Set the OpenXR Runtime to SteamVR:
   
   - Still under the **OpenXR** settings, locate **Play Mode OpenXR Runtime**.
   - Set it to **SteamVR** to ensure compatibility with the SteamVR runtime.


Add AMFITRACK Unity VR script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The AMFITRACK Steam VR driver reports poses in a right-handed y-axis up cordinate. However, unity handles poses in a left-handed y-axis up cordinate. The Following steps will add the nessary code to transform poses from the Steam VR format into Unity format.

1. Create a MonoBehaviour Script:

   - Select **Assets** > **Create** > **Scripting** > **MonoBehaviour Script**.

2. Name the MonoBehaviour Script:

   - Type in the name ``AMFITRACK_UNITY_VR_Script`` (any other name of your choice should also work, but the guide will use this name when refering to this MonoBehaviour Script).

3. Edit MonoBehaviour Script:

   - Open ``AMFITRACK_UNITY_VR_Script`` in a editor of your choice.
   - Replace the contents of ``AMFITRACK_UNITY_VR_Script`` with the code snippet below (using copy and paste).
   .. example-code::
   .. code-block:: C#

      using System;
      using System.CodeDom.Compiler;
      using System.Collections.Specialized;
      using System.Diagnostics;
      using UnityEngine;
      using Valve.VR;

      struct pose
      {
         public Vector3 position;
         public Quaternion orientation;
      };

      public class AMFITRACK_UNITY_VR_Script : MonoBehaviour
      {
         public uint DeviceIndex = 0;

         void Update()
         {
            pose controller_pose = getUnityPose(DeviceIndex);
            transform.SetPositionAndRotation(controller_pose.position, controller_pose.orientation);
         }
         pose getUnityPose(uint ID)
         {
            pose output;
            output.position = new Vector3(0, 0, 0);
            output.orientation = new Quaternion(0, 0, 0, 1);

            TrackedDevicePose_t[] poses = new TrackedDevicePose_t[OpenVR.k_unMaxTrackedDeviceCount];
            OpenVR.System.GetDeviceToAbsoluteTrackingPose(ETrackingUniverseOrigin.TrackingUniverseStanding, 0, poses);

            if (OpenVR.System != null && ID < OpenVR.k_unMaxTrackedDeviceCount && (OpenVR.System.GetTrackedDeviceClass(ID) == ETrackedDeviceClass.Controller || OpenVR.System.GetTrackedDeviceClass(ID) == ETrackedDeviceClass.GenericTracker || OpenVR.System.GetTrackedDeviceClass(ID) == ETrackedDeviceClass.HMD))
            {
                  var poseMatrix = poses[ID].mDeviceToAbsoluteTracking;
                  Vector3 position_raw = new Vector3(poseMatrix.m3, poseMatrix.m7, poseMatrix.m11);
                  output.position = new Vector3(
                     position_raw.x,
                     position_raw.y,
                     -position_raw.z
                     );
                  Quaternion orientation_raw = Quaternion_FromMatrix(poseMatrix);
                  output.orientation = new Quaternion(
                        -orientation_raw.x,
                        -orientation_raw.y,
                        orientation_raw.z,
                        orientation_raw.w);
            }
            return output;
         }
         Quaternion Quaternion_FromMatrix(HmdMatrix34_t matrix)
         {
            float w = Mathf.Sqrt(Mathf.Max(0, 1 + matrix.m0 + matrix.m5 + matrix.m10)) / 2;
            float x = Mathf.Sqrt(Mathf.Max(0, 1 + matrix.m0 - matrix.m5 - matrix.m10)) / 2;
            float y = Mathf.Sqrt(Mathf.Max(0, 1 - matrix.m0 + matrix.m5 - matrix.m10)) / 2;
            float z = Mathf.Sqrt(Mathf.Max(0, 1 - matrix.m0 - matrix.m5 + matrix.m10)) / 2;

            x = Mathf.Sign(x * (matrix.m9 - matrix.m6)) * x;
            y = Mathf.Sign(y * (matrix.m2 - matrix.m8)) * y;
            z = Mathf.Sign(z * (matrix.m4 - matrix.m1)) * z;

            return new Quaternion(x, y, z, w);
         }
      }


Set Up an Object with the Steam VR script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Create a 3D Object:
   
   - In the **Hierarchy** window, right-click and select **3D Object** > **Cube** (or any object of your choice).

2. Add the ``AMFITRACK_UNITY_VR_Script`` Component:
   
   - Select the object in the **Hierarchy**.
   - In the **Inspector**, click **Add Component**.
   - Search for and select ``AMFITRACK_UNITY_VR_Script``.

3.  Set the **Device Index**:
   
   - The **Device Index** determines which piece of HW the 3D object will follow to what piece of hardware you wish your 3D object to follow.
   - (For this guide it is **NOT** recommended using **Generic Tracker SRC** as it behaves very differently from the Controllers and Trackers.)

   ================  ================  ===================
   **Device Index**  **AMFITRACK ID**  **device-type**
   ================  ================  ===================
   0                 N/A               HMD
   16                2                 Left Controller
   17                3                 Right Controller
   18                4                 Generic Tracker 01
   19                5                 Generic Tracker 02
   20                6                 Generic Tracker 03
   21                7                 Generic Tracker 04
   22                9                 HMD Src Tracker
   ================  ================  ===================

Run the Scene
~~~~~~~~~~~~~

1. Connect your VR headset and launch SteamVR.
2. In Unity, press the **Play** button to test your scene.
3. The object with the ``AMFITRACK_UNITY_VR_Script`` should now follow the motion of your VR device.

Troubleshooting
---------------

- **SteamVR Plugin Not Found**:
   - Ensure you are logged into the Unity Asset Store and have an active internet connection.
- **Tracked Pose Driver Does Not Work**:
   - Verify the **Device** and **Pose Source** settings in the Tracked Pose Driver component.
   - Ensure SteamVR is running, and your VR headset is properly connected.

Additional Notes
----------------

- These instructions are specific to Unity 6. If you are using a different version, some steps or UI elements may differ.
- For more information, refer to the `official Unity documentation <https://docs.unity3d.com/>`_.