tobii_pytracker.analyze.HeatmapAnalyzer

class tobii_pytracker.analyze.HeatmapAnalyzer(output_folder: Path)

Generates gaze heatmaps and overlays them over screenshots.

This analyzer is independent of DataLoader — it operates directly on pandas DataFrames and image paths.

Parameters

output_folderPath

Directory where results or plots can be saved.

Notes

The DataFrame must contain:

  • ‘avg_gaze_x’ : x gaze coordinate (centered)

  • ‘avg_gaze_y’ : y gaze coordinate (centered)

  • ‘set_name’ : subject or participant ID

  • ‘slide_index’: slide identifier (int)

  • ‘input_data’ : image identifier (str)

__init__(output_folder: Path)

Methods

__init__(output_folder)

analyze(background_data[, per])

Perform gaze heatmap analysis by aggregating gaze data per group.

plot_analysis(background_data, screenshot_path)

Plot gaze heatmap overlayed over the given screenshot.
analyze(background_data: DataFrame, per: str = 'global') → DataFrame

Perform gaze heatmap analysis by aggregating gaze data per group.

Parameters

background_datapd.DataFrame

Combined gaze data from one or more subjects.

perstr, optional

Aggregation mode: - ‘global’ → compute statistics across all data (no grouping) - ‘set’ → compute per subject - ‘slide’ → compute per subject and slide

Returns

pd.DataFrame

DataFrame with mean gaze positions and counts per group.

plot_analysis(background_data: DataFrame, screenshot_path: Path, title: str | None = None, flip_y: bool = True, blur_sigma: float = 3.0, bins: int = 100, cmap: str = 'hot', alpha: float = 0.6, show: bool = True, save_path: Path | None = None)

Plot gaze heatmap overlayed over the given screenshot.

Parameters

background_datapd.DataFrame

The gaze data to visualize (usually a subset).

screenshot_pathPath

Path to the screenshot to overlay.

titlestr, optional

Custom title for the plot.

flip_ybool, optional

Whether to invert Y axis to align with screen coordinates.

blur_sigmafloat, optional

Gaussian smoothing factor for the heatmap.

binsint, optional

Number of bins for the 2D histogram.

cmapstr, optional

Colormap for the heatmap overlay.

alphafloat, optional

Transparency level for the heatmap overlay.

showbool, optional

Whether to display the figure interactively.

save_pathPath, optional

If provided, saves the figure to this location.