CircularROI

class pypillometry.CircularROI(center, radius, name=None, setup=None)

Bases: ROI

Circular Region of Interest defined by center point and radius.

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:

• center (Tuple[float, float]) – (x, y) coordinates of the center point in pixels

• radius (float) – radius of the circle in pixels (must not be negative)

• name (str) – Name of the ROI

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

Raises:

ValueError – If radius is negative

Examples

>>> import numpy as np
>>> from pypillometry import CircularROI
>>> roi = CircularROI(center=(640, 512), radius=100, name="center")
>>> bool((650, 500) in roi)
True
>>> roi.contains(np.array([[640, 512], [900, 900]]))
array([ True, False])

Methods

contains	Test if coordinates are within the circle (boundary included).
from_degrees	Create circular ROI from visual angle coordinates.
from_mm	Create circular ROI from mm coordinates (origin at screen center).
plot	Plot the circular ROI.

Details

classmethod from_degrees(center, radius, setup, name=None)

Create circular ROI from visual angle coordinates.

Parameters:

• center (Tuple[Union[float, str], Union[float, str]]) – (x, y) center 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

• radius (Union[float, str]) – Radius in visual angle. Can be: - float: degrees - str: with units, e.g., “2 deg”, “0.035 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:

CircularROI

Returns:

ROI with coordinates converted to pixels

Examples

>>> from pypillometry import ExperimentalSetup, CircularROI
>>> setup = ExperimentalSetup(
...     screen_resolution=(1920, 1080),
...     physical_screen_size=("52 cm", "29 cm"),
...     eye_to_screen_center="60 cm"
... )
>>> roi = CircularROI.from_degrees(center=("5 deg", "2.5 deg"), radius="2 deg", setup=setup)
>>> roi = CircularROI.from_degrees(center=(5, 2.5), radius=2, setup=setup)  # degrees

classmethod from_mm(center_mm, radius_mm, setup, name=None)

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

Parameters:

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

• radius_mm (float) – Radius in mm

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

• name (str) – Name of the ROI

Return type:

CircularROI

Returns:

ROI with coordinates converted to pixels

Examples

>>> from pypillometry import ExperimentalSetup, CircularROI
>>> setup = ExperimentalSetup(
...     screen_resolution=(1920, 1080),
...     physical_screen_size=("52 cm", "29 cm")
... )
>>> roi = CircularROI.from_mm(center_mm=(50, 25), radius_mm=30, setup=setup)

contains(coords)

Test if coordinates are within the circle (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)

Plot the circular 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.Circle. Common options include: - facecolor: color of the circle fill - edgecolor: color of the circle edge - alpha: transparency - fill: whether to fill the circle - label: label for the legend

Return type:

matplotlib.axes.Axes

Returns:

the axes of the plot (the circle 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)

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