Troubleshooting the Tobii module
The module fails to start, with a generic initialization error
Cause. LicenceFile is empty, points at a missing file, or the file is unreadable. Loading
it is not specifically guarded in this module’s own code, so the failure surfaces as a generic
module-initialization error rather than a message naming the license file as the cause.
Fix. Confirm LicenceFile points at a real, readable Tobii license file for the connected
device before assuming the tracker itself is faulty.
No eye tracker is found
Cause. This module enumerates trackers once at startup; if none are connected and recognised by Tobii’s own Stream Engine SDK at that moment, it fails immediately rather than waiting or retrying.
Fix. Confirm the tracker is connected and recognised by the operating system before starting the capture session, then restart the session.
Gaze data looks correct but the mapped screen position is off
Cause. ScreenWidth, ScreenHeight or TrackerOffsetX don’t match the actual physical
screen and mounting. This produces a display area calculation that is internally consistent but
physically wrong - there is no error for this, only a systematically offset gaze-to-screen
mapping.
Fix. Measure the actual screen dimensions and tracker offset and correct the settings; this looks like a tracking-quality problem but is a geometry-configuration one.
Gaze accuracy is poor for a specific person
Cause. This module always applies the same bundled default calibration blob at every session start - there is no per-user or per-session calibration step. See Configure.
Fix. This is a real limitation in this version, not a setting to adjust. If per-operator calibration accuracy matters, it needs to be handled outside this module.
Gaze, pupillometry or head pose updates far less often than expected
Cause. Unlike the other eye-tracking modules in this catalogue, this data is only published
at Interval cadence, left at the SDK default of 1000 ms - not at Tobii’s own faster update
rate. See Configure.
Fix. Lower Interval if your scenario needs this data closer to real time. Video is not
affected by this.
Video never appears despite CaptureVideoFeed being on
Cause. Either the tracker’s camera reports a pixel format other than 8-bit greyscale, or the H264 encoder failed to initialize (no usable hardware or software MFT on the workstation). Both disable video for that session only; gaze, pupillometry and head pose are unaffected.
Fix. Check the log for the specific error logged once at the point video was disabled - either points at the actual cause rather than a generic failure.