Tobii Ocumen Filters - Getting Started

The Tobii Ocumen Filters are currently in alpha and prone to change.

The eye movement classifiers and filters are available through the Tobii Ocumen Sample Project, a Unity project you will get access to when signing up for a Tobii Ocumen license.

This page will give you an overview of how to use the pipeline supporting the eye movement classifiers and filters. You will get access to the full documentation when you sign up for Tobii Ocumen.

Table of Contents


Overview of Pipeline Stages

  • Frame Processors: used on HMD tracking data to ensure timestamps are correctly ordered, regularly-intervaled, and time-shifted, if needed.
  • Eye Tracking Processors: used on eye tracking data to remove outliers, remove blinks, ensure that timestamps are correctly ordered, regularly-intervaled, and time-shifted, if needed.
  • Fusion Stage: gives you options for how to temporally fuse frame data and eye tracking data which often have different refresh rates.
  • Fused Processors: another chance to ensure that fused data timestamps are correctly sorted and regularly-intervaled.
  • Filters: algorithms used to detect eye tracking events such as saccades, fixations, smooth pursuits, vestibulo-ocular reflexes, etc.

Step 1: Get Access

To get access, you need a Tobii Ocumen license.

When you sign up for a license, you will be able to download the Tobii Ocumen Sample Project in Unity which contains the eye movement classifiers and filters.


Step 2: Initialize the Pipeline

The pipeline requires a JSON5 pipeline definition file.

In order to generate one, open a command prompt in the folder containing the ocumen_cli.exe file and run:

ocumen_cli pipeline init

This will create a default pipeline.json5 file which is used to configure your pipeline. You can have several JSON5 pipeline definition files.

For more information about commands, you can always run:

ocumen_cli help

You can add help at the end of any command for more information.


Step 3: Customize the Pipeline

The JSON5 pipeline definition file determines how the pipeline works and which algorithms and filters it uses.

The basic idea is that eye tracking and frame data (e.g, HMD transform data) is recorded, optionally pre-processed and then fused together. Algorithms are then applied on the fused data, generating for example fixation or saccade data.

Open the JSON5 file and customize the pipeline by for example adding a second algorithm called “saccade” which uses the built-in SaccadeSimple() filter. This will allow you to query for saccade results using this filter in this pipeline. It’s a good idea to rename this file to something like “myPipeline.json5”.

{
    "algorithms": {
        "fixation": {
            "FixationSimple": {}
        },
        "saccade": {
            "SaccadeSimple": {}
        }
    }
}

Step 4: Validate the Pipeline

To validate and make sure that the pipeline will execute, run:

ocumen_cli pipeline check --pipeline myPipeline.json5

This will validate that your JSON pipeline definition file is set up correctly and run some additional tests on it using pre-recorded data.


Step 5: Run the Pipeline

Once you have set up your pipeline, you can now record eye tracking data and feed it into the pipeline and then query for results.

Below is some example code using the myPipeline.json5 file we just set up.

public class SamplePipelineCode : MonoBehaviour
{
    private Pipeline _pipeline;
    private DataAggregator _dataAggregator;
    private int windowSizeUs = 100000; // Size of time window in microseconds.

    private void Start()
    {
        // Read pipeline definition file from StreamingAssets folder on PC.
        var filePath = Path.Combine(Application.streamingAssetsPath, "myPipeline.json5");
        var config = File.ReadAllText(filePath);

        // Create a pipeline and data aggregator.
        _pipeline = Pipeline.Create(config);
        _dataAggregator = new DataAggregator(windowSizeUs);
    }

    private void Update()
    {
        // Refresh data window with new frame and eye tracking data and feed that data into the pipeline.
        _dataAggregator.Tick();
        _pipeline.Execute(_dataAggregator.FrameData.ToArray(), _dataAggregator.EyeTrackingData.ToArray());

        // Query the pipeline for results and log them.
        var leftEyeSaccade = _pipeline.QueryResult<bool>("saccade", "is_saccade_left");
        Debug.Log(string.Join(Environment.NewLine, leftEyeSaccade.Values));
    }
}

Step 6: Run the Example Scene

We have created an example scene that visualizes Tobii Ocumen data and that uses the pipeline to showcase some filters in graph format.

Check out our Tobii Ocumen Example Showcase for more information.


Documentation

The full documentation for the pipeline and filters can be found in the downloadable Tobii Ocumen package.

It can also be generated by running:

ocumen_cli.exe pipeline document -f myDocumentation.md

This will create a markdown file called myDocumentation.md (see snippet below).