[ENH] total aoi dwell time - eye tracking data

Describe the new feature or enhancement

Add functionality to compute total area-of-interest (AOI) dwell time from eye-tracking data.

AOI-based metrics, such as total dwell time, are commonly used to quantify total time gaze has been oriented toward specific regions and useful for user aiming for multi-subject statistical analyses.

Idea of workflow is linked here #13786

References:
Hessels, R. S., Kemner, C., van den Boomen, C., & Hooge, I. T. (2016). The area-of-interest problem in eyetracking research: A noise-robust solution for face and sparse stimuli. Behavior research methods, 48(4), 1694–1712. https://doi.org/10.3758/s13428-015-0676-y

Rim, N. W., Choe, K. W., Scrivner, C., & Berman, M. G. (2021). Introducing Point-of-Interest as an alternative to Area-of-Interest for fixation duration analysis. PloS one, 16(5), e0250170. https://doi.org/10.1371/journal.pone.0250170

Describe your proposed implementation

perhaps as a standalone function within mne.preprocessing.eyetracking.

The function would take eye-tracking data, along with AOI definitions (such as bounding boxes or masks), and compute total dwell time per AOI over a specified time window. It would internally map gaze samples to AOIs and accumulate the total time spent within each region.

The output could be a dictionary or structured array mapping each AOI to its corresponding total dwell time (in seconds).

Inspired from workflow described here: https://mne.tools/stable/auto_examples/visualization/eyetracking_plot_heatmap.html

mne.preprocessing.eyetracking.interpolate_blinks(raw, interpolate_gaze=True)
raw.annotations.rename({"dvns": "natural"}) # more intuitive

epochs = mne.Epochs(raw, event_id=["natural"], tmin=0, tmax=20, baseline=None)

total_dwell = aoi_dwell_time(
epochs["natural"],
xrange = (250, 500),
yrange = (400, 800)
)

Describe possible alternatives

Users can compute AOI dwell time manually from gaze data, but this requires custom implementations. Another alternative would be to integrate this functionality into a higher-level eye-tracking object, but a standalone function may be simpler and more flexible.

Additional context

No response

Start by reading the eye-tracking entry point in mne.preprocessing.eyetracking and the visualization example at mne.tools/stable/auto_examples/visualization/eyetracking_plot_heatmap.html. Clarify the AOI input and output design, then define completion as computing total dwell time per AOI over a specified time window for the shown epochs workflow.