napari-macrophage

A napari plugin for interactive 3D macrophage image analysis — mask editing, Otsu/Watershed segmentation, YOLO bounding box export, and morphology analysis.

3D segmentation of macrophages overlaid with the volume	3D rendering of a single macrophage

Features

• Load multi-channel TIFF/Zarr images (CD206, DAPI, Collagen, F480) and 3D instance masks
• Click-to-select objects; delete per-slice or globally; rename, renumber IDs
• Draw ROI → Otsu preview (adjustable threshold) → optional Watershed → save 3D mask
• ONNX-based automatic macrophage detection (CD206 + DAPI)
• Annotate and export/import bounding boxes in YOLO .txt format
• Per-object morphology analysis: volume, surface area, sphericity → CSV export
• Isotropic resampling of image and mask
• 3D rendering of individual macrophages (smoothed surface mesh, adjustable shading, black/white background, PNG screenshot, mesh export to STL/OBJ/PLY)

Installation

With uv (recommended)

uv sync                       # core deps
uv sync --extra detection     # + onnxruntime for ONNX detection
uv run napari

With pip

pip install napari-macrophage
napari

Development

pip install -e .
napari

Usage

Start napari with the two main plugin docks already open:

napari-macrophage

(The regular napari command still works — use it if you want a clean viewer without the plugin's docks pre-mounted.)

1. Load data — Plugins → napari-macrophage → Load Image & Mask (or use the Load Image & Mask dock opened by napari-macrophage)
2. Edit masks — Plugins → napari-macrophage → Annotate & Correct Masks/Boxes
3. Segment — Draw ROI bbox → Otsu preview → Save or Run Watershed
4. Detect — Run ONNX detection on CD206 + DAPI slices
5. Render 3D — In the 3D Visualization panel, enter an Object ID and click Generate 3D to open the macrophage in a new window; save a PNG or export the mesh (STL/OBJ/PLY) from that window
6. Export — YOLO .txt bounding boxes or morphology .csv

Input shape: (Z, Y, X) for grayscale, (C, Z, Y, X) for multi-channel (C ∈ {2, 5}).

Documentation

Full user guide and API reference: macrophage-napari.readthedocs.io

Build the docs locally:

pip install -e ".[docs]"
sphinx-build docs docs/_build/html

Companion pipeline

For fully automated end-to-end segmentation (YOLO + SAM2 + Cellpose), see: macrophage-image-processor