Metadata-Version: 2.5
Name: speed-analyzer
Version: 6.0.0.0
Summary: SPEED Pro v6: High-performance eye-tracking, real-time computer vision, and spatial oculometric analysis framework
Project-URL: Homepage, https://github.com/danielelozzi/SPEED-pro
Project-URL: Repository, https://github.com/danielelozzi/SPEED-pro
Project-URL: Bug Tracker, https://github.com/danielelozzi/SPEED-pro/issues
Author-email: "Dr. Daniele Lozzi, LabSCoC" <daniele.lozzi@univaq.it>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: numpy>=1.26.0
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: pupil-labs-realtime-api>=1.1.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pylsl>=1.16.0
Requires-Dist: scipy>=1.11.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

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

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/speed-analyzer.svg?color=blue)](https://pypi.org/project/speed-analyzer/)
[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://www.python.org/)
[![Type Checked](https://img.shields.io/badge/mypy-strict-brightgreen.svg)](https://mypy-lang.org/)
[![Code Style](https://img.shields.io/badge/code%20style-ruff-black.svg)](https://github.com/astral-sh/ruff)
[![Tests](https://img.shields.io/badge/tests-pytest-blueviolet.svg)](https://pytest.org/)
[![Architecture](https://img.shields.io/badge/architecture-Clean%20%2F%20Hexagonal-orange.svg)]()
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.3390%2Fsoftware6020035-blue.svg)](https://doi.org/10.3390/software6020035)

**Comprehensive Framework for Eye-Tracking Data Analysis, Real-Time Computer Vision, Spatial Oculometrics, Desktop GUI & Python Library**

</div>

---

## 📖 Table of Contents

1. [Overview & What's New in SPEED Pro v6](#1-overview--whats-new-in-speed-pro-v6)
2. [Environment Setup with Anaconda & Dependencies](#2-environment-setup-with-anaconda--dependencies-⚙️)
3. [SPEED Desktop Application (GUI for Researchers)](#3-speed-desktop-application-gui-for-researchers)
   - [The Modular Workflow](#the-modular-workflow)
   - [The 4 AOI Strategies](#the-4-aoi-strategies)
   - [Real-Time Suite & LSL Bridge](#real-time-suite--lsl-bridge)
   - [Interactive Analysis Tools](#interactive-analysis-tools)
4. [Command-Line Interface (CLI)](#4-command-line-interface-cli)
5. [Data Standards & Interoperability (BIDS & DICOM)](#5-data-standards--interoperability-bids--dicom)
   - [BIDS Integration](#bids-integration)
   - [DICOM PACS Waveform Integration](#dicom-pacs-waveform-integration)
6. [Synthetic Data & Stream Generators](#6-synthetic-data--stream-generators-🧪)
7. [SPEED Pro v6: High-Performance Architecture & API](#7-speed-pro-v6-high-performance-architecture--api)
   - [Clean / Hexagonal Architecture](#clean--hexagonal-architecture)
   - [Pure Vectorized Math Engines (I-VT, Homography, NSI)](#pure-vectorized-math-engines)
   - [Immutable Domain Models & Interfaces](#immutable-domain-models--interfaces)
   - [Hardware Adapters (Pupil Labs & Mocks)](#hardware-adapters)
8. [Docker Container Usage](#8-docker-container-usage)
9. [Authors, Academic Citations & Publications](#9-authors-academic-citations--publications-✍️)
10. [Artificial Intelligence Disclosure](#10-artificial-intelligence-disclosure-💻)
11. [License](#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](https://pypi.org/project/speed-analyzer/), 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](https://www.anaconda.com/download)
- [Miniconda Installer](https://docs.anaconda.com/miniconda/)

### Step 2: Create a Dedicated Conda Environment
Open **Anaconda Prompt** (Windows) or your **Terminal** (macOS/Linux) and create a dedicated Python 3.12 environment:

```bash
# 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](https://developer.nvidia.com/cuda-downloads) (e.g. CUDA 12.1+).
2. Install PyTorch with CUDA support matching your system via [PyTorch Get Started](https://pytorch.org/get-started/locally/):

```bash
# 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)
```bash
pip install speed-analyzer==6.0.0.0
```

#### Option B: Install from Source (For GUI & Full Development)
```bash
# 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:

```bash
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:

| Strategy | Description | Best For |
| :--- | :--- | :--- |
| **1. Static AOI** | User-defined fixed rectangle on stationary coordinates. | Fixed screen experiments, static images, kiosk displays. |
| **2. Dynamic AOI (YOLO Tracking)** | Automatically tracks detected objects using YOLOv8 with **BoT-SORT** or **ByteTrack**. | Moving people, sports balls, vehicles, faces, hands. |
| **3. Dynamic AOI (Keyframes)** | Manual keyframe interpolation where the user adjusts AOI bounds at key timestamps. | Deforming objects, occluded scenes, complex camera pan. |
| **4. Surface from Markers (ArUco / QR)** | Estimates perspective homography to map gaze onto dynamic non-rectangular surfaces. | Tablets, monitors, flight cockpits, mobile devices. |

### 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:

```bash
# 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:

```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`):

```python
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):

```python
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:

```bash
# 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:

```python
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:

```python
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}$):

```python
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):

```bash
# 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](https://doi.org/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](https://doi.org/10.3390/s25113572)

- **Pupil Labs Neon Reference**:  
  Baumann, C., & Dierkes, K. (2023). *Neon accuracy test report*. Pupil Labs. [DOI: 10.5281/zenodo.10420388](https://doi.org/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](https://doi.org/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](https://doi.org/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](https://doi.org/10.1016/j.csbj.2025.01.012)

```bibtex
@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](LICENSE) file for details.

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