Using the recording application

Using the recording application

The run-spotlight program is the main GUI application for recording behavior and muscle imaging data.

Prerequisites

• Arena registration must be complete: ~/Spotlight/arenas/arena146/model/calibration_result.yaml must exist. See Calibration implementation and procedure.
• The pco-camera-server binary must be present (it is launched automatically by the recording application when muscle imaging is requested).

Starting the application

./run-spotlight -p ~/Spotlight/profiles/sibo_260514 -a ~/Spotlight/arenas/arena146

Both arguments are required:

• -p / --profile-dir: path to the profile directory containing recorder_config.yaml and muscle_camera_roi.yaml.
• -a / --arena: path to the arena directory containing metadata.yaml and model/calibration_result.yaml.

Optional:

• -v / --verbose: enable debug-level logging.
• --verbosity LEVEL: set log level explicitly (trace/debug/info/warn/error/critical/off).

Startup dialog

A configuration dialog appears before the main window opens. Here you set:

• Record both cameras or behavior only.
• Behavior FPS and exposure time.
• Sync ratio (muscle camera is triggered every N behavior frames).
• Muscle light-on time (µs).

Main window

The main window shows:

• Live behavior camera preview.
• Live muscle camera preview (if enabled).
• Motion stage position indicator (a dot moving within the arena outline).
• Tracking on/off toggle: when enabled, the stage continuously moves to keep the fly centered.
• Save directory selector.
• Start / Stop recording button.
• Experiment protocol string input (see The experiment protocol string).

Starting a recording

1. Set the save directory.
2. Optionally enter an experiment protocol string.
3. Click Start recording.

Upon start, the application saves the following metadata alongside the images:

• metadata/experiment_parameters.yaml
• metadata/recorder_config.yaml
• metadata/calibration_parameters_behavior.yaml (snapshot of the behavior-cam calibration)
• metadata/calibration_parameters_muscle.yaml (snapshot, if recording both cameras)
• metadata/dual_recording_timing.yaml

Data layout of a recording

<save_dir>/
├── behavior_images/         # behavior_frame_*.jpg  (packed pseudo-BGR JPEGs)
├── muscle_images/           # muscle_frame_*.tif    (16-bit LZW-compressed TIFF)
├── stage_position/
│   └── stage_position.csv
└── metadata/
    ├── experiment_parameters.yaml
    ├── recorder_config.yaml
    ├── calibration_parameters_behavior.yaml
    ├── calibration_parameters_muscle.yaml
    └── dual_recording_timing.yaml

Post-processing

After recording, run the offline postprocessing pipeline:

postprocess-recording --recording-dir <save_dir>/ [--with-muscle]

See Generating videos and consolidating metadata for details.