RectangularROI#

class pypillometry.RectangularROI(corner1, corner2, name=None, setup=None)[source]#

Bases: ROI

Rectangular Region of Interest defined by two corners.

Coordinates are in pixels (origin at upper-left, y increases downward) by default. Use from_mm() or from_degrees() factory methods for alternative coordinate systems.

Parameters:

  • corner1 (Tuple[float, float]) – (x, y) coordinates of the first corner in pixels

  • corner2 (Tuple[float, float]) – (x, y) coordinates of the opposite corner in pixels (the order of the corners does not matter)

  • name (str) – Name of the ROI

  • setup (Optional[ExperimentalSetup]) – Experimental setup for coordinate conversions

Methods

contains

Test if coordinates are within the rectangle (boundary included).

from_degrees

Create rectangular ROI from visual angle coordinates.

from_mm

Create rectangular ROI from mm coordinates (origin at screen center).

plot

Plot the rectangular ROI.

Details

classmethod from_degrees(corner1, corner2, setup, name=None)[source]#

Create rectangular ROI from visual angle coordinates.

Parameters:

  • corner1 (Tuple[Union[float, str], Union[float, str]]) – (x, y) first corner in visual angle from screen center. Positive x = right, positive y = up. Each coordinate can be: - float: degrees - str: with units, e.g., “-5 deg”, “-0.087 rad” - with a unit, e.g., 5 * u.deg

  • corner2 (Tuple[Union[float, str], Union[float, str]]) – (x, y) second corner in visual angle from screen center. Positive x = right, positive y = up. Each coordinate can be: - float: degrees - str: with units, e.g., “5 deg”, “0.087 rad” - with a unit, e.g., 5 * u.deg

  • setup (ExperimentalSetup) – Experimental setup with screen geometry and eye distance (screen_resolution, physical_screen_size, and eye_to_screen_center must be set)

  • name (str) – Name of the ROI

Return type:

RectangularROI

Returns:

ROI with coordinates converted to pixels

Examples

>>> from pypillometry import ExperimentalSetup, RectangularROI
>>> setup = ExperimentalSetup(
...     screen_resolution=(1920, 1080),
...     physical_screen_size=("52 cm", "29 cm"),
...     eye_to_screen_center="60 cm"
... )
>>> # Rectangle from (-5, -2.5) deg to (5, 2.5) deg
>>> roi = RectangularROI.from_degrees(
...     corner1=("-5 deg", "-2.5 deg"), corner2=("5 deg", "2.5 deg"), setup=setup
... )
classmethod from_mm(corner1_mm, corner2_mm, setup, name=None)[source]#

Create rectangular ROI from mm coordinates (origin at screen center).

Parameters:

  • corner1_mm (Tuple[float, float]) – (x, y) first corner in mm relative to screen center. Positive x = right, positive y = up.

  • corner2_mm (Tuple[float, float]) – (x, y) second corner in mm relative to screen center. Positive x = right, positive y = up.

  • setup (ExperimentalSetup) – Experimental setup with screen geometry (screen_resolution and physical_screen_size must be set)

  • name (str) – Name of the ROI

Return type:

RectangularROI

Returns:

ROI with coordinates converted to pixels

Examples

>>> from pypillometry import ExperimentalSetup, RectangularROI
>>> setup = ExperimentalSetup(
...     screen_resolution=(1920, 1080),
...     physical_screen_size=("52 cm", "29 cm")
... )
>>> # Rectangle from (-50, -25) mm to (50, 25) mm (centered, 100x50 mm)
>>> roi = RectangularROI.from_mm(
...     corner1_mm=(-50, -25), corner2_mm=(50, 25), setup=setup
... )
contains(coords)[source]#

Test if coordinates are within the rectangle (boundary included).

Parameters:

coords (Union[Tuple[float, float], ndarray]) – a single (x, y) point or an array of shape (n, 2) with one point per row (in pixels)

Return type:

Union[bool, ndarray]

Returns:

for a single point, whether it is inside the ROI; for an array, a boolean array of length n

plot(ax=None, **kwargs)[source]#

Plot the rectangular ROI.

Parameters:

  • ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, the current axes will be used.

  • **kwargs (dict) – Additional keyword arguments passed to patches.Rectangle. Common options include: - facecolor: color of the rectangle fill - edgecolor: color of the rectangle edge - alpha: transparency - fill: whether to fill the rectangle - label: label for the legend

Return type:

matplotlib.axes.Axes

Returns:

the axes of the plot (the rectangle is ax.patches[-1])

Examples

Draw two regions on a gaze heatmap:

>>> import pypillometry as pp
>>> from pypillometry import u
>>> import matplotlib.pyplot as plt
>>> d = pp.get_example_data("rlmw_002_short")
>>> left = pp.CircularROI((280, 512), radius=150, name="left stimulus")
>>> right = pp.RectangularROI((850, 350), (1150, 650), name="right stimulus")
>>> fig = d.plot.plot_heatmap(eyes="left")
>>> ax = fig.axes[0]  # the heatmap (axes[1] is the colorbar)
>>> ax = left.plot(ax=ax, edgecolor="white", linewidth=2, alpha=1)
>>> ax = right.plot(ax=ax, edgecolor="white", linewidth=2, alpha=1)
../../_images/pypillometry-RectangularROI-1.png

d.plot.plot_heatmap() and d.plot.plot_scanpath() can also draw them (rois=[left, right]).