External Displays

Contents

1. Visual Stimulus Delivery
2. Projector Box
3. Display Registration
4. Using Registration Output

Overview

MARGO supports closed-loop targeting of visual stimuli to individual ROIs using an external display or projector. To get started displaying visual stimuli:

1. Download and install Psychtoolbox

2. Install projector above or flatscreen display below behavioral arenas

3. Map the display to the camera's field of view

4. Use mapping to convert camera coordinates to target display coordinates

Visual Stimulus Delivery with Psychtoolbox

Visual stimuli can be crafted and displayed with Psychtoolbox, a freely-available, MATLAB based software package for psychology and neuroscience research. Psychtoolbox is not included with MARGO and must be downloaded and installed separately. Psychtoolbox is an powerful and expansive package developed by Mario Kleiner. See one of the many online resources to learn how to generate and display stimuli.

Projector box

Mounting an overhead projector to the behavioral box allows targeting of visual stimuli to individual ROIs. The camera can be placed slightly off-center so the behavioral platform is visible to both the camera and projector. Equipping a long-pass filter to the camera allows tracking done in infrared without interference from the projector.

In order to accurately target objects within the camera's field of view with the projector, a mapping must be made between the pixel coordinates of both the camera and projector. MARGO creates this mapping by tracking a spot that is rastered through the projector's display. For this to work, the projection must be visible to the camera during registration but invisible to the camera during tracking. Mounting a long-pass filter on a swivel makes it easy to switch between the two without disturbing the camera.

Sample schematic of projector behavioral box. An external long-pass filter can be rotated in and out of the imaging path allowing the camera to switch between imaging only infrared light and imaging both infrared and visible light. The overhead projector targets individual ROIs underneath by projecting visual stimuli on a diffuser film on the floor of the behavioral arenas.

Display Registration

Any coordinate mapping between the camera and the projector will only be accurate for a particular configuration and positioning of both. If either is moved during or after registration, the mapping must be recalculated. Having a high contrast, non-reflective projection surface will greatly improve the ease of tracking the projector with the camera. A flat white sheet of paper or matte white painted surface works well.

To register an external display in MARGO:

1. Ensure that Psychtoolbox is installed by executing PsychtoolboxVersion in the MATLAB command window (MARGO support built on version 3)

2. Remove the infrared filter from the imaging path and start the camera preview

3. Place a high-contrast, white surface on the behavioral platform

4. Ensure no sources of illumination but the projector will be visible to the camera

5. Drag a window into the projector display (anything with high-contrast black and white text) and ensure the projector is in focus

6. Sync the camera exposure to the refresh rate of to the camera shutter. For example, for a 60Hz monitor, setting the shutter speed to 30Hz or 60Hz will ensure that the camera is synced to the refresh cycle of the display.

7. Select Hardware > projector > register projector

8. Select and confirm the projector screen and registration parameters when prompted to begin registration:

   • Raster grid mode - rasters a single dot across the display

     • Grid Step Size (pixels) sets the size of the steps between target locations of the rastered dot

     • Spot Radius sets the size of the rastered dot (pixels)

   • Random dot mode - displays a random array of dots and uses the coherent point drift algorithm register dot imaged by the camera to the known target

     • Spot Radius sets the size of the random dots (pixels)

9. Once registration is finished, the output mapping will be saved to file under: ../margo/hardware/projector_fit/

Using registration output

Examples of projector initialization and targeting can be found in the Optomotor, Slow Phototaxis, and Temporal Phototaxis example experiments.

To use the mapping in custom experiments, run the following command to initialize the external display:

% initialize the external display
expmt = initialize_projector(expmt, bg_color)

This initializes a Psychtoolbox window to the screen set under registration parameters with the background color specified by the RGB triplet, bg_color. Additionally, projector initialization stores the registration mapping and screen properties to the ExperimentData object. To convert from camera coordinates to projector coordinates, use the maping functions stored under expmt.hardware.projector :

% use display mappings to convert tracking coordinates from the
% camera to the same region of space in the display
projector_x = expmt.hardware.projector.Fx(cam_x, cam_y);
projector_y = expmt.hardware.projector.Fy(cam_x, cam_y);

Screen Properties

Name	Description
screenNumber	display number of the screen as assigned by Psychtoolbox
window	handle to the open Psychtoolbox window object
windowRect	pixel dimensions of the screen in the format [0, 0, width, height]
xCenter	x-coordinate of the screen center in pixels
yCenter	y-coordinate of the screen center in pixels
black/white	screen color index of black and white colors
vbl	high-precision vertical retrace time stamp for when the last stimulus was flipped to the screen
ifi	interframe interval of the screen (inverse of the refresh rate)
waitframes	number of frames to wait before flipping stimuli to the screen

Detailed use of MARGO and Psychtoolbox to deliver stimuli under closed-loop control is beyond the scope of this manual, but sample implementations are available in:

../margo/examples/Optomotor/run_optomotor.m
../margo/examples/Slow Phototaxis/run_slowphototaxis.m