tobii_pytracker.analyze.FixationAnalyzer

class tobii_pytracker.analyze.FixationAnalyzer(output_folder: Path, method: Literal['dispersion', 'velocity'] = 'dispersion', dispersion_threshold: float = 50.0, min_duration: float = 0.1, velocity_threshold: float = 100.0)

Detects and visualizes gaze fixations from time-series gaze data.

The analyzer supports simple dispersion-based fixation detection and outputs per-fixation metrics (centroid, duration, dispersion, etc.). Always processes data per slide.

Parameters

output_folderPath

Directory where results or plots can be saved.

method{‘dispersion’, ‘velocity’}, optional

Fixation detection method. Default = ‘dispersion’.

dispersion_thresholdfloat, optional

Maximum visual angle (in pixels or units of your coordinate system) for gaze points to be considered within a fixation (used in ‘dispersion’ method). Default = 50.

min_durationfloat, optional

Minimum duration (in seconds) for a fixation to be valid. Default = 0.1.

velocity_thresholdfloat, optional

Maximum velocity (pixels/sec) to consider samples as belonging to a fixation when using the ‘velocity’ method. Default = 100.

__init__(output_folder: Path, method: Literal['dispersion', 'velocity'] = 'dispersion', dispersion_threshold: float = 50.0, min_duration: float = 0.1, velocity_threshold: float = 100.0)

Methods

__init__(output_folder[, method, ...])
analyze(background_data)	Detect fixations per slide.
plot_analysis(fixations, screenshot_path[, ...])	Overlay fixations on a slide image.

analyze(background_data: DataFrame) → DataFrame

Detect fixations per slide.

Parameters

background_datapd.DataFrame

Flattened gaze data with columns: [‘avg_gaze_x’, ‘avg_gaze_y’, ‘system_time’, ‘set_name’, ‘slide_index’]

Returns

pd.DataFrame

Fixations with columns: [‘set_name’, ‘slide_index’, ‘fix_start’, ‘fix_end’, ‘duration’,

‘x_mean’, ‘y_mean’, ‘dispersion’]

plot_analysis(fixations: DataFrame, screenshot_path: Path, set_name: str | None = None, slide_index: int | None = None, title: str | None = None, flip_y: bool = True, color: str = 'yellow', alpha: float = 0.7, size_scale: float = 2000.0, show: bool = True, save_path: Path | None = None)

Overlay fixations on a slide image.

Parameters

fixationspd.DataFrame

Output of analyze(). Can contain all sets/slides.

screenshot_pathPath

Path to the slide screenshot.

set_namestr, optional

Filter by subject.

slide_indexint, optional

Filter by slide.

titlestr, optional

Custom plot title.

flip_ybool, optional

Whether to invert Y (origin top-left).

colorstr, optional

Fixation circle color.

alphafloat, optional

Fixation transparency.

size_scalefloat, optional

Scales fixation size according to duration.

show : bool, optional save_path : Path, optional