Please cite this work if it helped with your project! Thank you!
Xingjian Zhang. (2024). hsingchien/Bannotator: 1.0 stable version (1.0.0). Zenodo. https://doi.org/10.5281/zenodo.10957095
pip install bannotatorOpen GUI
annotate-behavior
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.
-
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.
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.
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
Your contributions are always welcome! Contribution guideline will be available soon.
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.
The MIT License (MIT) 2017 - Xingjian Zhang.