pyavs.get_fixated_objects

pyavs.get_fixated_objects(events_df: DataFrame, transformed_annotations_dir: str, verbose: bool = False, error_margin_pixels: int = 10, use_cocostuff: bool = True) → DataFrame[source]

Add object labels to fixation events using transformed AVS scene annotations.

This function uses pre-transformed annotations that match the processed scene format used in the AVS experiment, providing more accurate object detection. Includes error margin tolerance to account for eye tracker noise and calibration drift.

Parameters:

  • events_df (pd.DataFrame) – Eye tracking events dataframe

  • transformed_annotations_dir (str) – Path to directory containing transformed annotation JSON files

  • verbose (bool, optional) – Whether to print progress information (default: False)

  • error_margin_pixels (int, optional) – Search radius in pixels around fixation for nearest object (default: 10) This accounts for eye tracker noise and calibration drift.

  • use_cocostuff (bool, optional) – If True, use COCO-Stuff annotations (172 classes: 80 things + 91 stuff + 1 unlabeled). If False, use standard COCO annotations (80 thing classes only). Default is True (COCO-Stuff mode).

Returns:

Events dataframe with object_label and object_id columns added

Return type:

pd.DataFrame

Notes

COCO-Stuff mode (use_cocostuff=True) provides better coverage by including amorphous background regions like sky, grass, walls, water, etc. This typically increases fixation labeling coverage by 20-40% compared to COCO-only mode.