record video and system timestamps from Imaging Source USB3 cameras

Python GUI + scripts to record video sync'ed to behavior. Can record from multiple imaging source camera feeds while simultaneously grabbing system timestamps for each recorded frame. One can also record timestamps from one NIDAQ card signal to sync with a behavioral task (records timestamp on the rising edge of a TTL signal).

This software package was written by Gary Kane, post-doctoral fellow @ the Adaptive Motor Control Lab.

Prerequisite Software:

1. Windows 10
2. Anaconda
   • LSENS: install for all users.
3. Git

Required Hardware:

1. Imaging Source USB cameras
2. (Optional) NIDAQ card. Necessary to record timestamps from a behavioral task. Signal must be a TTL wired to digital input channel that is not dual-PFI (one that has hardware interrupt capabilities).

Instructions for Installation:

1. Install the latest driver for your camera. You can find the driver from The Imaging Source website: https://www.theimagingsource.com/products/. If you add new cameras to an existing system, make sure to update the driver!

2. Clone this repository. Open command prompt (type "cmd" into the search bar and hit enter), then type:
   
   git clone https://github.com/AdaptiveMotorControlLab/Camera_Control

3. Open the camera control directory, right-click 'install1.bat' and select 'Run as administrator'
   
   This script will install imaging source libraries, ffmpeg for command prompt, and create a new conda environment 'camera36'. Upon completion, the window will close suddenly.

4. Download and install IC Capture from imaging source: https://www.theimagingsource.com/support/downloads-for-windows/end-user-software/iccapture/. Launch it with your camera plugged in. Go to Device/Properties/Exposure and untoggle all 'auto' parameters. Otherwise the camera exposure won't be adjustable from the GUI.

5. Run 'install2.bat'.
   
   This script will finish setting up the conda environment and create a desktop shortcut to open the GUI.

6. Edit the 'write_camera_details.py' script according to your system's camera configuration. A template is provided (write_camera_details_TEMPLATE.py), please do not edit the template. The 'write_camera_details.py' script will write a dictionary to the file 'camera_details.json' containing the following fields:

   • a dictionary for each imaging source camera with the fields:

     • name = camera name

     • crop = cropping parameters

     • rotate = rotation angle of image

     • exposure = exposure in ms; can edit this in the GUI

     • output_dir = default directory to save videos; can edit this in the GUI

     • Example:

       cam_0 = {'name' : 'Cog Rig',
               'crop' : {'top' : 150, 'left' : 225, 'height' : 250, 'width' : 300},
               'rotate' : 0,
               'exposure' : .003,
               'output_dir' : 'C:/Users/user1/Desktop/video'}
       

   • subjects = a list of experimental subjects to select. Can be manually entered in GUI

   • labview = a list of labview channels to select, e.g. ['Dev1/port0/line0'] (optional). Can be manually entered in GUI
     
     

LSENS: The template to follow is write_camera_details.py. This file will also ask that you configure a device state for each camera object listed above. These states will be saved and loaded upon camera initialization. This requires that you now which of cam_0/cam_1 corresponds to which view, if your configuration parameters are view-dependent (e.g. FPS). WIP

To Run the Program:

Double click the cameraGUI.bat file on the Desktop or open command prompt, navigate to the camera_control directory, and run: python camera_control_GUI.py

1. Select the number of cameras to record from
2. Select and initialize each cameras
3. Select subject, frame rate and output directory, then click 'Set Up Video'
   • Will default to the output directory from 'camera_details.json'
   • Drop down menus for subject and output directory are populated via 'camera_details.json'
4. To start recording, click the On button. Recording can be turned Off/On multiple times -- frames, system timestamps, and timestamps from the nidaq card will be stored only when 'Record' is set to 'On'.
5. Once finished recording, click 'Save Video', 'Compress & Save Video', or 'Delete Video'
   • 'Save Video' saves an .avi file using the DIVX codec to 'output_dir/CameraName_Subject_Date.avi' and timestamp files to 'output_dir/TIMESTAMPS_CameraName_Subject_Date.npy' and (if applicable) 'output_dir/LABVIEW_Subject_Date.npy'. There will be one timestamps file per camera, but only one labview timestamp file per session.
   • 'Compress & Save Video' saves as above, but also saves an .mp4 file using ffmpeg compression to 'output_dir/CameraName_Subject_Date.mp4'
   • 'Delete Video' will not save any videos of timestamp files. Preliminary video files will be deleted.
6. To record more videos, return to step iii.

LICENSE:

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. Please see here for more information.

Citation:

If you find this software useful for your research, please cite: