AnnotateEZ

A lightweight GUI tool for visualizing and annotating immunofluorescence (IF) microscopy cell images stored in HDF5 format.

Features

• Tile-based grid view of single-cell images with configurable layout
• Multi-class annotation with customizable label names and colors
• Configurable RGB channel mapping with per-channel gain control
• Optional mask boundary overlay (binary or multi-cell instance masks)
• Click-and-drag annotation for fast bulk labeling
• Per-page lazy image loading with background prefetch — handles large datasets without loading everything into memory
• Sort events by any DataFrame column without modifying the underlying data
• Undo / redo with configurable depth
• Dark and light themes
• Full keyboard shortcut support
• Annotations saved back to the source HDF5 file and exported to TSV

Input Format

The tool expects an HDF5 file with the following datasets:

Installation

pip install annotate-ez

Usage

# bash command
annotate-ez

Keyboard Shortcuts

Annotation Tips

Single-click annotation Left-click any tile to assign the currently selected label. Right-click to reset it to the background class (label 0).

Click-and-drag annotation Hold the mouse button and drag across tiles to annotate multiple cells in one motion. The entire drag gesture counts as a single undo step, so you can reverse it with one Ctrl+Z.

Batch labeling Use the All button to assign the active label to every tile on the current page, or None to reset the entire page to background. Both actions are undoable.

Sorting for faster review Use the sort panel to reorder cells by any feature column (e.g., a confidence score or size metric) before annotating. Sort order is display-only — the saved DataFrame is never reordered.

Undo depth The default undo history keeps the last 3 steps. Increase max undo steps in Settings if you want a deeper history, keeping in mind that each step stores a full copy of all labels.

Configuration

On first launch, a default configuration file is created at:

~/.config/annotate-ez/config.yml

All settings are also editable via the Settings dialog inside the app. Key options:

Requirements

• Python 3.8 – 3.9 (tested)
• PyQt5 ≥ 5.15
• h5py ≥ 3.1
• pandas ≥ 1.3
• numpy ≥ 1.21
• tables ≥ 3.8
• PyYAML ≥ 6.0