pymovements.gaze.transforms_numpy.pix2deg#

Convert pixel screen coordinates to degrees of visual angle.

Parameters:

arr (float | list[float] | list[list[float]] | np.ndarray) – Pixel coordinates to transform into degrees of visual angle
screen_px (float | list[float] | tuple[float, float] | np.ndarray) – Screen dimension in pixels
screen_cm (float | list[float] | tuple[float, float] | np.ndarray) – Screen dimension in centimeters
distance_cm (float) – Eye-to-screen distance in centimeters
origin (str) – Specifies the screen location of the origin of the pixel coordinate system. Valid values are: center, upper left.

Returns:

Coordinates in degrees of visual angle

Return type:

np.ndarray

Raises:

TypeError – If arr is None.
ValueError – If dimension screen_px or screen_cm don’t match dimension of arr. If screen_px or screen_cm or one of its elements is zero. If distance_cm is zero. If origin value is not supported.

Examples

>>> pix2deg(
...    arr=[(123.0, 865.0)],
...    screen_px=(1280, 1024),
...    screen_cm=(38.0, 30.0),
...    distance_cm=68.0,
...    origin='upper left',
... )
array([[-12.70732231, 8.65963972]])

>>> pix2deg(
...    arr=[(123.0, 865.0)],
...    screen_px=(1280, 1024),
...    screen_cm=(38.0, 30.0),
...    distance_cm=68.0,
...    origin='center',
... )
array([[ 3.07379946, 20.43909054]])

If the eye-movement of both eyes was recorded, the input array must contain first the x- and y-coordinates of one eye and then the x- and y-coordinates of the other eye as shown in the example below.

>>> x_left, y_left = 123.0, 865.0
>>> x_right, y_right = 183.0, 865.0
>>> arr = [(x_left, y_left, x_right, y_right)]
>>> pix2deg(
...    arr=arr,
...    screen_px=(1280, 1024),
...    screen_cm=(38.0, 30.0),
...    distance_cm=68.0,
...    origin='center',
... )
array([[ 3.07379946, 20.43909054,  4.56790364, 20.43909054]])