Scanpath Studio

Scanpath Studio shows you how people read. Load eye-tracking-while-reading data and watch each trial unfold over the text, exactly where it sat on the screen — then compare participants, analyze a corpus, and export figures ready for a paper.

Get started

• As a desktop app, the easiest way to work with your own data: Windows · macOS (Apple silicon) · Linux.

• With pip (Python 3.11–3.14):

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

• In the browser, to try it on the bundled demo data: the live demo at https://scanpath-studio.streamlit.app.

The desktop and pip installs keep your data on your own machine, handle large datasets, and download the public corpora (PoTeC, OneStop) in one click. The hosted demo runs on Streamlit Community Cloud, with limited memory and no corpus downloads.

What you can do

• See the reading: fixations, saccades, heatmaps and raw gaze over the text at its true on-screen position, with fixations colored by any column.
• Replay it in real time or faster, and export it as HTML, GIF or MP4.
• Compare participants: overlay two trials or place them side by side — even from two different datasets.
• Analyze a corpus per text, participant or group, from the reading measures your data brings, each defined in the computation register.
• Triage, export and share: tag and filter trials, export one figure or a zip for every trial, and share a link that reopens the exact view.

A trial, replayed fixation by fixation	Two participants on one paragraph, overlaid (animated)

The app has three views: 🗺️ Scanpath for one trial at a time, 📊 Corpus Analysis for the whole dataset, and 🗂️ Data Management for loading and configuring datasets. The feature guides walk through each one.

Your data

Load word, fixation and raw-gaze tables in CSV, Parquet, Excel or another common format. Scanpath Studio adapts to how your study was recorded, so there is rarely anything to reformat first — see Loading public and own data.

Command line & Python API

Everything the app draws is also available headless — same pipeline, same figure. These run as-is on the bundled demo:

scanpath-studio render --sample --list-trials          # the demo's trials
scanpath-studio render --sample -o scanpath.html       # one trial, interactive HTML
scanpath-studio render --sample --animate -o replay.html
scanpath-studio render --sample -p l37_1129 -t l37_1129_2_1_1_Ele_r0 \
  --compare-with l7_1090:l7_1090_2_1_1_Ele_r0 -o compare.html

import scanpath_studio as sps

words, fixations = sps.load_sample_data()
print(sps.list_trials(words, fixations).head())
fig = sps.plot_scanpath(words, fixations, "l37_1129", "l37_1129_2_1_1_Ele_r0")
sps.save_figure(fig, "scanpath.html")

For your own files, pass --words ia.csv --fixations fix.csv to render, or use sps.load_scanpath_data("ia.csv", "fix.csv"). HTML output needs nothing else; PNG, SVG and PDF (and GIF/MP4 replays) go through Kaleido, which needs Chrome, Chromium or Edge, or run plotly_get_chrome -y once. The CLI reference and the Python API reference list every flag and parameter.

Where next

The full documentation is at https://lacclab.github.io/scanpath-studio/:

• Getting started: install, launch and a first trial
• Tutorials: task walk-throughs, from checking a pilot to a figure for a paper
• Feature guides: every view and control
• Loading public and own data: what the loader accepts and how to map it
• CLI and Python API: scripting and batch rendering
• Gallery: the figures it draws, each with the code that makes it
• Computation register: how each measure is derived
• FAQ · Cite

Contributing

git clone https://github.com/lacclab/scanpath-studio.git
cd scanpath-studio
pip install -e ".[test]"          # or: uv sync --extra test --extra lint
streamlit run streamlit_app.py --server.address 127.0.0.1
pytest -n auto

CONTRIBUTING.md covers setup, the checks that gate CI, and how work is tracked in GitHub Issues; AGENTS.md is the architectural map. To preview the docs site locally, run pip install -e ".[docs]" and then mkdocs serve.

Taking part means following the Code of Conduct.

Citation

A paper is in preparation. Until then, cite the software by its DOI, 10.5281/zenodo.22933884 (GitHub's Cite this repository button formats it as APA or BibTeX). If you use the bundled demo, a subset of OneStop Eye Movements, please also cite:

@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},
}

AI-assisted software

Scanpath Studio was built with AI assistance. Cross-check results before publishing. If something looks wrong — or if you have a feature request or suggestion — report it.