napari-simpleannotate 0.1.5

A napari plugin for simple image and video annotation

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

Widget	Annotation File	Class File	Format
Bbox (Images)	image.txt	class.yaml	YOLO standard
Bbox (Video)	imgNNN.txt per frame (+ optional crops/*.txt)	class.yaml	YOLO normalized (per frame/crop)
Classification	labels.csv	class.txt	CSV with image-label pairs

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.