Scanpath Studio

An interactive workbench for visualizing eye-tracking-while-reading data. Drop in a trial and see the scanpath the way the reader saw it — words at their true on-screen positions, with fixations, saccades, a density heatmap, and animated replay layered on top, all exportable as publication-ready figures.

It is dataset-agnostic (auto-detects EyeLink / Gazepoint / snake-case columns) and ships with a small OneStop demo, so you can try it with zero setup.

Authors: Omer Shubi, Keren Gruteke Klein, Ella Lion, Deborah N. Jakobi, David R. Reich, Lena Jäger, and Yevgeni Berzak — Data and Decision Sciences (Technion) and Department of Computational Linguistics (University of Zurich).

A scanpath replayed fixation by fixation over the text the reader saw.

Try it

Live demo (zero install): https://scanpath-studio.streamlit.app

pip install scanpath-studio
scanpath-studio      # launches the app in your browser

What it does

The scanpath plot is built from layers you toggle independently:

• Text drawn at the exact pixel coordinates the participant saw.
• Fixations sized and colored by any column in your data (duration, GPT-2 surprisal, word frequency, …).
• Saccades, with backward jumps (regressions) standing out.
• Areas of interest (word boxes from your data) and a word-level heatmap (total fixation duration, count, …).

On top of that:

• Animated replay — watch the scanpath unfold at real or scaled speed; export as interactive HTML, GIF, or MP4.
• Compare readings — overlay two trials on one canvas or place them side by side (e.g. ordinary vs. information-seeking, first vs. repeated, L1 vs. L2).
• Critical-span, out-of-text & by-line highlights — mark an answer span, flag fixations outside every word box, or color fixations by text line.
• Triage — star, tag, and annotate trials; save and restore everything as a JSON sidecar.
• Bulk export — one zip of per-trial PNG + SVG figures, plot settings, and tabular data across every filtered trial.

Two readers of the same bundled-demo paragraph, overlaid on one canvas — 305 fixations between them (watch it animated).

The app is organized into three tabs:

Project map

Solid = built, dashed = planned (see the improvements tracker).

Your data

Upload CSV, TSV, Parquet, or Feather tables for words/AoIs, fixations, and (optionally) raw gaze. Columns are auto-detected from common EyeLink, Gazepoint, and snake-case conventions; a sidebar Column mapping panel overrides any guess. The loader bends to fit real corpora — many files per table (concatenated with a source_file tag), a single report (words- or fixations-only), stimulus-level word boxes broadcast across readers, and AoI-sequence fixations placed at word/character-box centers.

If your data carries only raw fixations, the app computes the canonical per-word measures itself — FFD, FPRT (gaze duration), RPD (go-past), TFD (dwell), plus skips and regressions, following Rayner (1998) and Inhoff & Radach (1998). Pre-aggregated EyeLink columns, when present, take precedence.

A ready-made PoTeC loader (Potsdam Textbook Corpus) exercises that flexible pipeline end to end:

import scanpath_studio as sps

words, fixations = sps.load_potec("data/PoTeC", download=True)   # ~45 MB on first call
fig = sps.plot_scanpath(words, fixations, "0", "b0", canvas_size=(1680, 1050))

Command line & Python API

Everything the app draws is also available headless — same pipeline, same figure.

scanpath-studio render --sample --list-trials              # what's available
scanpath-studio render --sample -o scanpath.html           # interactive HTML
scanpath-studio render --words ia.csv --fixations fix.csv -p p1 -t t3 -o figure.png
scanpath-studio render --sample --animate -o replay.html   # animated replay

import scanpath_studio as sps

words, fixations = sps.load_scanpath_data("ia.csv", "fixations.csv")  # paths, globs, or lists; either table optional
sps.list_trials(words, fixations)
fig = sps.plot_scanpath(words, fixations, "p1", "t3")     # every layer toggle is a kwarg
sps.save_figure(fig, "scanpath.png")                       # .html / .png / .svg / .pdf
measures = sps.compute_word_metrics(words, fixations)      # FFD / FPRT / RPD / TFD …

HTML export is browser-free; PNG/SVG/PDF/GIF/MP4 go through Kaleido (run plotly_get_chrome -y once). See scanpath-studio render --help for all flags.

Run from source

git clone https://github.com/lacclab/scanpath-studio.git
cd scanpath-studio
pip install -e ".[test]"          # or: uv sync
streamlit run streamlit_app.py

Tested on Python 3.11–3.14. Run the tests with pytest; see AGENTS.md for an architectural overview.

Documentation

Full docs — getting started, the Python API, the CLI reference, data format, and export/troubleshooting — are at https://lacclab.github.io/scanpath-studio/ (built from docs/ with MkDocs Material). Build them locally with:

pip install -e ".[docs]"
mkdocs serve

Citation

A system-demo paper is in preparation — citation TBD. Until then, cite the software via GitHub's "Cite this repository" button (generated from CITATION.cff).

If you use the bundled demo data, please cite the OneStop corpus:

@article{berzak2025onestop,
  title     = {{OneStop}: A 360-Participant {E}nglish Eye Tracking Dataset
               with Different Reading Regimes},
  author    = {Berzak, Yevgeni and Malmaud, Jonathan and Shubi, Omer
               and Meiri, Yoav and Lion, Ella and Levy, Roger},
  journal   = {Scientific Data},
  year      = {2025},
  publisher = {Nature Publishing Group},
  doi       = {10.1038/s41597-025-06272-2},
  url       = {https://www.nature.com/articles/s41597-025-06272-2},
}

The bundled demo is a subset of OneStop Eye Movements, used under its original license (docs).

Built with AI assistance

Much of this code was written with AI assistance. Two things you can check: the reading measures are pinned to a ground-truth trial with expected values per measure (open it with ?source=synthetic), and EyeLink IA_* measures already in your export are passed through, not recomputed.

That is not the same as bug-free. Cross-check anything you publish against your own pipeline. If something looks wrong, open an issue with the JSON from 💾 Save & restore — it reproduces the exact view.

License

MIT — see LICENSE.