napari-simpleannotate

A napari plugin for simple image and video annotation that provides three main annotation workflows:

1. Bounding Box Annotation (YOLO format): For object detection training data on images
2. Video Bounding Box Annotation: For object detection training data on video files
3. Image Classification Labeling: For image classification training data

This napari plugin was generated with Cookiecutter using @napari's cookiecutter-napari-plugin template.

Installation

You can install napari-simpleannotate via pip:

pip install napari-simpleannotate

To install latest development version :

pip install git+https://github.com/hiroalchem/napari-simpleannotate.git

How to use

Getting Started

After installing napari-simpleannotate, launch napari and navigate to Plugins > Add dock widget to find three annotation widgets:

• Bbox annotation: For bounding box annotation on images
• Bbox video annotation: For bounding box annotation on video files
• Label image classification: For image classification labeling

Bounding Box Annotation (Images)

Prerequisites: None required

1. Opening Files:

   • Single file: Click Open File to select an image file
   • Directory: Click Open Directory to select a folder containing images
   • If a class.yaml file exists in the directory, you'll be prompted to load existing classes

2. Class Management:

   • Enter class names in the text box and click Add class
   • Classes are automatically assigned sequential IDs (0, 1, 2, ...)
   • Select a class and click Delete selected class to remove it
   • Classes are saved to class.yaml alongside annotations

3. Creating Annotations:

   • Select a class from the list (becomes your active class)
   • Use napari's rectangle tool (shortcut: R) to draw bounding boxes
   • New rectangles automatically inherit the selected class
   • Change existing rectangles: select the shape, then click a different class

4. Saving Work:

   • Click Save Annotations to export in YOLO format
   • Files saved: image_name.txt (YOLO coordinates) + class.yaml (class definitions)
   • YOLO format: class_id x_center y_center width height (normalized 0-1)

Video Bounding Box Annotation

Prerequisites: Install PyAV for video support: pip install av

1. Opening Videos:

   • Click Open Video to select MP4, AVI, MOV, MKV, WMV, FLV, or WebM files
   • Frames load through a cached reader that keeps recently viewed frames ready for scrubbing

2. Navigation & Frame Tools:

   • Use napari's time slider; the widget shows Frame: current/total alongside live cache usage
   • Jump between annotated frames with the Prev (Q) and Next (W) buttons or keyboard shortcuts
   • Nearby frames are prefetched in the background to keep playback smooth during review

3. Annotating Frames:

   • Draw rectangles after selecting a class; each shape stores its frame index automatically
   • Bounding boxes are only visible on the frame where they were created
   • Class management matches the image workflow, and class.yaml is written in YOLO names: format

4. Automatic Tracking:

   • Use Start to launch trackers for the boxes in the current frame and Stop to halt processing
   • Keep Track all bounding boxes enabled to follow every box, or disable it to track only selected shapes
   • Choose between the default OpenCV CSRT tracker and the experimental TrackerVit

   

5. Saving & Exports:

   • Save Annotations writes per-frame YOLO files (imgNNN.txt) in a video-specific folder next to the source
   • Annotated frames are saved once as imgNNN.png so you can review what was labeled later
   • Enable Enable crop on save to export fixed-size crops plus matching YOLO labels under crops/
   • Existing exports are reused when present so repeated saves only write new annotations

Image Classification Labeling

Prerequisites: None required

1. Opening Directory:

   • Click Open Directory to select image folder
   • Recursively finds all images (PNG, TIF, JPG, JPEG, TIFF)
   • Automatically loads existing labels.csv and class.txt if present

2. Display Options:

   • Split Channels: Check to display multi-channel images as separate layers
   • Contrast settings preserved when switching between images
   • Navigate images using the file list on the left

3. Labeling Workflow:

   • Add classes: Type in text box and press Enter (or click Add class)
   • Remove classes: Type existing class name and press Enter
   • Assign labels: Select image → Click class name to label it
   • Real-time auto-save to labels.csv and class.txt

4. Resume Sessions:

   • Previous work automatically loaded when reopening directories
   • Continue labeling from where you left off

Performance Notes

• Video annotation: Optimized with frame caching and parallel prefetching for smooth playback
• Large datasets: Classification widget handles thousands of images efficiently
• Memory management: LRU cache prevents memory overflow during long annotation sessions

Output Formats

Contributing

Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

License

Distributed under the terms of the BSD-3 license, "napari-simpleannotate" is free and open source software

Issues

If you encounter any problems, please file an issue along with a detailed description.