SPEED Pro (v6.0.0.0) - LabSCoC Software for Processing and Extraction of Eye-tracking Data

📖 Table of Contents

1. Overview & What's New in SPEED Pro v6
2. Environment Setup with Anaconda & Dependencies
3. SPEED Desktop Application (GUI for Researchers)
   • The Modular Workflow
   • The 4 AOI Strategies
   • Real-Time Suite & LSL Bridge
   • Interactive Analysis Tools
4. Command-Line Interface (CLI)
5. Data Standards & Interoperability (BIDS & DICOM)
   • BIDS Integration
   • DICOM PACS Waveform Integration
6. Synthetic Data & Stream Generators
7. SPEED Pro v6: High-Performance Architecture & API
   • Clean / Hexagonal Architecture
   • Pure Vectorized Math Engines (I-VT, Homography, NSI)
   • Immutable Domain Models & Interfaces
   • Hardware Adapters (Pupil Labs & Mocks)
8. Docker Container Usage
9. Authors, Academic Citations & Publications
10. Artificial Intelligence Disclosure
11. License

1. Overview & What's New in SPEED Pro v6

SPEED (Software for Processing and Extraction of Eye-tracking Data) is an advanced scientific framework developed by the Cognitive and Behavioral Science Lab (LabSCoC) at the University of L'Aquila.

Version 6.0.0.0 introduces a high-performance architectural overhaul (SPEED Pro v6) while maintaining full compatibility with the complete analysis ecosystem:

• SPEED Desktop App: User-friendly GUI application with interactive timeline editors, multi-task YOLO computer vision, video-in-video rendering, and live camera streaming.
• speed-analyzer Package: The core scientific library available on PyPI, re-architected with Clean / Hexagonal Architecture, SOLID principles, strict Python 3.11+, and Pydantic v2 validation.
• Pure Vectorized Mathematical Engines: Ultra-fast implementations of I-VT (Velocity-Threshold Identification), RANSAC Homography perspective transforms, and Nearest Surface Intersection (NSI).
• Open Standards: Native support for BIDS (Brain Imaging Data Structure) and DICOM Waveform IOD for clinical PACS environments.

2. Environment Setup with Anaconda & Dependencies ⚙️

To install SPEED and run either the Desktop GUI, CLI scripts, or Python developer APIs, follow the Anaconda setup guide below.

Step 1: Install Anaconda or Miniconda

Download and install Anaconda (or lightweight Miniconda) from the official website:

• Anaconda Installer
• Miniconda Installer

Step 2: Create a Dedicated Conda Environment

Open Anaconda Prompt (Windows) or your Terminal (macOS/Linux) and create a dedicated Python 3.12 environment:

# 1. Create conda environment
conda create --name speed python=3.12 -y

# 2. Activate the environment
conda activate speed

# 3. Ensure pip and git are up-to-date
conda install pip git -y

Step 3: (Optional) GPU Acceleration with NVIDIA CUDA

If you plan to use YOLO-based deep learning, real-time tracking, or neural vision models with GPU acceleration:

1. Install NVIDIA CUDA Toolkit (e.g. CUDA 12.1+).
2. Install PyTorch with CUDA support matching your system via PyTorch Get Started:

# Example for CUDA 12.4
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

Step 4: Install SPEED

Option A: Install from PyPI (Recommended for Library Users)

pip install speed-analyzer==6.0.0.0

Option B: Install from Source (For GUI & Full Development)

# Clone the repository
git clone https://github.com/danielelozzi/SPEED-pro.git
cd SPEED-pro

# Install using high-speed uv package manager (recommended)
pip install uv
uv pip install -e "speed_v6[dev]"

3. SPEED Desktop Application (GUI for Researchers)

The Desktop App provides a graphical user interface for researchers and end-users, automating the pipeline without requiring manual code.

Launching the GUI

From the activated speed environment:

conda activate speed
python -m desktop_app.GUI

The Modular Workflow

1. Input Folders:
   • Select your RAW Data Folder (Pupil Labs recording, external cameras) and Un-enriched Data Folder.
   • Alternatively, load directly from a BIDS Directory or a DICOM File.
2. Advanced Event Management:
   • Create, edit, and filter experimental markers and triggers.
   • Synchronize video events with millisecond precision using the interactive visual editor.
3. Core Analysis:
   • Executes fixation identification, saccade velocity extraction, blink filtering, pupil dilation analysis, and metrics aggregation.
4. On-Demand Output Generation:
   • Plots 📊: Scanpaths, fixation heatmaps, pupil time-series, velocity profiles.
   • Videos 🎬: Gaze overlay, fixation circles, dynamic AOI tracking overlays.
   • Video-in-Video: Replaces the scene camera view with the screen content being watched, synchronized with the gaze point.

The 4 AOI Strategies

SPEED supports 4 distinct Area of Interest (AOI) definition strategies:

Real-Time Suite & LSL Bridge

• Dual-Camera Live Feed: Real-time simultaneous visualization of external world view and eye camera.
• Live Pupillometry & Blink Detection: Instantaneous fragmentation and pupil diameter monitoring.
• Lab Streaming Layer (LSL): Built-in realtime_lsl_bridge.py and lsl_time_series_viewer.py allowing real-time multi-channel broadcasting and visualization of gaze coordinates alongside EEG, fNIRS, or ECG data.

Interactive Analysis Tools

• Data Viewer: Multi-modal viewer for BIDS/DICOM/Un-enriched data with interactive playback, on-the-fly YOLO detections, and filtering.
• Data Plotter: Interactive exploration of continuous time-series (pupil, gaze, fixations) with range statistics.
• Interactive NSI Calculator: Timeline-based tool for computing the Normalized Switching Index between AOIs within defined windows.

4. Command-Line Interface (CLI)

SPEED includes CLI utilities for automated headless batch processing and server environments:

# Run batch analysis across multiple subjects
python -m speed_analyzer.analysis_modules.classify_cli \
    --input-dir ./data/recordings \
    --output-dir ./analysis_output \
    --velocity-threshold 30.0

Programmatic execution via Python:

from pathlib import Path
from speed_analyzer import run_full_analysis

run_full_analysis(
    raw_data_path="./data/raw",
    unenriched_data_path="./data/unenriched",
    output_path="./results",
    subject_name="participant_01",
)

5. Data Standards & Interoperability (BIDS & DICOM)

BIDS Integration

SPEED natively supports the Brain Imaging Data Structure (BIDS) eye-tracking specification (_eyetrack.tsv.gz, _events.tsv):

from pathlib import Path
from speed_analyzer import convert_to_bids, load_from_bids

# Export un-enriched recording to BIDS format
convert_to_bids(
    unenriched_dir=Path("./data/unenriched"),
    output_bids_dir=Path("./bids_dataset"),
    subject_id="01",
    session_id="01",
    task_name="visualsearch",
)

# Load existing BIDS dataset for analysis
temp_folder = load_from_bids(
    bids_dir=Path("./bids_dataset"),
    subject_id="01",
    session_id="01",
    task_name="visualsearch",
)

DICOM PACS Waveform Integration

For clinical workflows and medical imaging environments, SPEED converts eye-tracking waveforms into DICOM Waveform IOD objects compatible with Picture Archiving and Communication Systems (PACS):

from pathlib import Path
from speed_analyzer import convert_to_dicom, load_from_dicom

# Export to clinical DICOM file
convert_to_dicom(
    unenriched_dir=Path("./data/unenriched"),
    output_dicom_path=Path("./exports/subject01.dcm"),
    patient_info={"name": "Patient 01", "id": "SUB01"},
)

# Load back from a DICOM file
temp_path = load_from_dicom(dicom_path=Path("./exports/subject01.dcm"))

6. Synthetic Data & Stream Generators 🧪

SPEED includes synthetic simulators for testing pipelines without physical hardware:

# 1. Generate full offline dummy dataset (gaze.csv, fixations.csv, external.mp4)
python generate_synthetic_data.py

# 2. Simulate live streaming for Real-Time GUI testing
python generate_synthetic_stream.py

# 3. Simulate high-frequency LSL eye-tracking stream
python lsl_stream_simulator.py

7. SPEED Pro v6: High-Performance Architecture & API

The speed_v6 core represents the state-of-the-art implementation adhering to Clean Architecture / Hexagonal Architecture (Ports & Adapters).

                   ┌─────────────────────────────────────────┐
                   │           Presentation / UI             │
                   └────────────────────┬────────────────────┘
                                        │
                   ┌────────────────────▼────────────────────┐
                   │          Application Pipeline           │
                   └────────────────────┬────────────────────┘
                                        │
    ┌───────────────────────────────────┴───────────────────────────────────┐
    │                          Core Domain Layer                            │
    │                                                                       │
    │  ┌──────────────────────┐  ┌─────────────────┐  ┌──────────────────┐  │
    │  │  Pydantic v2 Models  │  │ Core Interfaces │  │    Core Math     │  │
    │  │  - GazeDatum         │  │ - IEyeTracker   │  │  - Homography    │  │
    │  │  - FramePacket       │  │ - ICameraStream │  │  - I-VT Classifier│ │
    │  │  - Surface, AOI      │  │ - IDetector     │  │  - NSI Proximity │  │
    │  │  - BoundingBox       │  │ - ITelemetrySink│  │  - Switching Idx │  │
    │  └──────────────────────┘  └────────▲────────┘  └──────────────────┘  │
    └─────────────────────────────────────┼─────────────────────────────────┘
                                          │ Inversion of Control (Protocols)
    ┌─────────────────────────────────────┴─────────────────────────────────┐
    │                     Infrastructure & Adapters                         │
    │                                                                       │
    │  ┌──────────────────────┐  ┌─────────────────┐  ┌──────────────────┐  │
    │  │   Pupil Labs Neon    │  │ OpenCV / RTSP   │  │  PyArrow Parquet │  │
    │  │   Hardware Client    │  │  Camera Stream  │  │   Telemetry Sink │  │
    │  └──────────────────────┘  └─────────────────┘  └──────────────────┘  │
    └───────────────────────────────────────────────────────────────────────┘

Pure Vectorized Math Engines

1. Oculomotor I-VT Classifier (speed_v6.core.math.oculometrics)

Vectorized Velocity-Threshold Identification algorithm classifying gaze samples into FIXATION, SACCADE, and BLINK with structured event aggregation:

import numpy as np
from speed_v6.core.math.oculometrics import IVTClassifier

timestamps_ns = np.array([i * 10_000_000 for i in range(100)], dtype=np.int64) # 100 Hz
coords = np.zeros((100, 2))
coords[:70] = [0.3, 0.3]  # Fixation
coords[70:] = np.linspace([0.3, 0.3], [0.8, 0.8], 30)  # Saccade

labels = IVTClassifier.classify(timestamps_ns, coords, velocity_threshold=2.0)
fixations = IVTClassifier.extract_fixations(timestamps_ns, coords, labels, min_duration_ms=100.0)

for fix in fixations:
    print(f"Fixation at ({fix.centroid_x:.3f}, {fix.centroid_y:.3f}) for {fix.duration_ms:.1f}ms")

2. Homography Estimation & Projection (speed_v6.core.math.homography)

RANSAC-based 3x3 projective transformation with outlier filtering and safe homogeneous normalization:

import numpy as np
from speed_v6.core.math.homography import HomographyTransformer

src = np.array([[0.1, 0.1], [0.9, 0.1], [0.85, 0.85], [0.15, 0.9]])
dst = np.array([[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0]])

h_matrix, mask, rms_err = HomographyTransformer.find_homography(src, dst)
screen_x, screen_y = HomographyTransformer.project_gaze(0.5, 0.5, h_matrix)
print(f"Screen coordinates: ({screen_x:.4f}, {screen_y:.4f})")

3. Nearest Surface Intersection (speed_v6.core.math.nsi)

Calculates minimum Euclidean distance from gaze coordinates to polygon boundaries, centroid proximity, and Normalized Switching Index ($NSI = \frac{K-1}{L_{in}-1}$):

from speed_v6.core.models.spatial import Surface
from speed_v6.core.math.nsi import NearestSurfaceIntersection

surface = Surface(
    id="screen_1",
    name="Monitor Display",
    vertices=((0.1, 0.1), (0.9, 0.1), (0.9, 0.9), (0.1, 0.9)),
)

result = NearestSurfaceIntersection.find_nearest_surface((0.5, 0.5), [surface])
print(f"Inside: {result.is_inside}, Min distance: {result.min_distance}")

Hardware Adapters

• PupilLabsEyeTracker: Asynchronous adapter wrapping pupil_labs.realtime_api with dedicated worker thread ingestion to prevent blocking the asyncio loop.
• MockEyeTrackerStream: High-frequency synthetic hardware simulator (120 Hz, 200 Hz) for automated testing.

8. Docker Container Usage

For fully reproducible cross-platform deployments without manual dependency installations, use the pre-built Docker container from GitHub Container Registry (GHCR):

# Pull container
docker pull ghcr.io/danielelozzi/speed:latest

# Run interactive container
docker run -it --rm -v $(pwd)/data:/app/data ghcr.io/danielelozzi/speed:latest

9. Authors, Academic Citations & Publications ✍️

SPEED is developed and maintained by Dr. Daniele Lozzi and the Cognitive and Behavioral Science Lab (LabSCoC), Department of Applied Clinical Sciences and Biotechnology, University of L'Aquila.

If you use SPEED or SPEED Pro in your research, please cite our publications:

• Primary Software Citation:
  Lozzi, D.; Di Pompeo, I.; Marcaccio, M.; Ademaj, M.; Migliore, S.; Curcio, G. SPEED: A Graphical User Interface Software for Processing Eye Tracking Data. Software 2024, 6(2), 35. DOI: 10.3390/software6020035

• AI-Powered Eye Tracking in Sports / Motion:
  Lozzi, D.; Di Pompeo, I.; Marcaccio, M.; Alemanno, M.; Krüger, M.; Curcio, G.; Migliore, S. AI-Powered Analysis of Eye Tracker Data in Basketball Game. Sensors 2025, 25(11), 3572. DOI: 10.3390/s25113572

• Pupil Labs Neon Reference:
  Baumann, C., & Dierkes, K. (2023). Neon accuracy test report. Pupil Labs. DOI: 10.5281/zenodo.10420388

• YOLO Real-Time Object Detection:
  Redmon, J., Divvala, S., Girshick, R., & Farhadi, A. (2016). You only look once: Unified, real-time object detection. CVPR 2016. DOI: 10.1109/CVPR.2016.91

• Eye-Tracking BIDS Standard:
  Szinte, M., et al. (2025). Eye-Tracking-BIDS: the brain imaging data structure extended to gaze position and pupil data. Journal of Vision, 25(9), 2351. DOI: 10.1167/jov.25.9.2351

• DICOM Waveform Inspiration:
  Di Matteo, A., Lozzi, D., Mignosi, F., Polsinelli, M., & Placidi, G. (2025). A DICOM-based standard for quantitative physical rehabilitation. Comput. Struct. Biotechnol. J., 28, 40-49. DOI: 10.1016/j.csbj.2025.01.012

@article{lozzi2024speed,
  title={SPEED: A Graphical User Interface Software for Processing Eye Tracking Data},
  author={Lozzi, Daniele and Di Pompeo, Ilaria and Marcaccio, Martina and Ademaj, Matias and Migliore, Simone and Curcio, Gianluca},
  journal={Software},
  volume={6},
  number={2},
  pages={35},
  year={2024},
  publisher={MDPI},
  doi={10.3390/software6020035},
  url={https://www.mdpi.com/2673-4087/6/2/35}
}

10. Artificial Intelligence Disclosure 💻

The architecture, refactoring, and code engineering of SPEED Pro v6 were developed using Google DeepMind Antigravity IDE powered by Gemini Extended / Advanced Agentic Coding, following Clean Architecture, SOLID, and strict type-safe paradigms.

11. License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2024-2026 Daniele Lozzi, Laboratorio di Scienze Cognitive e del Comportamento.