Skip to content

Behavioural video filming

Jump to bottom
Axel edited this page May 14, 2025 · 4 revisions

Behavioural video filming

This page describes how to setup video filming for behaviour and how to use the system when doing behavioural sessions.

Hardware and equipment 🎥 💡 🖥️

We use triggerable infrared The Imaging Source USB cameras, in particular the DMK 37BUX273. Other models with comparable specifications could also work. These cameras are compact, light, easy to use.

You also need IR LEDs e.g.:

We usually do video data acquisition on a separate PCs:

  • recent computer
  • USB 3.1 ports at the back of the computer
  • one or several SSDs

We acquire on dedicated SSD drives (that are not the system C:\ drive):

  • sufficient SSD storage e.g. 4Tb or higher to hold all of your day's data
  • SATA III or better (NVMe M.2)
  • SSD write speed higher than the data stream requirements for a specific combination of: number of cameras X color format #bits X image size X frame rate, etc.
  • several SSDs can be used in parallel

Note: ⚠️ Sometimes we lose frames, i.e. some frames are not saved in the .avi file even though a trigger was sent and an exposure time was received, suggesting that either a component of the system cannot keep up. This seems to be PC-dependent: some PCs work, others don't. The specific reasons for that are still unknown. The detailed PC specifications may matter for this. Lowering the frame rate showed that frame loss can be avoided altogether.

Setup

  • Setup 2 cameras on your setup: for side and top views of the mouse face. However, this depends on your specific project. 😄
  • Install IC Capture on the PC.
  • Install the drivers for your camera models (here for DMK 37BUX273) under the camera's webpage -> Downloads -> Device Drivers.
  • Launch IC Capture.
  • File -> New -> Select Device
  • Set up our video acquisition settings:
    • Color format: Y800 (640x480)
    • Binning: 2x (improves SNR luminance)
    • Input: NA
    • FPS: 200.00
    • Format: AVI
    • Codec: Y800 (uncompressed)
    • Video file: choose target SSD directory, MouseName_<view> as filename prefix, without index, with time stamp (either option), where view is {side, top} or {sideview, topview}
    • Exposure: 1/500sec (2ms)
    • Leave all other brightness/sharpness/etc. parameters untouched -> adjust brightness conditions with collimation/LED drivers directly
  • Repeat for other cameras: File -> New -> Select Device
  • Save configuration on desktop: File -> Save Configuration

You can then either load the saved .iccf configuration file from Desktop or leave the software open if you are continuously recording videos.

Usage

On the video filming PC:

  • Open configuration file. You should see the 2 camera views.
  • Right Click -> Live. Adjust camera views and ligthning before session start.
  • For each camera: Right Click -> Properties
    • Turn all Auto features OFF
    • In Special:
      • Trigger Enabled, Polarity ON, Exposure Mode on Trigger Width, Strobe Enabled, Mode on Exposure, Polarity ON, Delay 0.
  • For each camera: Record Video File -> Specify name, making sure format, codec, SSD device is OK. Number of frames should be 0.
  • Before starting the session, click Record (🔴). Recorded duration should increased but not the number of frames (as triggers are sent by the behaviour control).

Note: If you realize during the session that some lightning conditions are not optimal, you can modify the Gain. This will improve luminosity, however at the expense of increased noise.

On the behaviour control PC:

  • At this stage your behaviour GUI should be already set up.
  • At this stage, you should have already checked that the video FOVs, image quality, brightness etc. are good and that you can film all relevant bodyparts.
  • Click Camera ON. Make sure the frame rate and exposure time are the same as on IC Capture. The start delay is just for convenience. Leave default of 3secs.
  • Start session when you're ready. After the start delay, you should see incoming strobe TTLs.

At the end of the session:

  • After stopping the behaviour session, click Stop (⬛) for both videos on IC Capture.
  • ⚠️ The two files should have the same number of frames. If not, this may be because of loss of saved frames in one/both cameras. Check this using the continuous processing functions of the NWB_converter.

At the end of each day, transfer your video files on the server in the appropriate folder.

Note: you cannot transfer and acquire files at the same time. This will likely result in frame loss. You should start each recording day with a fresh empty drive, then transfer all your videos once your done.

Troubleshooting:

Fixing a corrupt AVI file

Scenario: you incorrectly stopped the video acquisition resulting in an AVI video file that you cannot read or open. Various AVI file fixing software tell you that your AVI file is not an AVI file. This means that probably the AVI header of the video is wrong or missing.

Requirements

  • Your broken video file: broken.avi that you have first made a copy of to avoid further damage! 😉
  • A working AVI file (same codec/resolution/etc.): good.avi
  • FFmpeg installed

Step-by-Step

  • Step 1: Extract a clean AVI header

    • Run: 
      ffmpeg -i good.avi -frames:v 0 -an -f avi header.avi
    • This creates a minimal AVI file containing only the header metadata, no video or audio frames.

  • Step 2: Merge the clean header with the broken video

    • On Windows: 
      copy /b header.avi + broken.avi merged.avi
    • On macOS/Linux: 
      cat header.avi broken.avi > merged.avi

  • Step 3: Rebuild the AVI index

    • Run: 
      ffmpeg -i merged.avi -c copy fixed.avi
    • This reconstructs timing, fixes seeking, and generates a clean output.

  • Step 4: Test and verify

    • Open fixed.avi in VLC Media Player: does it read now? The video may start with some black "frames", that are not actually frames.
    • With ffmpeg's ffprobe to check the number of frames (and compare with the number of TTL frame pulses. from your binary file): 
      ffprobe -v error -count_frames -select_streams v:0 -show_entries stream=nb_read_frames -of default=nokey=1:noprint_wrappers=1 fixed.avi

Notes:

  • Only use a good.avi file that has matching encoding (resolution, codec, etc.)
  • Avoid copying more than the header or you’ll unintentionally add extra frames
  • This process doesn’t recover damaged frames — only restores structure so the video becomes playable/editable
  • This does not guarantee that you'll be able to use the video for downstream processes: DeepLabCut, NWB_converter... you'll have to try it!

Clone this wiki locally