Hardware
Many of the challenges in achieving robust tracking over long time scales that would be very difficult to solve by adjusting parameters in the tracking can be entirely avoided by constructing a dedicated space for tracking. Although a tracking box is not strictly required, a box of the general configuration in the sample schematic below may serve as a reference for good tracking conditions before attempting to optimize other hardware or software parameters. We recommend tracking setups with the following features:
- opaque walls to block external light
- overhead camera mount
- bright, diffuse illumination source
Sample tracking platform constructed from aluminum
rails and acrylic plastic. Backlit behavioral arenas and opaque walls
enhance ROI contrast and reduce imaging
noise.
In addition to walls, use clear sanded plastic, diffuser film, or paper either between the illumination source and behavioral arenas or on the floor of the arenas themselves to diffuse the light source. Having a sanded or matte finish on all surfaces inside of the tracking box can also help reduce reflections and glares inside the box.
The choice of behavioral arenas depends on which of MARGO's two ROI detect modes are used:
Automatic detection mode works by finding bright regions of the image that are all roughly the same size. This means that ideal behavioral arenas used for automatic ROI detection are backlit, transparent areas separated by opaque areas in between.
Sample arenas for automatic ROI detection. Arena floors are constructed of sanded clear acrylic, separated by black acrylic.
Grid detection mode works only on the assumption that ROIs will be arranged in regularly spaced rows and columns. The user is prompted to draw and adjust the position of one or more grids of any arbitrary dimensions to specify ROIs. This means that behavioral arenas can be anything with stereotyped dimensions. Wellplates of any dimensions make ideal behavioral arenas for grid mode detection.
Sample arenas for grid detection.
Quality illumination is a prerequisite for high-quality tracking. An ideal light source for tracking will have the following features:
- As bright as possible without saturating camera
- Uniformly bright across the imaging plane
- Uniformly bright over time
We perform all of our tracking with infrared light. Using an infrared light source and longpass filter on the camera has the dual benefit of reducing sensitivity of the tracking to perturbation by most external light sources and allowing for independent control of visible light sources to deliver stimuli not visible to the camera. LCD backlight panels and edge-lit two channel light panels are examples of good illumination sources.
The appropriate configuration for your camera will largely depend on your particular experiment. Camera customization features are accessible under the "Hardware" menu bar. But before configuring the camera in MARGO, ensure that the camera and camera lens are properly setup for tracking. The following are good guidelines for configuring your camera:
-
Exposure adjusted so that ROIs are near saturation
-
Lens focused on ROIs
-
Camera rigidly fixed to a camera mount
Camera support in MARGO is built on MATLAB's Image Acquisition Toolbox. Before a camera can be detected by MARGO, the associated MATLAB camera adaptors must first be installed. The appropriate adaptor to install will depend on the camera manufucturer. See MATLAB's tutorial for complete instructions on installing MATLAB camera support packages.
Once the camera adaptors are installed, a list of available cameras and camera modes should auto-populate upon launching MARGO. The list available cameras can be refreshed under the hardware menubar.
MARGO will automatically detect available camera modes for operating at different pixel resolutions and color bit depths. The tracking is designed to work with 8-bit color depth because most tracking operations are performed on binary images. It is also strongly recommended that monochromatic cameras are used. By default, MARGO only tracks the green color channel of RGB images.
Camera properties such as (e.g. exposure, shutter) can be adjusted under Hardware > Camera > camera settings. Because the configurable settings are specific to each device, the properties that can be adjusted here will depend on your camera. Many cameras have modes to automatically adjust the camera exposure time, shutter speed, frame rate, gain or focus in real time. These modes are also often enabled by default, which may be good for many applications but is highly problematic for tracking. Constantly fluctuating images will introduce a lot of noise into the tracking due to the sensitivity of difference image to even minor changes from frame to frames.
To preview camera settings changes, click Start preview to initiate a preview display and open the camera settings window. Keep in mind that the available settings and names of each property will be dependent on the camera. From the settings menu:
-
Ensure that any automatic adjustment of camera settings (e.g. auto-exposure) is disabled
-
Adjust exposure and shutter speeds until the preview is just below saturation
-
Set max frame rate (target acquisition rate can be set lower in tracking parameters)
-
Close window to save settings
Camera lens distortion can be corrected by importing cameraParameters objects. See camera calibration for more details.
Programmable input/ouput control boards such as Arduino microcontrollers can be detected and interfaced with through MARGO. The GUI features tools to interface with a dedicated COM device for illumination control and an auxillary COM device for control of other peripheral electronics.
We use a customly programmed Teensy microcontrollers to control a dual-color LED illumination board with independently controllable visible and infrared light. To select and write values to an illumination control board.
- Select a COM port from the lighting control panel drop-down menu
- Edit the white and/or infrared intensity (0-100)
- Press Enter to send the new values to the control board
When the intensity values are changed, MARGO will do the following under the hood:
- Convert the intensity value (0-100) to an 8-bit unsigned integer value in the range 0-255
- Transmit two bytes to the selected COM port:
- new intensity value
- integer value denoting either the white (9) or infrared (10) channel
Therefore, users must program their device with script capable of parsing these bytes and on the control side. Some sample C code is provided below using analogWrite from the Arduino library to adjust light intensity via pulse-width modulation.
// initialize placeholder to store bytes read from serial port
byte readBuf[2];
void setup() {
// open serial port
Serial.begin(9600);
// configure infrared/white pins as digital output
pinMode(10,OUTPUT);
pinMode(9,OUTPUT);
// initialize value on pins to something intermediate
analogWrite(10,40);
analogWrite(9,40);
}
void loop() {
// while 2 or more bytes are available on serial port
while(Serial.available()>=2){
// read in first byte as intensity level, second byte as pin number
Serial.readBytes((char*)readBuf,2);
byte level=readBuf[0];
byte pin=readBuf[1];
// write PWM intensity value to the pin
if(pin==9||pin==10){
analogWrite(pin,level);
}
}
}Custom hardware control can be implemented through auxillary COM devices. With a COM device connected, users can select an auxillary COM device under Hardware > aux COM. Once a device is selected, MARGO will initialize a MATLAB serial object on the selected port. The auxillary COM device serial object can be accessed in the ExperimentData object under:
expmt.hardware.COM.auxSee MARGO's custom experiment tutorial for a sample of implementation of hardware control with an auxillary COM device in MARGO. Writing control scripts for programmable microcontrollers is beyond the scope of this documentation, but the Arduino community offers many tutorials which can serve as a starting point for users that are new to using microcontrollers.