bannotator 1.0.0

Anntotate episodic events of videos

Behavior Annotator

Table of contents

• Installation
• Usage
  • GUI
  • Video
  • Annotation
  • KeyPress Functions
• Contributing
• Acknowledgement
• License

Installation

1. Install Git
2. In git bash, run

git clone https://github.com/hsingchien/Bannotator.git

3. In anaconda prompt, go to annotator directory, run

conda env create -f environment.yml

4. Then activate the environment

conda activate bannotator

5. Under this environment, go to the bannotator directory, run

python setup.py develop

6. To open the app, under this environment, run

annotate-behavior

Usage

GUI

The GUI layout has 5 major areas.

• Video display area, where you can add multiple videos.
• Stream area shows the enlarged portion of the color coded streams.
• Stream overviews provide the bird's-eye view of the full annotation and the current progress.
• Behavior table dock where ID, name, keystroke and color are shown in the Behaviors tab; number of epochs and percentage of the time are shown in the Stats tab.
• Epoch tables where epochs are shown in the All Epochs tab, epochs of selected behaviors are shown in the Behavior Epochs tab.

Video

• Annotator supports major video formats and the Norpix Streampix seq files. Only uncompressed seq (RAW) or compressed seq in JPEG format are currently supported.

• Annotator is capable of displaying multiple videos simultaneously, therefore is great for experiments with multiple video streams. If videos have different number of frames, the 1st added video is treated as the main video and the other videos are stretched to the length of the video 1.

• Annotator provides several different video layouts. Side by side, Stacked or Grid (this option becomes available when number of videos reaches 4).

• Video can be played at various speed.

Annotation

The annotator is compatible with the format of annotation txt file of Piotr's MATLAB toolbox. If you are a user of the behavior annotator of this toolbox, you can view/edit your existing annotation files as well as keep using your configuration files to create new annotations. The output annotation txt files are also back compatible with Piotr's annotator.

If you do not have configuration files to start with, you can create an new annotation from scratch using New annotaion dialog in the Annotation menu. To enable this option you need to add a video first so that the annotator knows the length of the annotation.

First, set the number of streams. In the text editor, input behavior - keystroke pair in each line, parsed by '-' or space. The dialog actively checks the input to ensure the behavior-keystroke pairs are unique. Once created, all the streams will be initialized with the first behavior in your list. Usually the first behavior label is reserved for the blank label of name "other" or "blank", which will be assigned grey color.

Once the new streams are created, go through the video and label the events. Press keystroke to label the current frame as well as the rest of the Epoch.

Epoch is the fundamental unit of the annotation. An Annotation contains Streams which contains a series of Epoch. Each Stream also contains several Behavior objects each one of which stores name, color, keystroke and ID of a user defined behavior. Behavior objects also collects all the Epochs of this kind in its stream.

KeyPress Functions

Space : Play/Pause video

↑ / ↓ : Increase/Decrease playing speed

← / → : Previous/Next frame

1 - 0 : Change the current stream to stream 1 - 10

` : Rotate current stream through all streams

-/+ : Move to previous/next epoch of current stream

CTRL-/CTRL+ : Move to previous/next epoch of selected behavior

Contributing

Your contributions are always welcome! Contribution guideline will be available soon.

Acknowledgement

This project is inspired by Piotr's MATLAB toolbox.

Seq file reading is inspired by PIMS.

Random color generator distinctipy

The project is built with PySide6.

License

The MIT License (MIT) 2017 - Xingjian Zhang.