Blob tracking with SimBA

This notebook demonstrates how to run blob tracking using SimBA outside of its GUI interface, by directly executing Python code.

Make sure SimBA (version >=3.4.1) is installed in your Python environment:

pip install simba-uw-tf

Prepare the Configuration File

To run blob tracking in a notebook or by command line, you first need a .json configuration file containing both general settings and video-specific tracking parameters.

  • An example file is available here

  • Alternativly, when you run blob tracking in the GUI, as documented HERE or HERE, a file gets created in your chosen output folder called blob_definitions.pickle. You can also convert the saved .pickle file to .json followed by manual editing (see the last cell for an example code how to this) and use this file as input to the currently documented function.

Each video in the config file has its own block with settings like threshold, reference frame, kernel size, etc as below.

{
  "input_dir": "/Users/simon/Downloads/bg_videos",
  "output_dir": "/Users/simon/Downloads/result_bg",
  "gpu": false,
  "core_cnt": 4,
  "vertice_cnt": 30,
  "close_iterations": 3,
  "open_iterations": 3,
  "save_bg_videos": true,
  "video_data": {
    "M2_coc_380_fps_15": {
      "video_path": "/Users/simon/Downloads/bg_videos/M2_coc_380_fps_15.mp4",
      "threshold": 18,
      "smoothing_time": 0.25,
      "buffer_size": null,
      "reference": "/Users/simon/Downloads/bg_videos/M2_coc_380_fps_15.mp4",
      "inclusion_zones": null,
      "window_size": null,
      "close_kernel": 20.0,
      "open_kernel": 3.0
    },
    "...": {}
  }
}

[1]:

#Import SimBA blob tracker CLI utility
from simba.utils.cli.cli_tools import blob_tracker

[2]:

# Set path to your manually created or GUI-exported JSON config
# Update the path below to point to your `.json` file. This file must include the video tracking specifications.
CONFIG_PATH = r"C:\troubleshooting\blob_track\blob_definitions_ex.json"

[3]:

## Step 4: Run the Blob Tracker
# This command will:
# - Load the specified videos
# - Use the reference frames and thresholds in the config
# - Perform background subtraction + morphological processing
# - Save tracking outputs in the specified output directory

# - NOTE: If using a notebook, follow the progress in the terminal window from where you launche dthe notebook.

blob_tracker(config_path=CONFIG_PATH)

Starting background subtraction on video M2_coc_380_fps_15 (video 1/7, frame count: 27000, cores: 24, gpu: False)
Frame batch 1 completed...
Frame batch 2 completed...
Frame batch 3 completed...
Frame batch 4 completed...
Frame batch 5 completed...
Frame batch 6 completed...
Frame batch 7 completed...
Frame batch 8 completed...
Frame batch 9 completed...
Frame batch 10 completed...
Frame batch 11 completed...
Frame batch 12 completed...
Frame batch 13 completed...
Frame batch 14 completed...
Frame batch 15 completed...
Frame batch 16 completed...
Frame batch 17 completed...
Frame batch 18 completed...
Frame batch 19 completed...
Frame batch 20 completed...
Frame batch 21 completed...
Frame batch 22 completed...
Frame batch 23 completed...
Frame batch 24 completed...
Joining M2_coc_380_fps_15 multi-processed video...
SIMBA COMPLETE: Video concatenated (elapsed time: 5.1614s)      complete
SIMBA COMPLETE: Video saved at C:\troubleshooting\blob_track\results\M2_coc_380_fps_15.mp4 (elapsed time: 44.798s)      complete
Starting background subtraction on video F16_sal_400_fps_15 (video 2/7, frame count: 27000, cores: 24, gpu: False)
Frame batch 1 completed...
Frame batch 2 completed...
Frame batch 3 completed...
Frame batch 4 completed...
Frame batch 5 completed...
Frame batch 6 completed...
Frame batch 7 completed...
Frame batch 8 completed...
Frame batch 9 completed...
Frame batch 10 completed...
Frame batch 11 completed...
Frame batch 12 completed...
Frame batch 13 completed...
Frame batch 14 completed...
Frame batch 15 completed...
Frame batch 16 completed...
Frame batch 17 completed...
Frame batch 18 completed...
Frame batch 19 completed...
Frame batch 20 completed...
Frame batch 21 completed...
Frame batch 22 completed...
Frame batch 23 completed...
Frame batch 24 completed...
Joining F16_sal_400_fps_15 multi-processed video...
SIMBA COMPLETE: Video concatenated (elapsed time: 4.5483s)      complete
SIMBA COMPLETE: Video saved at C:\troubleshooting\blob_track\results\F16_sal_400_fps_15.mp4 (elapsed time: 55.1213s)    complete
Starting background subtraction on video F12_sal_380_fps_15 (video 3/7, frame count: 27000, cores: 24, gpu: False)
Frame batch 1 completed...
Frame batch 2 completed...
Frame batch 3 completed...
Frame batch 4 completed...
Frame batch 5 completed...
Frame batch 6 completed...
Frame batch 7 completed...
Frame batch 8 completed...
Frame batch 9 completed...
Frame batch 10 completed...
Frame batch 11 completed...
Frame batch 12 completed...
Frame batch 13 completed...
Frame batch 14 completed...
Frame batch 15 completed...
Frame batch 16 completed...
Frame batch 17 completed...
Frame batch 18 completed...
Frame batch 19 completed...
Frame batch 20 completed...
Frame batch 21 completed...
Frame batch 22 completed...
Frame batch 23 completed...
Frame batch 24 completed...
Joining F12_sal_380_fps_15 multi-processed video...
SIMBA COMPLETE: Video concatenated (elapsed time: 5.4331s)      complete
SIMBA COMPLETE: Video saved at C:\troubleshooting\blob_track\results\F12_sal_380_fps_15.mp4 (elapsed time: 47.0927s)    complete
Starting background subtraction on video M8_sal_400_fps_15 (video 4/7, frame count: 27000, cores: 24, gpu: False)
Frame batch 1 completed...
Frame batch 2 completed...
Frame batch 3 completed...
Frame batch 4 completed...
Frame batch 5 completed...
Frame batch 6 completed...
Frame batch 7 completed...
Frame batch 8 completed...
Frame batch 9 completed...
Frame batch 10 completed...
Frame batch 11 completed...
Frame batch 12 completed...
Frame batch 13 completed...
Frame batch 14 completed...
Frame batch 15 completed...
Frame batch 16 completed...
Frame batch 17 completed...
Frame batch 18 completed...
Frame batch 19 completed...
Frame batch 20 completed...
Frame batch 21 completed...
Frame batch 22 completed...
Frame batch 23 completed...
Frame batch 24 completed...
Joining M8_sal_400_fps_15 multi-processed video...
SIMBA COMPLETE: Video concatenated (elapsed time: 4.5649s)      complete
SIMBA COMPLETE: Video saved at C:\troubleshooting\blob_track\results\M8_sal_400_fps_15.mp4 (elapsed time: 55.7728s)     complete
Starting background subtraction on video M1_sal_380_fps_15 (video 5/7, frame count: 27000, cores: 24, gpu: False)
Frame batch 1 completed...
Frame batch 2 completed...
Frame batch 3 completed...
Frame batch 4 completed...
Frame batch 5 completed...
Frame batch 6 completed...
Frame batch 7 completed...
Frame batch 8 completed...
Frame batch 9 completed...
Frame batch 10 completed...
Frame batch 11 completed...
Frame batch 12 completed...
Frame batch 13 completed...
Frame batch 14 completed...
Frame batch 15 completed...
Frame batch 16 completed...
Frame batch 17 completed...
Frame batch 18 completed...
Frame batch 19 completed...
Frame batch 20 completed...
Frame batch 21 completed...
Frame batch 22 completed...
Frame batch 23 completed...
Frame batch 24 completed...
Joining M1_sal_380_fps_15 multi-processed video...
SIMBA COMPLETE: Video concatenated (elapsed time: 3.9149s)      complete
SIMBA COMPLETE: Video saved at C:\troubleshooting\blob_track\results\M1_sal_380_fps_15.mp4 (elapsed time: 55.1719s)     complete
Starting background subtraction on video F12_coc_364_fps_15 (video 6/7, frame count: 27000, cores: 24, gpu: False)
Frame batch 1 completed...
Frame batch 2 completed...
Frame batch 3 completed...
Frame batch 4 completed...
Frame batch 5 completed...
Frame batch 6 completed...
Frame batch 7 completed...
Frame batch 8 completed...
Frame batch 9 completed...
Frame batch 10 completed...
Frame batch 11 completed...
Frame batch 12 completed...
Frame batch 13 completed...
Frame batch 14 completed...
Frame batch 15 completed...
Frame batch 16 completed...
Frame batch 17 completed...
Frame batch 18 completed...
Frame batch 19 completed...
Frame batch 20 completed...
Frame batch 21 completed...
Frame batch 22 completed...
Frame batch 23 completed...
Frame batch 24 completed...
Joining F12_coc_364_fps_15 multi-processed video...
SIMBA COMPLETE: Video concatenated (elapsed time: 6.114s)       complete
SIMBA COMPLETE: Video saved at C:\troubleshooting\blob_track\results\F12_coc_364_fps_15.mp4 (elapsed time: 50.1068s)    complete
Starting background subtraction on video M2_sal_380_fps_15 (video 7/7, frame count: 27000, cores: 24, gpu: False)
Frame batch 1 completed...
Frame batch 2 completed...
Frame batch 3 completed...
Frame batch 4 completed...
Frame batch 5 completed...
Frame batch 6 completed...
Frame batch 7 completed...
Frame batch 8 completed...
Frame batch 9 completed...
Frame batch 10 completed...
Frame batch 11 completed...
Frame batch 12 completed...
Frame batch 13 completed...
Frame batch 14 completed...
Frame batch 15 completed...
Frame batch 16 completed...
Frame batch 17 completed...
Frame batch 18 completed...
Frame batch 19 completed...
Frame batch 20 completed...
Frame batch 21 completed...
Frame batch 22 completed...
Frame batch 23 completed...
Frame batch 24 completed...
Joining M2_sal_380_fps_15 multi-processed video...
SIMBA COMPLETE: Video concatenated (elapsed time: 5.7106s)      complete
SIMBA COMPLETE: Video saved at C:\troubleshooting\blob_track\results\M2_sal_380_fps_15.mp4 (elapsed time: 47.3704s)     complete
Background subtraction COMPLETE: videos saved at C:\troubleshooting\blob_track\results, (elapsed time: 355.508s)
Starting animal location detection for video M2_coc_380_fps_15...
Animal blob tracking data for video M2_coc_380_fps_15 saved at C:\troubleshooting\blob_track\results\M2_coc_380_fps_15.csv, (elapsed time: 160.046s).
Starting animal location detection for video F16_sal_400_fps_15...
Animal blob tracking data for video F16_sal_400_fps_15 saved at C:\troubleshooting\blob_track\results\F16_sal_400_fps_15.csv, (elapsed time: 155.3263s).
Starting animal location detection for video F12_sal_380_fps_15...
Animal blob tracking data for video F12_sal_380_fps_15 saved at C:\troubleshooting\blob_track\results\F12_sal_380_fps_15.csv, (elapsed time: 152.7777s).
Starting animal location detection for video M8_sal_400_fps_15...
Animal blob tracking data for video M8_sal_400_fps_15 saved at C:\troubleshooting\blob_track\results\M8_sal_400_fps_15.csv, (elapsed time: 158.0056s).
Starting animal location detection for video M1_sal_380_fps_15...
Animal blob tracking data for video M1_sal_380_fps_15 saved at C:\troubleshooting\blob_track\results\M1_sal_380_fps_15.csv, (elapsed time: 164.8258s).
Starting animal location detection for video F12_coc_364_fps_15...
Animal blob tracking data for video F12_coc_364_fps_15 saved at C:\troubleshooting\blob_track\results\F12_coc_364_fps_15.csv, (elapsed time: 132.6086s).
Starting animal location detection for video M2_sal_380_fps_15...
Animal blob tracking data for video M2_sal_380_fps_15 saved at C:\troubleshooting\blob_track\results\M2_sal_380_fps_15.csv, (elapsed time: 157.9654s).
Blob tracking COMPLETE: data saved at C:\troubleshooting\blob_track\results, (elapsed time: 1081.5564s
SIMBA COMPLETE: Animal tracking complete. Results save din directory C:\troubleshooting\blob_track\results (elapsed time: 1437.111s)    complete

[ ]:

## TO CONVERT A PICKLE FILE TO A JSON FILE. NOTE: THIS WILL NOT WORK IF YOU HAVE SPECIFIED INCLUSION / EXCLUSION ZONES.
from simba.utils.read_write import save_json, read_pickle

INPUT_CONFIG_PICKLE_PATH = r"C:\troubleshooting\blob_track_tester\results\blob_definitions.pickle"
OUTPUT_CONFIG_JSON_PATH = r"C:\troubleshooting\blob_track_tester\results\blob_definitions.json"

input_config = read_pickle(INPUT_CONFIG_PICKLE_PATH)
save_json(data=input_config, filepath=OUTPUT_CONFIG_JSON_PATH)