Tracker system

The Tracker system allows for measurement of parameters in real-time (frame-by-frame) within a trial, and subsequently storing those measurements in a table (CSV file if using File Saver Data Handler, list of arrays in Web AWS DynamoDB Data Handler).

Included Tracking Scripts

UXF includes the following tracking scripts in the UXF/Scripts/Trackers folder. Any tracker used needs to be added to the Tracked Object field in the Session inspector (Data Collection tab).

• PositionRotationTracker: Attach this to a game object to measure its position and rotation. This could be a GameObject that is tied to the user's physical input such as a VR controller or a mouse cursor.
• MouseWorldTracker: Attach this to an empty GameObject in the scene to track the mouse's position in world-coordinates. The main camera in the scene needs assigning to this script. For cameras in perspective mode, the user needs to define the distance into the screen the measurements should be taken from (i.e. the depth from the camera to the plane of interest). For cameras in orthographic perspective mode, this distance can be any value.
• MouseScreenTracker: Attach this to an empty GameObject in the scene to track the mouse's position in screen-coordinates. Note that the position (0, 0)px is at the bottom left of the game window.

Custom Tracking Scripts

For tracking of other parameters - you can create a custom class that inherits from the UXF.Tracker, where you need to implement collection of the parameters you want to measure. For example, you could use this to track what the participant is looking at if using eye tracking hardware. The included tracking scripts give good examples for how to do this, but tracking need not be restricted to positions. For example, the following custom tracker can be added to an object will record the colour of an assigned material:

using UnityEngine;
using UXF;

public class ColorTracker : Tracker
{
    private Renderer rend;

    protected override void SetupDescriptorAndHeader()
    {
        measurementDescriptor = "color";
        
        customHeader = new string[]
        {
            "color"
        };
    }

    protected override UXFDataRow GetCurrentValues()
    {
        var values = new UXFDataRow()
        {
            ("color", rend.material.color)
        };

        return values;
    }
}

Tracking Timing

Measurement of parameters by tracker components can be performed in Unity's LateUpdate() call (default behaviour), in Unity's FixedUpdate() call, or in a manual call that the user can define either by calling the RecordRow method from another script, or by extending the UXF.Tracker class and defining how the RecordRow method is called. UXF automatically adds a time column to the output, which is just a log of Unity's Time.time.

As an example of a manual call, consider the following code where a script calls for data to be recorded (roughly) every 200ms. By referencing a gameObject's UXF.PositionRotationTracker needs assigning in the editor, and the TrialBegin and TrialEnd methods need adding to the [UXF_Rig] events called on trial start and end. With this done, measurements will be taken every time the coroutine has waited for 200ms.

using System.Collections;
using UnityEngine;
using UXF;

public class RegularRecorder : MonoBehaviour
{
    public PositionRotationTracker positionRotationTracker;

    public void TrialBegin()
    {
        StartCoroutine(ManualRecord());
    }

    public void TrialEnd()
    {
        StopAllCoroutines();
    }

    private IEnumerator ManualRecord()
    {
        while (true)
        {
            if (positionRotationTracker.Recording) positionRotationTracker.RecordRow();

            yield return new WaitForSeconds(0.2f);
        }
    }
}