retinotopic_mapping.MonitorSetup

Used to store the display monitor and particular geometry used within a given experimental setup. The Monitor class holds references to the sizing of the monitor that is used to display stimulus routines and contains the necessary geometrical description of where the subject’s eye is placed with respect to the display monitor. The Indicator class, on the other hand, is generally used in order to gain precise temporal information of the stimuli display. Basically a indicator is just a small square shows up at one corner of the display screen. It changes color during visual stimuli display. By covering it with a photodiode with high temporal precision and syncing the photodiode signal into data acquisition system, the experimenter will get the ground truth of display timestamps. Ideally the flashes of an indicator will be synchronized with the onsets of stimuli.

The module will most definitely be used in conjunction with the DisplayStimulus and StimulusRoutines modules.

Monitor

class retinotopic_mapping.MonitorSetup.Monitor(resolution, dis, mon_width_cm, mon_height_cm, C2T_cm=None, C2A_cm=None, center_coordinates=(0.0, 60.0), visual_field='right', deg_coord_x=None, deg_coord_y=None, name='testMonitor', gamma=None, gamma_grid=None, luminance=None, downsample_rate=10, refresh_rate=60.0)

monitor object created by Jun, has the method “remap” to generate the spherical corrected coordinates in degrees

This object contains the relevant data for the monitor used within a given experimental setup. When initialized, the rectangular coordinates of the pixels on the monitor are computed and stored as lin_coord_x, lin_coord_y. The rectangular coordinates are then transformed and warped by calling the remap method to populate the deg_coord_x and deg_coord_y attributes.

Parameters:

resolution : tuple

value of the monitor resolution

dis : float

distance from eyeball to monitor (in cm)

mon_width_cm : float

width of monitor (in cm)

mon_height_cm : float

height of monitor (in cm)

C2T_cm : float

distance from gaze center to monitor top

C2A_cm : float

distance from gaze center to anterior edge of the monitor

center_coordinates : tuple of two floats

(altitude, azimuth), in degrees. the coordinates of the projecting point from the eye ball to the monitor. This allows to place the display monitor in any arbitrary position.

visual_field : str from {‘right’,’left’}, optional

the eye that is facing the monitor, defaults to ‘right’

deg_coord_x : ndarray, optional

array of warped x pixel coordinates, defaults to None

deg_coord_y : ndarray, optional

array of warped y pixel coordinates, defaults to None

name : str, optional

name of the monitor, defaults to testMonitor

gamma : optional

for gamma correction, defaults to None

gamma_grid : optional

for gamme correction, defaults to None

luminance : optional

monitor luminance, defaults to None

downsample_rate : int, optional

downsample rate of monitor pixels, defaults to 10

refresh_rate : float, optional

the refresh rate of the monitor in Hz, defaults to 60

Methods

generate_lookup_table() generate lookup talbe between degree corrdinates and linear corrdinates return two matrix: lookupI: i index in linear matrix to this pixel after warping lookupJ: j index in linear matrix to this pixel after warping
plot_map()
remap() warp the linear pixel coordinates to a spherical corrected representation.
set_downsample_rate(downsample_rate)
set_gamma(gamma, gamma_grid)
set_luminance(luminance)
warp_images(imgs, center_coor[, …]) warp a image stack into visual degree coordinate system
generate_lookup_table()

generate lookup talbe between degree corrdinates and linear corrdinates return two matrix: lookupI: i index in linear matrix to this pixel after warping lookupJ: j index in linear matrix to this pixel after warping

remap()

warp the linear pixel coordinates to a spherical corrected representation.

Function is called when the monitor object is initialized and populate the deg_coord_x and deg_coord_y attributes.

warp_images(imgs, center_coor, deg_per_pixel=0.1, is_luminance_correction=True)

warp a image stack into visual degree coordinate system

Parameters:

imgs : ndarray

should be 2d or 3d, if 3d, axis will be considered as frame x rows x width

center_coor : list or tuple of two floats

the visual degree coordinates of the center of the image (altitude, azimuth)

deg_per_pixel : float or list/tuple of two floats

size of original pixel in visual degrees, (altitude, azimuth), if float, assume sizes in both dimension are the same

is_luminance_correction : bool

if True, wrapped images will have mean intensity equal 0, and values will be scaled up to reach minimum equal -1. or maximum equal 1.

Returns:

imgs_wrapped : 3d array, np.float32

wrapped images, each frame should have exact same size of down sampled monitor resolution. the region on the monitor not covered by the image will have value of np.nan. value range [-1., 1.]

coord_alt_wrapped : 2d array, np.float32

the altitude coordinates of all pixels in the wrapped images in visual degrees. should have the same shape as each frame in ‘imgs_wrapped’.

coord_azi_wrapped : 2d array, np.float32

the azimuth coordinates of all pixels in the wrapped images in visual degrees. should have the same shape as each frame in ‘imgs_wrapped’.

imgs_dewrapped : 3d array, dtype same as imgs

unwrapped images, same dimension as input image stack. the region of original image that was not got displayed (outside of the monitor) will have value of np.nan. value range [-1., 1.]

coord_alt_dewrapped : 2d array, np.float32

the altitude coordinates of all pixels in the dewrapped images in visual degrees. should have the same shape as each frame in ‘imgs_dewrapped’.

coord_azi_dewrapped : 2d array, np.float32

the azimuth coordinates of all pixels in the dewrapped images in visual degrees. should have the same shape as each frame in ‘imgs_dewrapped’.

Indicator

class retinotopic_mapping.MonitorSetup.Indicator(monitor, width_cm=3.0, height_cm=3.0, position='northeast', is_sync=True, freq=2.0)

flashing indicator for photodiode

Parameters:

monitor : monitor object

The monitor used within the experimental setup

width_cm : float, optional

width of the size of the indicator in cm, defaults to 3.

height_cm : float, optional

height of the size of the indicator in cm, defaults to 3.

position : str from {‘northeast’,’northwest’,’southwest’,’southeast’}

the placement of the indicator, defaults to ‘northeast’

is_sync : bool, optional

determines whether the indicator is synchronized with the stimulus, defaults to True.

freq : float, optional

frequency of photodiode, defaults to 2.

Methods

get_center()
get_frames() if not synchronized with stimulation, get frame numbers of each update of indicator
get_size_pixel()
get_frames()

if not synchronized with stimulation, get frame numbers of each update of indicator