napari-cell-curator 0.1.0

A napari plugin for manual cell tracking curation

napari-cell-curator

A napari plugin for manual curation of cell tracking data from time-lapse microscopy experiments.

---

Overview

napari-cell-curator provides a full-featured dock widget that lets you inspect, correct, and annotate cell tracks directly inside napari. It works with a standard triplet of files:

File	Description
cell_tracks.csv	Tracking table with columns trackId, frame, Center_of_the_object_0, Center_of_the_object_1, continuous_label, Outcome, Parent_ID
cell_mask.tif	4-D label image (T × H × W, uint32)
cell_image.tif	4-D raw microscopy image (T × H × W)

---

Installation

pip install napari-cell-curator

For video export support, also install:

pip install "imageio[ffmpeg]"

---

Usage

1. Open napari.
2. Go to Plugins → Cell Curator Pro.
3. Browse to your CSV, mask TIFF, and image TIFF files.
4. Click Load and Open Curator.

The curator dock panel will appear on the right side of the viewer.

Mouse shortcuts

Action	Result
Shift + Click on a cell	Loads that cell's ID into box [A]
Ctrl + Click on a cell	Loads that cell's ID into box [B]
X or x	Delete cell [A] from the current frame
Ctrl + Z	Undo the last operation (up to 3 steps)

---

Toolbar Buttons

Basic Tools

Button	Description
Undo	Reverts the last operation (up to 3 steps).
Shuffle Colors	Randomizes the napari label color seed. Useful to distinguish adjacent cells.
Merge	Replaces every occurrence of ID [A] with ID [B] across the entire video and CSV.
Swap/Cut (From this frame forward)	Swaps IDs [A] and [B] from the current frame to the end. If [B] is 0, a new ID is generated automatically.
Local Swap (THIS frame only)	Swaps [A] and [B] only in the current frame.
Baptize Mask (New ID)	Assigns a fresh unique ID to the mask currently painted as [A].
Sync Paintings (This Frame)	Reads the label image for the current frame and updates the CSV centroids accordingly.
Sync Everything (Entire Video)	Recalculates centroids from the label image for all frames and reconciles the CSV.
Harmonize Colors	Detects disconnected regions sharing the same ID and splits them. Then aligns continuous_label with trackId.
Delete Cell [A] (This frame)	Erases the mask of cell [A] from the current frame and removes its CSV row.
Exterminate Track [A] (Entire video)	Removes cell [A] from every frame of both the mask and the CSV.
Rescue Orphans	Finds masks in the label image that have no corresponding CSV row and assigns them new IDs.
Auto-Tracking (ID [A] only)	Runs conflict resolution (automatic local swap), predator-mode absorption, and centroid gap filling for track [A].

Outcome Flags

Applied to track ID [A]. Flags are automatically propagated to all frames of the track by the visual engine.

Button	Flag value
Flag: MITOSIS	Mitosis
Flag: END (Left the frame)	End
Flag: DEATH/SENESCENCE	Death/Senescence
Clear Flags from ID [A]	Removes all manual flags; the auto-organizer keeps Start on the first frame.

Lineage Tree

Button	Description
Link Mother [A] -> Daughter [B]	Sets [A] as the parent of [B] in the Parent_ID column. Automatically flags [A] as Mitosis.
Re-sequence Tree	Renumbers all lineage IDs hierarchically (family 1 → daughters 11, 12 → grandchildren 111, 112, 121…). Also handles individually flagged cells without children.
Cut Post-Mitosis Ghosts	Detects mother cells that continue to exist in the mask after their division frame and splits them off with new IDs.
View Lineage Tree Graph	Opens a matplotlib window showing the full lineage tree.

Navigation

Button	Description
Focus Mode	Isolates a single cell in the viewer. All other masks are hidden. Click again to disable.
Jump to Next Unlinked Cell	Advances the viewer to the next frame containing a cell with no lineage assignment and no outcome flag.

Diagnostics & Export

Button	Description
Run Diagnostics	Prints a quality report to the terminal: short tracks, time gaps, spatial jumps, anomalous mitosis durations, and cells without a final outcome flag.
Export Cell Video [A]	Saves a 100×100 px MP4 cropped around cell [A] with its mask highlighted in cyan.
Export Presentation (Screen)	Saves a full-resolution screen capture of the napari canvas as an MP4.
SAVE ALL AND ANALYZE ERRORS	Runs quality control (short tracks, gaps, jumps), shows an interactive dialog to remove or keep anomalies, checks for duplicate IDs, and writes the CSV and mask TIFF to disk.

---

CSV Format

The plugin reads and writes a CSV with at minimum these columns:

trackId, frame, Center_of_the_object_0, Center_of_the_object_1, continuous_label, Outcome, Parent_ID

• Center_of_the_object_0 → X coordinate (column)
• Center_of_the_object_1 → Y coordinate (row)
• Outcome → One of Start, Mitosis, End, Death/Senescence, or empty
• Parent_ID → ID of the mother cell, or -1 if none

Older CSV files using the column name Desfecho instead of Outcome are automatically migrated on load and save.

---

Requirements

• Python ≥ 3.9
• napari ≥ 0.4.17
• numpy, pandas, tifffile, magicgui, qtpy, matplotlib, scikit-image
• imageio[ffmpeg] (optional, for video export)

---

License

MIT License. See LICENSE.