Standalone Tobii Eye Tracker 4C support for Linux/X11.
tobii4c provides realtime gaze tracking, fullscreen calibration
and eye-controlled mouse interaction for Linux desktops using X11.
The current stable runtime is based on:
- Barycentric triangle mesh calibration
- 3x3 calibration mesh warping
- Tobii Stream Engine
- Direct X11 cursor control
- Low latency gaze smoothing
- Local triangle interpolation
- Optional Quha gyro integration
The current runtime does NOT yet use:
- Full projective warp
- Active bootstrap geometry
- Active C12 mapping
- Full 3D reprojection
These parts exist experimentally in newer branches but are not part of the current stable runtime.
Current stable runtime pipeline:
Tobii Eye Tracker 4C
│
▼
Tobii Stream Engine
│
▼
raw gaze coordinates
│
▼
triangle selection
│
▼
barycentric interpolation
│
▼
local warped coordinates
│
▼
runtime smoothing
│
▼
optional Quha gyro offset
│
▼
X11 cursor mapping
│
▼
XWarpPointer
bash install.shThis installs:
- Tobii USB service (
tobiiusb.service) - Tobii Stream Engine service (
tobii_engine.service) - Tobii shared libraries into
/usr/lib/tobii/ - Tobii headers into
/usr/include/tobii/ - Library config into
/etc/ld.so.conf.d/tobii.conf
Both systemd services are enabled and started automatically.
Afterwards, update the dynamic linker cache:
sudo ldconfigmakesudo make installInstalls to /usr/local/bin/ by default.
A custom prefix can be set:
sudo make install PREFIX=/usreyecalibeyemouseRemove Tobii services and libraries:
bash uninstall.shRemove binaries and man pages:
sudo make uninstalleyecalib runs in two phases:
Phase 1 — Native Tobii calibration via tobii_calibration_* API:
Adapts the tracker firmware to the user's eyes so the Stream Engine
delivers normalized [0..1] gaze coordinates. Without this step, raw
gaze values can be far outside [0..1] and the mesh calibration cannot
work correctly.
Phase 2 — Mesh calibration (barycentric warp): Collects gaze samples at 9 screen positions and builds the correction mesh that maps raw gaze to accurate screen coordinates.
Run:
eyecalibOptions:
| Option | Description |
|---|---|
-h --help |
Show command line help |
--debug |
Verbose debug output on stderr |
--debuggaze |
Verbose gaze output on stderr (high frequency) |
# debug calibration
eyecalib --debug
# gaze debug
eyecalib --debuggaze
# all to log file
eyecalib --debug --debuggaze 2>eyecalib.logThe calibration process:
Phase 1: Native Tobii calibration
-> tobii_calibration_start
-> tobii_calibration_collect_data_2d (9 points)
-> tobii_calibration_compute_and_apply
-> tobii_calibration_stop
-> tracker now delivers normalized [0..1] gaze
Phase 2: Mesh calibration
-> fullscreen targets
-> gaze sample collection (250 samples per point)
-> invalid sample rejection
-> gaze averaging
-> calibration mesh generation
-> persistent calibration storage
Calibration data is stored in:
~/.local/tobii_4c/calx11.conf
If a Tobii Pro Eye Tracker Manager profile exists at:
~/.config/TobiiProEyeTrackerManager/db/da-setups.db
eyecalib will automatically import physical screen geometry
(tracker placement, screen tilt, display dimensions) and derive
a sensor_offset_y correction from it.
The 9 targets are placed near screen edges to maximize fullscreen reachability:
P00(5%,5%) P01(50%,5%) P02(95%,5%)
P10(5%,50%) P11(50%,50%) P12(95%,50%)
P20(5%,95%) P21(50%,95%) P22(95%,95%)
Each line stores one calibration point:
raw_x raw_y target_x target_y
Example:
0.052524 0.075656 0.050000 0.050000
| Value | Meaning |
|---|---|
| raw_x | Measured Tobii gaze x |
| raw_y | Measured Tobii gaze y |
| target_x | Expected screen x (0–1) |
| target_y | Expected screen y (0–1) |
The config file also stores runtime parameters:
| Parameter | Default | Meaning |
|---|---|---|
| gaze_smooth | 0.12 | Gaze low-pass filter strength |
| cursor_smooth | 0.22 | Cursor low-pass filter strength |
| edge_zone | 0.08 | Edge expansion zone width |
| edge_power | 1.35 | Edge expansion nonlinearity |
| sensor_offset_x | 0.0 | Horizontal sensor offset |
| sensor_offset_y | 0.0 | Vertical sensor offset |
| screen_distance | 63.0 | Viewing distance |
| screen_tilt | 0.0 | Screen tilt angle in degrees |
eyemouse [options] [config_file]| Option | Description |
|---|---|
-h --help |
Show command line help |
--usegyro |
Enable Quha gyro, grab Quha exclusively |
--leaveXgyro |
Enable Quha gyro, leave Quha as X11 mouse |
--blink |
Enable blink click |
--blink-left <ms> |
Left click threshold in ms (default: 80) |
--blink-right <ms> |
Right click threshold in ms (default: 300) |
--blink-hold <ms> |
Hold toggle threshold in ms (default: 600) |
--debug |
Verbose debug output on stderr |
--debuggaze |
Verbose gaze output on stderr (high frequency) |
--debuggyro |
Verbose gyro event output on stderr (high frequency) |
--debugblink |
Verbose blink event output on stderr |
# default calibration
eyemouse
# custom calibration file
eyemouse ~/.local/tobii_4c/calx11.conf
# with Quha gyro
eyemouse --usegyro
# gyro with custom calibration
eyemouse --usegyro tobii.conf
# blink click enabled
eyemouse --blink
# blink with custom thresholds
eyemouse --blink --blink-left 100 --blink-right 350 --blink-hold 650
# blink + gyro
eyemouse --blink --usegyro
# debug mode
eyemouse --debug
# debug mode with gyro
eyemouse --debug --usegyro
# gaze debug (high frequency)
eyemouse --debuggaze
# gyro event debug (high frequency)
eyemouse --debuggyro
# blink debug
eyemouse --blink --debugblink
# all debug output to log file
eyemouse --debug --debuggaze --debuggyro --debugblink 2>eyemouse.logeyemouse --blink enables eye blink gesture recognition for mouse clicks.
Blink duration determines the action:
| Duration | Action |
|---|---|
< --blink-left (default 80ms) |
Noise, ignored |
| 80ms – 300ms | Left click |
| 300ms – 600ms | Right click |
| ≥ 600ms | Hold toggle |
Hold toggle alternately presses and releases the left mouse button, enabling drag operations without physical input.
All thresholds are configurable:
eyemouse --blink --blink-left 100 --blink-right 350 --blink-hold 650Requires libXtst (-lXtst) at build time.
Screen: 1920x1080
Device: tobii-prp://<serial>
Gyro disabled
Mouse 1365 150
The 9 calibration points form a triangulated mesh:
P00 P01 P02
P10 P11 P12
P20 P21 P22
The mesh is split into 8 triangles. For every gaze sample:
- The containing triangle is selected
- Barycentric weights are calculated
- Local warped screen coordinates are interpolated
This improves:
- Fullscreen reachability
- Edge precision
- Corner access
- Asymmetric distortion correction
- Local edge compensation
Without mesh correction, raw gaze mapping typically causes:
- Compressed edges
- Unstable corners
- Asymmetric fullscreen reachability
- Poor border access
The runtime applies two-stage exponential smoothing:
gaze_smooth = 0.12 (gaze low-pass)
cursor_smooth = 0.22 (cursor low-pass)
A deadzone of 3 pixels suppresses micro-jitter when the eye is stationary.
This improves:
- Cursor stability
- Accessibility usage
- Fullscreen usability
- Small target interaction
The Quha device is automatically detected via:
/dev/input/by-id/
When --usegyro is active, the Quha device is grabbed exclusively
using EVIOCGRAB. This prevents X11 from receiving raw Quha mouse
events in parallel while eyemouse controls the cursor.
When --leaveXgyro is used instead, the Quha gyro input is read
but the Quha is not grabbed — it continues to operate as a
normal X11 mouse alongside the eyetracker.
Without --usegyro or --leaveXgyro, the Quha is not touched
and operates normally as an X11 mouse.
If the exclusive grab fails, a warning is printed and eyemouse continues — but X11 may still receive Quha events simultaneously.
On SIGTERM, SIGINT, or SIGHUP the grab is released automatically
before exit, so the Quha resumes normal X11 mouse operation immediately.
Both --usegyro and --leaveXgyro read Quha movement events and apply
them as a relative offset on top of the Tobii gaze position. The offset
decays exponentially (factor 0.92 per frame), so gaze remains the
primary positioning input.
eyemouse supports two independent debug flags:
| Flag | Prefix | Content |
|---|---|---|
--debug |
[DBG] |
Init, Quha grab, XWarpPointer calls |
--debuggaze |
[GAZE] |
Every gaze sample, warp/triangle selection, uvw, frame stats |
--debuggyro |
[GYRO] |
Every REL_X/REL_Y gyro event with value and accumulated offset |
--debugblink |
[BLINK] |
Eye open/close events, duration, action taken |
Both flags write to stderr and can be combined:
eyemouse --debug 2>debug.log
eyemouse --debuggaze 2>gaze.log
eyemouse --debuggyro 2>gyro.log
eyemouse --debug --debuggaze --debuggyro 2>full.log
eyemouse --debuggaze 2>&1 | grep GAZE
eyemouse --debuggyro 2>&1 | grep GYRO--debuggaze and --debuggyro are high frequency and should be
redirected to a file when used together with --debug.
Both tools require an active X11 session. Wayland is currently not supported.
Verify your session type:
echo $XDG_SESSION_TYPE
# must output: x11Run eyecalib again at any time to recalibrate.
The previous calibration file will be overwritten.
The calibration file is plain text and can also be edited manually:
~/.local/tobii_4c/calx11.conf
Partially implemented or experimental:
- Bootstrap geometry import
- C12 runtime
- 3D gaze reprojection
- Head compensated mapping
- Projective warp
- Adaptive mesh refinement
- Binocular convergence estimation
- Advanced geometry correction
These are not fully active in the stable runtime.
Planned future improvements:
- Projective warp / homography
- Bilinear mesh interpolation
- Geometry-aware reprojection
- Headpose compensation
- Dynamic runtime calibration
- Adaptive edge expansion
- Improved corner precision
| Path | Description |
|---|---|
~/.local/tobii_4c/calx11.conf |
Calibration and runtime config |
/usr/lib/tobii/ |
Tobii Stream Engine shared libraries |
/usr/include/tobii/ |
Tobii Stream Engine headers |
/etc/ld.so.conf.d/tobii.conf |
Library path config |
/etc/systemd/system/tobii_engine.service |
Tobii engine service |
/etc/systemd/system/tobiiusb.service |
Tobii USB service |
tobii.conf |
Library path source file (copied by install.sh) |
examples/ |
Usage examples |
MIT-style open source / research-oriented project.