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, the player's head, or an object such as a virtual ball.
• 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 projection 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 projection 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.

You can have as many Trackers as you want, UXF will log the data for all of them. It will also reference the data output location in the trial_result output.

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 create your own custom tracker 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;

    public override string MeasurementDescriptor => "color";

    public override IEnumerable<string> CustomHeader => new string[] { "color" };

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

        return values;
    }
}

I made a script for eye tracking with Vive Pro Eye here, feel free to add to your project.

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