EntocellularAnnotate

Cell annotation toolkit for Cellpose fine-tuning on phase contrast microscopy images. Built for the UMass Boston IMPACT program.

Includes a Napari-based annotation tool with model-assisted pre-labeling — pre-computed segmentation masks are loaded as starting points so you correct predictions instead of painting from scratch.

Repository Structure

├── annotate.py                 # Napari annotation tool
├── cpsam_inf.py                # Cellpose-SAM inference (local)
├── cpsam_train.py              # Cellpose-SAM fine-tuning (local)
├── generate_patches.ipynb      # Chunk TIFFs into patches (Colab)
├── finetune.ipynb              # Fine-tune Cellpose + evaluate (Colab)
├── generate_predictions.ipynb  # Generate pred_masks for annotation (Colab)
├── img0/
│   ├── patches/                # 196 image patches (256×256, 50% overlap)
│   ├── masks/                  # Hand-annotated cell masks
│   └── pred_masks/             # Model predictions for assisted annotation
├── img1/
│   ├── patches/                # 196 image patches
│   ├── masks/                  # Hand-annotated cell masks
│   └── pred_masks/             # Model predictions for assisted annotation
└── models/
    └── finetuned_best          # Fine-tuned Cellpose cyto3 model (AP@0.5: 0.624)

Setup

pip install -r requirements.txt

Annotating

From scratch

python annotate.py -i img0/patches -o img0/masks

Model-assisted (recommended)

python annotate.py -i img0/patches -o img0/masks -p img0/pred_masks
python annotate.py -i img1/patches -o img1/masks -p img1/pred_masks

Resume

Already-annotated patches are automatically skipped. Jump to a specific index:

python annotate.py -i img0/patches -o img0/masks -p img0/pred_masks --start 50

Options

Flag	Description
-i, --input	Directory with img_*.npy patches (required)
-o, --output	Directory to save mask_*.npy annotations (required)
-p, --preds	Directory with pred_*.npy predictions (optional)
--start	Patch index to start from (default: 0)

Cellpose-SAM (local)

Inference and fine-tuning scripts that run against the on-disk <root>/patches/ and <root>/masks/ layout.

Inference

python cpsam_inf.py --root img0 --n 51                 # first 51 patches in img0
python cpsam_inf.py --root img0 --indices 0 7 42       # specific indices
python cpsam_inf.py --model models/cpsam_finetuned     # use a fine-tuned checkpoint
python cpsam_inf.py --root img0 --out-name pred_masks  # overwrite canonical seeds

Default output dir is <root>/preds_<timestamp>/. Pass --view to inspect each prediction in Napari.

Fine-tuning

python cpsam_train.py                                  # all roots: img0, img1
python cpsam_train.py --root img0 --epochs 200 --lr 5e-5 --model-name my_cells

Pairs <root>/patches/img_NNNN.npy with <root>/masks/mask_NNNN.npy, splits off --val-frac (default 0.15), and saves the checkpoint under models/.

Napari Controls

Action	Control
Paint cell	Left click / drag
Erase	Right click / drag
New cell label	M (auto-increments)
Pick existing label	L then click a cell
Toggle mask	Eye icon or V
Brush size	Toolbar slider
Save + next	Close the window

Annotation Guidelines

• Each cell gets a unique integer label. Background is 0.
• If you can see any boundary between cells, annotate separately.
• If cells form one indistinguishable blob, annotate as one.

Model

The included model is Cellpose cyto3 fine-tuned on 51 hand-annotated phase contrast patches.

	AP@0.5	Eval
Base cyto3	0.523	finetune.ipynb test split
Fine-tuned cyto3	0.624	finetune.ipynb test split
Base cpsam	0.515	img0 val (16 patches)
Fine-tuned cpsam	0.688	img0 val (16 patches)

Training config:

• cyto3: 500 epochs, lr=0.001, weight_decay=1e-5, diameter=17px
• cpsam: 100 epochs, lr=1e-5, weight_decay=0.1 (defaults from cpsam_train.py)