Aligning the two cameras

Note

If you are not doing muscle imaging, you can omit this step.

The align-cameras command-line tool helps align (i) the field of view (FOV) of the behavior camera, (ii) the FOV of the muscle camera, and (iii) the spot size of the blue excitation light. This program is written in C++ and it is implemented in recorder/src/alignCameras/alignCameras_main.cpp and alignCameras.hpp.

IR illumination is achieved by a large ring light mechanically coupled to the behavior camera, so it doesn't have to be explicitly aligned.

Additionally, the spot size of the blue excitation light needs to be adjusted to balance the following trade-off:

1. The spot should be large enough so that the part covering the fly is as homogenous as possible in light intensity.
2. The spot should be as small as possible to reduce overheating, which can visibly impact behavior. If the light is more focused, we can reduce the power.

In this alignment procedure, we will align the two cameras and the light as well as adjust the spot size of the light. The overall principle of the alignment procedure is to stream behavior images using the FOV specified "recorder_config" file (the user specifies the FOV size and Spotlight automatically takes the center portion of the sensor). By contrast, for the muscle camera, we will stream the full image capture by the entire sensor. Then, the user will click on a point on the muscle image that coincides with the center of the behavior image. The FOV on the muscle camera sensor will be defined based on the position of this point. This helps the user align the two FOVs with out having to physically aligning the cameras perfectly. To help define the center point, we will place a fixed bullseye on top of the physical arena, and move the motion stages so that the behavior camera is centered at the bullseye.

The bullseye pattern is located at calibration_target_A4paper.svg.

The align-cameras command-line tool is implemented for this procedure. The arguments accepted by this program can be displayed by running ./align-cameras --help:

$ ./align-cameras --help
Usage: ./align-cameras [OPTIONS]
Options:
  -h, --help                 Display this help message
  -p, --profile-dir PATH     Path to profile directory (default: ~/Spotlight/default/)
  -v, --verbose              Enable verbose output (debug level)
  --verbosity LEVEL          Set verbosity level (trace, debug, info, warn, error, critical, off)

Mainly, the user has to specify the profile using the --profile-dir (or -p for short) argument. For example, you might run:

$ ./align-cameras -p ~/Spotlight/sibo

Then, two windows will pop up, displaying images from each of the cameras. You can always press the ESC key on the keyboard to quit with saving anything.

Once the program is running, perform the following steps:

1. Take the piece of paper with the bullseye printed on it and place it on top of the arena. Pay attention to the orientation: The corner with an arrow should be aligned with the corner marked with an arrow on the arena holder. Then, place the acrylic "paper weight" plate on top of the piece of paper to keep the paper pressed down.
2. Using the knobs on the Zaber X-MCC motion stage controller, move the stages so that the bullseye is centered on the behavior camera. Turning the knobs clockwise or counterclockwise will move the stages toward one direction or the other. The stages will move faster the more you turn the knobs. You can press the knobs to stop the movement.
3. Physically adjust the blue LED, its distance from the sample, and possibly the lenses in front of it so that (i) the light is centered at the bullseye (ii) the spot size is appropriate. Looking at the muscle camera view, you can use the radius markers on the bullseye to reproducibly set the spot size.
4. Physically adjust the muscle camera so it is roughly aligned to the bullseye. It does not have to be very precise.
5. If the stage or the behavior camera has moved in the process, move the stages again to re-align the behavior camera to the bullseye.
6. Click on the center of the bullseye on the muscle camera window. The clicked point will be shown in red. The nearest feasible FOV will be draw in blue, with the FOV center marked by a dot. Notably, the blue dot and the red dot will generally not coincide perfectly. This is because the PCO camera requires the FOV boundaries to be multiples of 32 pixels (horizontally) and 8 pixels (vertically).
7. Make sure the entire blue rectangle is within the boundary of the displayed image. If it is not, physically adjust the muscle camera position again.
8. Press the RETURN key on the keyboard (not the ENTER key on the number pad) to save the muscle FOV configuration.
9. Check that a "muscle_camera_roi.yaml" file has been saved under the profile directory specified in the command-line. This file contains the boundaries of the muscle camera FOV and will be used by the run-calibration-scan and run-spotlight programs.