Metadata-Version: 2.4
Name: napari-cell-curator
Version: 0.1.1
Summary: A napari plugin for manual cell tracking curation
Home-page: https://github.com/nickpippi/napari-cell-curator
Author: Nickolas Pippi Peranzoni
Author-email: nickolas.pippiperanzoni@gmail.com
License: MIT
Project-URL: Bug Tracker, https://github.com/YOUR_USERNAME/napari-cell-curator/issues
Project-URL: Documentation, https://github.com/YOUR_USERNAME/napari-cell-curator#readme
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: napari
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: napari>=0.4.17
Requires-Dist: napari-plugin-engine>=0.2.0
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: tifffile
Requires-Dist: magicgui
Requires-Dist: qtpy
Requires-Dist: matplotlib
Requires-Dist: scikit-image
Provides-Extra: testing
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-qt; extra == "testing"
Provides-Extra: video
Requires-Dist: imageio[ffmpeg]; extra == "video"
Dynamic: license-file

# napari-cell-curator

A [napari](https://napari.org) 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

```bash
pip install napari-cell-curator
```

For video export support, also install:

```bash
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](LICENSE).
