Add video acquisition support for pupillometry / eye tracking

[tabedzki]

Summary

Port the camera-based video acquisition feature from the internal ViRMEn fork into PureVirmen, so that external contributors can record synchronized eye/pupil video alongside behavioral sessions without any DataJoint or database dependencies.

Motivation

The internal BrainCOGS ViRMEn fork includes FLIR camera recording with behavioral sync timestamps, used for pupillometry and posture tracking analysis. PureVirmen currently lacks this. Bringing it in as a self-contained, opt-in feature makes PureVirmen useful for labs that want video acquisition without adopting the full U19 pipeline.

Proposed changes

Engine (bin/engine/virmenEngine.m)

• Add vr.preTic = tic before initialization() — provides a stable time reference for the whole session
• Add vr.timeElapsedFirstTrial = toc(vr.preTic) just before the main loop — captures initialization duration for post-hoc sync

New directory: sensors/camera/

File	Description
configureSingleCamera.m	Configure FLIR camera via GenTL (Image Acquisition Toolbox). Sets frame rate, exposure, gain; creates VideoWriter (Motion JPEG 2000) disk logger.
startVideoAcquisition.m	vr = startVideoAcquisition(vr, subject_name, session_number, logger) — configures camera, builds filename, captures vr.timeElapsedVideoStart = toc(vr.preTic), starts acquisition. logger is optional (default []).
stopVideoAcquisition.m	vr = stopVideoAcquisition(vr, logger) — stops and releases camera. logger is optional.
setupVideoFile.m	Builds output path using convention userid/subject/YYYYMMDD_g#/subject_YYYYMMDD_g#.ext (compatible with U19 pipeline paths).
checkCameraRigParameters.m	Validates required RigParameters properties before camera init; throws descriptive error on missing fields.
syncBehaviorVideo.m	Post-hoc alignment utility: maps video frames to behavioral iterations using log.timeElapsedVideoStart and log.iterationTimes. DataJoint-free equivalent of the U19 sync script.

Config (extras/RigParameters.m.example)

Add commented video-acquisition block:

hasCamera                           = false
video_parent_path                   = 'D:\Videos'
video_ext                           = '.mj2'
video_acquisition_rate              = 30
video_exposure_time_in_microseconds = 5000   % optional
video_gain                          = 0

Requirements

• MATLAB Image Acquisition Toolbox
• FLIR Spinnaker GenTL support (install via MATLAB Add-On Explorer)
• FLIR camera connected as device index 1

Out of scope

• DataJoint / database integration
• GPU-accelerated encoding (tracked separately)
• macOS / Linux (PureVirmen MEX files are Windows-only)

Usage

% initialization code:
if isprop(RigParameters, 'hasCamera') && RigParameters.hasCamera
    vr = startVideoAcquisition(vr, 'mouse01', 1);
end

% termination code:
if isfield(vr, 'v')
    vr = stopVideoAcquisition(vr);
end
% save vr.videoAcqInfo, vr.timeElapsedVideoStart, vr.timeElapsedFirstTrial
% alongside behavioral data; use syncBehaviorVideo() for post-hoc alignment