Skip to content

Introduction

Jump to bottom
Zachary Werkhoven edited this page Jan 15, 2021 · 7 revisions

Contents

  1. Installation
  2. Quickstart Guide
  3. Overview
  4. Experimental workflow
  5. Optimizing MARGO

Installation

Prerequisites

MATLAB

For best results, use MARGO with MATLAB 2016b or newer. MARGO but has generally been designed to be backwards compatible with older versions of MATLAB. In addition to the base installation of MATLAB, MARGO uses the image acquisition and image processing toolboxes.

Psychtoolbox (optional)

MARGO requires on Psychtoolbox 3 for support of external displays.

MARGO installation

1. The MARGO repository can be cloned via the github UI by downloading and extracting a zip file of the repository (Clone or Download > Download ZIP) OR clone via the git command line API with the following command: 

git clone https://github.com/de-Bivort-Lab/margo.git

2. After cloning the repository, add the MARGO directory to MATLAB's path by navigating to the margo directory and running: 

addpath(genpath(pwd));

OR

Alternatively, permanently add MARGO and all sub folders to the MATLAB path by adding by running:

pathtool

3. Once the margo directory is added to the MATLAB path, launch the GUI from the command line: 

margo

Getting started

We recommend that new users read the MARGO overview below for general understanding of how MARGO works and follow the sample tracking tutorial included in this documentation for more complete instructions on establishing tracking in MARGO.

Overview

MARGO is a MATLAB-based software package for real-time, high-throughput tracking of animals. Rapid tracking and identity sorting in real-time means that MARGO is particularly useful for applications requiring closed-loop control of individual stimulus delivery and massively high-throughput behavioral screens where video storage and processing would otherwise be rate-limiting. MARGO offers additional utility through GUI-based customization of tracking parameters, hardware settings, ROI-detection, and saved preferences. Development of custom experimental paradigms is facilitated through MARGO's experiment template tool and API.

Tracking Modes

MARGO can track objects in two different modes:

  1. Single Tracking - This mode is designed to track spatially segregated animals in parallel. Spatial segregation allows individuals to be tracked separately in defined regions of interest (ROIs). Single tracking operates on a single animal per ROI and can track many hundreds or thousands of individuals in parallel at high acquisition rates. In this mode, individual identities can be maintained indefinitely without supervision.

  2. Multi Tracking - This mode is designed to track groups of animals in parallel in one or more ROIs. Individual identities are not maintained. Multi tracking can be used to track spatial distribution, activity level, and group dynamics that do not require maintenance of individual identities.

Data outputs

  • centroid coordinates
  • timestamps (interframe interval in sec)
  • speed (pixels or mm s-1)
  • body size (pixels2 or mm2)
  • orientation (ellipse fit)
  • heading direction
  • angular velocity
  • comprehensive meta data
  • custom defined outputs

Hardware

  • cameras
  • external displays
  • serial COM devices

Starting a new experiment

Every experiment conducted in MARGO follows the same fundamental workflow. As users move through workflow, MARGO will progressively enable downstream utilities to enforce the correct setup. Before tracking, users must:

  1. Select and confirm video input source (camera/video file)

  2. Automatically or manually set ROIs

  3. Initialize a background reference image

  4. Collect a sample of clean imaging

  5. Set experiment parameters

Select video Input

MARGO support cameras and video files as input sources of video data. The input source can be switched under the Source menu.

Camera

MARGO will automatically detect any available camera with an associated MATLAB imaq adaptor installed and auto-populate the camera panel drop down with detected cameras. If no cameras are detected, see camera detection for information on installing MATLAB camera adaptors.

  1. Select a camera from the dropdown menu
  2. Select camera operating mode from the dropdown menu
  3. Press Confirm Settings button to open camera session
  4. Start Preview to view camera output (optional)
  5. Adjust camera settings such as exposure and shutter speed under Hardware > camera > camera settings (optional)

Video File

Switching the input source to video will replace the default camera input panel with the video input panel. MARGO supports the following avi, m4v, mov, mp4, mpg, and wmv formats but requires the appropriate video codecs to be installed and accessible by MATLAB. Videos should contain 8-bit mono, RGB, or YUV video data. To input a video:

  1. Select Source > video file
  2. Press Select files to select one or more video files
  3. Preview the video with Start Preview (optional)

Display modes

After initializing the video input, an initial preview image will be visible in the display window and the downstream ROI detection controls will be enabled. The preview button can be used to start and stop a streaming preview from the camera at any time the video input is not actively in use. Once the background reference has been acquired, the camera preview mode can be adjusted via the Display menu to preview:

  • raw - raw video input
  • difference -background subtraction
  • threshold - foreground extracted blobs
  • reference - background reference image

Define ROIs

Regions of interest must be set before individual identities can be tracked frame to frame. MARGO sets ROIs through either grid (default) or automatic modes. ROI definition modes can be toggled under Options > Tracking > ROI detection. See ROI detection for more details.

Grid

Grid ROI definition requires the user to draw one or more grids that define the boundaries between ROIs. To define ROI grids:

  1. Select Detect ROIs to open the grid ROI settings panel
  2. Click and drag a rectangle in the preview window to place a grid
  3. Click and drag ROI corners to adjust the individual vertices of the grid outline
  4. Adjust the ROI shape (quadrilateral or ellipsoid), grid row/column number, and ROI scale in the grid ROI settings panel
  5. Add one or more grids via the (+) button

Automatic

Automatic ROI detection extracts bright regions of the image. Once bright regions are extracted, regions with a pixel area < 100 are filtered out and the median width and height of the remaining objects is calculated. Regions are further filtered for width or height outside of a margin of error around the median. The remaining regions are selected as ROIs. For automatic detection to work reliably, ROIs should be bright, relatively abundant in the image, and should be a of a consistent size. To run automatic ROI detection:

  1. Select detect ROIs
  2. Adjust the ROI threshold slider bar to find a threshold that best separates ROIs from the background. Bounding boxes and ROI numbers will be displayed over any detected ROIs in real time.
  3. Select Accept to confirm ROI positions
  4. Add or remove ROIs as needed via Options > edit ROIs

Initialize background reference image

To track changes in the image from frame to frame, MARGO calculates a difference image between each frame and a background reference image. The background reference is generated by computing a median or mean image from snapshots of each ROI when the individual is in different locations. See Background Referencing for additional details. To initialize a background reference image:

  1. Select Initialize Reference
  2. Adjust the tracking threshold slider to find separation of objects from background
  3. Inspect the reference image as it develops by switching the view under Display > reference.
  4. Select Accept next to the tracking threshold slider to confirm the background reference image. Colored indicators next to each ROI will progress from red to blue as images of each ROI are collected.

Optimizing MARGO

Fast, accurate tracking can be highly dependent on optimization of parameters, camera configuration, and illumination. MARGO attempts to make the task from setup to data collection as streamlined as possible by making some of these decisions. Since every experiment and tracking setup is a bit different, getting optimal tracking performance out of MARGO may require adjusting both software and hardware parameters. MARGO has many integrated features to help the user make these decisions and then save the preferences to a user profile to ensure that the setup process is only necessary once. Here is a helpful but non-comprehensive list of things that will help you get the most out of MARGO:

Wiki Contents

Home

Introduction

Tracking Tutorial

Setup Details

Analysis Tutorial

Data Outputs

Options and Parameters

Hardware

External Displays

Custom Experiment Tutorial

Clone this wiki locally