itasc 0.2.0.dev0__py3-none-any.whl

itasc/tracking_ultrack/validation_state.py

@@ -0,0 +1,430 @@
+"""Persistent validation metadata for the nucleus workflow.
+
+All functions take ``nucleus_dir`` — the directory that holds the nucleus
+annotation store (``validated_frames.json``, ``validated_cells.json``,
+``corrections.json``). In the full orchestrator this is ``<pos>/2_nucleus``; the
+standalone tracking piece points it at a flat working directory. The annotation
+files live directly in that directory.
+
+Frame-level validation (validated_frames.json):
+    A "fully-validated" frame is one where every current (non-zero) cell ID has
+    been individually validated.  The file acts as a *cache* so UI counters can
+    count fully-validated frames without scanning the whole stack.
+
+    Schema: JSON array of ints, e.g. [0, 3, 7].
+
+Track-level validation (validated_cells.json):
+    Tracks which frames have been validated for each cell (track) ID.
+
+    Schema: JSON object keyed by cell ID string, value is a list of frame ints,
+    e.g. {"47": [10, 11, 12], "82": [3, 4, 5]}.
+    Cell IDs with no validated frames are omitted entirely (sparse).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from collections.abc import Iterable
+
+import numpy as np
+
+from itasc.tracking_ultrack.corrections import Correction
+
+# Stat-keyed parse caches: hot overlay loops call the readers below repeatedly,
+# and re-parsing unchanged JSON each time is the cost the review flagged. Key on
+# the file's (mtime_ns, size); a writer touching the file changes the signature
+# and invalidates the entry. Callers always receive a fresh copy, so the cached
+# value is never mutated through aliasing.
+_corrections_cache: dict[Path, tuple[tuple[int, int], list[Correction]]] = {}
+_legacy_tracks_cache: dict[Path, tuple[tuple[int, int], dict[int, set[int]]]] = {}
+
+
+def _stat_signature(path: Path) -> tuple[int, int] | None:
+    try:
+        st = path.stat()
+    except OSError:
+        return None
+    return (st.st_mtime_ns, st.st_size)
+
+
+def _path(nucleus_dir: Path) -> Path:
+    return Path(nucleus_dir) / "validated_frames.json"
+
+
+def read_validated_frames(nucleus_dir: Path) -> set[int]:
+    """Return the set of validated frame indices, or an empty set if none."""
+    p = _path(nucleus_dir)
+    if not p.exists():
+        return set()
+    try:
+        data = json.loads(p.read_text())
+        return set(int(t) for t in data)
+    except Exception:
+        return set()
+
+
+def write_validated_frames(nucleus_dir: Path, frames: set[int]) -> None:
+    """Persist the full set of validated frames."""
+    p = _path(nucleus_dir)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(sorted(frames)))
+
+
+def validate_frame(nucleus_dir: Path, t: int) -> None:
+    """Mark frame t as validated."""
+    frames = read_validated_frames(nucleus_dir)
+    frames.add(t)
+    write_validated_frames(nucleus_dir, frames)
+
+
+def invalidate_frame(nucleus_dir: Path, t: int) -> None:
+    """Remove the validated mark from frame t."""
+    frames = read_validated_frames(nucleus_dir)
+    frames.discard(t)
+    write_validated_frames(nucleus_dir, frames)
+
+
+def is_validated(nucleus_dir: Path, t: int) -> bool:
+    """Return True if frame t is in the validated set."""
+    return t in read_validated_frames(nucleus_dir)
+
+
+# ---------------------------------------------------------------------------
+# Track-level validation (nucleus workflow)
+# ---------------------------------------------------------------------------
+
+def _cells_path(nucleus_dir: Path) -> Path:
+    return Path(nucleus_dir) / "validated_cells.json"
+
+
+def read_validated_tracks(nucleus_dir: Path) -> dict[int, set[int]]:
+    """Return {cell_id: {frames}} for all validated tracks.
+
+    Empty dict if the file is missing or corrupt.
+    JSON keys are cell ID strings; values are lists of frame ints.
+    """
+    corrections = read_corrections(nucleus_dir)
+    if corrections:
+        data: dict[int, set[int]] = {}
+        for correction in corrections:
+            if correction.kind == "validated":
+                data.setdefault(int(correction.cell_id), set()).add(int(correction.t))
+        legacy = _read_legacy_validated_tracks(nucleus_dir)
+        for cell_id, frames in legacy.items():
+            data.setdefault(cell_id, set()).update(frames)
+        return data
+    return _read_legacy_validated_tracks(nucleus_dir)
+
+
+def _copy_tracks(data: dict[int, set[int]]) -> dict[int, set[int]]:
+    """Deep-ish copy so a cached map is never mutated through the returned value."""
+    return {cell_id: set(frames) for cell_id, frames in data.items()}
+
+
+def _read_legacy_validated_tracks(nucleus_dir: Path) -> dict[int, set[int]]:
+    p = _cells_path(nucleus_dir)
+    sig = _stat_signature(p)
+    if sig is None:
+        _legacy_tracks_cache.pop(p, None)
+        return {}
+    hit = _legacy_tracks_cache.get(p)
+    if hit is not None and hit[0] == sig:
+        return _copy_tracks(hit[1])
+    try:
+        raw: dict = json.loads(p.read_text())
+        parsed = {int(k): set(int(f) for f in vs) for k, vs in raw.items() if vs}
+    except Exception:
+        return {}
+    _legacy_tracks_cache[p] = (sig, parsed)
+    return _copy_tracks(parsed)
+
+
+def _write_validated_tracks(nucleus_dir: Path, data: dict[int, set[int]]) -> None:
+    """Persist the full {cell_id: {frames}} map. Entries with empty sets are dropped."""
+    p = _cells_path(nucleus_dir)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    serialisable = {
+        str(cell_id): sorted(frames)
+        for cell_id, frames in data.items()
+        if frames
+    }
+    p.write_text(json.dumps(serialisable))
+    # Invalidate the parse cache explicitly: two same-size writes within the
+    # filesystem's mtime granularity (coarse on Windows/FAT/NFS) leave the
+    # (mtime_ns, size) signature unchanged, so a stale entry would survive.
+    _legacy_tracks_cache.pop(p, None)
+
+
+def read_validated_cells_at_frame(nucleus_dir: Path, t: int) -> set[int]:
+    """Return all cell IDs that have frame *t* in their validated set.
+
+    Derived from the track-keyed store; suitable for overlay rendering.
+    """
+    return {cell_id for cell_id, frames in read_validated_tracks(nucleus_dir).items() if t in frames}
+
+
+def is_track_validated(nucleus_dir: Path, cell_id: int) -> bool:
+    """Return True if *cell_id* has any entry in the validated-tracks store."""
+    return cell_id in read_validated_tracks(nucleus_dir)
+
+
+def validate_track(nucleus_dir: Path, cell_id: int, frames: Iterable[int]) -> None:
+    """Add the given frames to *cell_id*'s validated set (idempotent, accumulates).
+
+    Creates an entry for *cell_id* if none exists yet. Any existing per-frame
+    anchor corrections for the same cell are dropped — whole-track validation
+    supersedes them (the post-solve paste-back stamps the validated geometry,
+    so anchor pins on the same cell are redundant).
+    """
+    frames_set = set(frames)
+    if not frames_set:
+        return
+    data = read_validated_tracks(nucleus_dir)
+    existing = data.get(cell_id, set())
+    data[cell_id] = existing | frames_set
+    _write_validated_tracks(nucleus_dir, data)
+
+    corrections = read_corrections(nucleus_dir)
+    if corrections:
+        filtered = [
+            c
+            for c in corrections
+            if not (int(c.cell_id) == int(cell_id) and c.kind == "anchor")
+        ]
+        if len(filtered) != len(corrections):
+            write_corrections(nucleus_dir, filtered)
+
+
+
+def invalidate_track(nucleus_dir: Path, cell_id: int) -> None:
+    """Remove the entire entry for *cell_id* from the validated-tracks store.
+
+    No-op if *cell_id* is not present.
+    """
+    corrections = read_corrections(nucleus_dir)
+    if corrections:
+        write_corrections(
+            nucleus_dir,
+            [
+                c
+                for c in corrections
+                if not (int(c.cell_id) == int(cell_id) and c.kind == "validated")
+            ],
+        )
+    data = read_validated_tracks(nucleus_dir)
+    if cell_id in data:
+        del data[cell_id]
+        _write_validated_tracks(nucleus_dir, data)
+
+
+def remap_validated_tracks(nucleus_dir: Path, old_to_new: dict[int, int]) -> None:
+    """Remap cell IDs in the validated-tracks store using *old_to_new* mapping.
+
+    IDs not present in the mapping are dropped.
+    """
+    corrections = read_corrections(nucleus_dir)
+    # Read the legacy store *directly* (not via ``read_validated_tracks``, which
+    # merges in the corrections we are about to rewrite) so each store is remapped
+    # exactly once. Reading the merged view here would remap the corrections-derived
+    # IDs a second time and inject phantom validations whenever the mapping is not
+    # the identity — i.e. for any real contiguous compaction with gaps.
+    legacy = _read_legacy_validated_tracks(nucleus_dir)
+    if corrections:
+        write_corrections(
+            nucleus_dir,
+            [
+                Correction(
+                    cell_id=int(old_to_new[int(c.cell_id)]),
+                    t=int(c.t),
+                    kind=c.kind,
+                    y=float(c.y),
+                    x=float(c.x),
+                )
+                for c in corrections
+                if int(c.cell_id) in old_to_new
+            ],
+        )
+    remapped = {
+        old_to_new[cell_id]: frames
+        for cell_id, frames in legacy.items()
+        if cell_id in old_to_new
+    }
+    _write_validated_tracks(nucleus_dir, remapped)
+
+
+# ---------------------------------------------------------------------------
+# Unified correction list (nucleus workflow)
+# ---------------------------------------------------------------------------
+
+def _corrections_path(nucleus_dir: Path) -> Path:
+    return Path(nucleus_dir) / "corrections.json"
+
+
+def read_corrections(nucleus_dir: Path) -> list[Correction]:
+    """Return persisted per-frame corrections, or an empty list if unavailable."""
+    p = _corrections_path(nucleus_dir)
+    sig = _stat_signature(p)
+    if sig is None:
+        _corrections_cache.pop(p, None)
+        return []
+    hit = _corrections_cache.get(p)
+    if hit is not None and hit[0] == sig:
+        return list(hit[1])  # fresh list of immutable Corrections
+    try:
+        raw = json.loads(p.read_text())
+        corrections = [
+            Correction(
+                cell_id=int(item["cell_id"]),
+                t=int(item["t"]),
+                kind=item["kind"],
+                y=float(item["y"]),
+                x=float(item["x"]),
+            )
+            for item in raw
+        ]
+    except Exception:
+        return []
+    result = sorted(corrections, key=lambda c: (c.t, c.cell_id, c.kind))
+    _corrections_cache[p] = (sig, result)
+    return list(result)
+
+
+def write_corrections(nucleus_dir: Path, corrections: Iterable[Correction]) -> None:
+    """Persist the full flat correction list to ``corrections.json``."""
+    p = _corrections_path(nucleus_dir)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    serialisable = [
+        {
+            "cell_id": int(c.cell_id),
+            "t": int(c.t),
+            "kind": c.kind,
+            "y": float(c.y),
+            "x": float(c.x),
+        }
+        for c in sorted(corrections, key=lambda item: (item.t, item.cell_id, item.kind))
+    ]
+    p.write_text(json.dumps(serialisable))
+    # See _write_validated_tracks: same-size writes can share a (mtime_ns, size)
+    # signature on coarse-mtime filesystems, so invalidate the cache explicitly.
+    _corrections_cache.pop(p, None)
+
+
+def add_correction(nucleus_dir: Path, correction: Correction) -> None:
+    """Add or replace a correction for the same cell, frame, and kind.
+
+    Writing a ``validated`` correction for a cell additionally drops every
+    ``anchor`` correction for that cell — validation is whole-track and
+    supersedes any anchor pinning on the same cell.
+    """
+    add_corrections(nucleus_dir, [correction])
+
+
+def add_corrections(nucleus_dir: Path, corrections: Iterable[Correction]) -> None:
+    """Add or replace several corrections with a single read+write.
+
+    Each correction replaces any existing one for the same cell, frame, and
+    kind (later entries in *corrections* win over earlier ones). As with
+    :func:`add_correction`, a ``validated`` correction for a cell additionally
+    drops every ``anchor`` correction for that cell.
+
+    Unlike calling :func:`add_correction` in a loop, this reads and writes
+    ``corrections.json`` exactly once, so validating a long track stays cheap
+    instead of re-parsing and re-serialising the whole file per frame.
+    """
+    new = list(corrections)
+    if not new:
+        return
+
+    # Keys (cell_id, t, kind) being written; cell_ids whose anchors validation drops.
+    replaced_keys = {(int(c.cell_id), int(c.t), c.kind) for c in new}
+    validated_cells = {int(c.cell_id) for c in new if c.kind == "validated"}
+
+    def _keep(c: Correction) -> bool:
+        if (int(c.cell_id), int(c.t), c.kind) in replaced_keys:
+            return False
+        if c.kind == "anchor" and int(c.cell_id) in validated_cells:
+            return False
+        return True
+
+    existing = [c for c in read_corrections(nucleus_dir) if _keep(c)]
+
+    # Dedupe within the batch itself (last wins for a repeated key).
+    deduped: dict[tuple[int, int, str], Correction] = {}
+    for c in new:
+        deduped[(int(c.cell_id), int(c.t), c.kind)] = c
+
+    write_corrections(nucleus_dir, existing + list(deduped.values()))
+
+
+def _centroid_of(mask: np.ndarray) -> tuple[float, float] | None:
+    if mask.ndim == 3:
+        mask = mask.any(axis=0)
+    ys, xs = np.nonzero(mask)
+    if ys.size == 0:
+        return None
+    return float(ys.mean()), float(xs.mean())
+
+
+def add_anchor(
+    nucleus_dir: Path,
+    cell_id: int,
+    t: int,
+    y: float,
+    x: float,
+    tracked_labels: np.ndarray,
+) -> int:
+    """Add an anchor for *cell_id* at frame *t* and back-fill intermediate frames.
+
+    If another anchor for the same cell already exists at some frame ``A``,
+    find the nearest such ``A`` (smallest ``|A - t|``). If ``cell_id`` is
+    present in ``tracked_labels`` at *every* frame in ``[min(A, t), max(A, t)]``,
+    add an anchor correction for each intermediate frame using the cell's
+    centroid in ``tracked_labels`` at that frame.
+
+    Returns the number of intermediate anchors added (0 if no neighbor exists
+    or the track is not consecutive).
+
+    The strictness rule guarantees we never anchor onto a frame where the cell
+    isn't actually present in the corrected layer.
+    """
+    cell_id = int(cell_id)
+    t = int(t)
+
+    existing = read_corrections(nucleus_dir)
+    other_anchor_frames = sorted(
+        int(c.t)
+        for c in existing
+        if int(c.cell_id) == cell_id and c.kind == "anchor" and int(c.t) != t
+    )
+
+    add_correction(
+        nucleus_dir,
+        Correction(cell_id=cell_id, t=t, kind="anchor", y=float(y), x=float(x)),
+    )
+
+    if not other_anchor_frames:
+        return 0
+
+    neighbor = min(other_anchor_frames, key=lambda f: (abs(f - t), f))
+    lo, hi = (neighbor, t) if neighbor < t else (t, neighbor)
+    interior = list(range(lo + 1, hi))
+    if not interior:
+        return 0
+
+    n_frames = int(tracked_labels.shape[0])
+    centroids: dict[int, tuple[float, float]] = {}
+    for f in interior:
+        if f < 0 or f >= n_frames:
+            return 0
+        mask = np.asarray(tracked_labels[f] == cell_id)
+        c = _centroid_of(mask)
+        if c is None:
+            return 0
+        centroids[f] = c
+
+    for f, (cy, cx) in centroids.items():
+        add_correction(
+            nucleus_dir,
+            Correction(cell_id=cell_id, t=f, kind="anchor", y=cy, x=cx),
+        )
+    return len(centroids)

itasc-0.2.0.dev0.data/data/itasc/napari.yaml

@@ -0,0 +1,45 @@
+name: itasc
+display_name: ITASC
+contributions:
+  commands:
+    - id: itasc.main_widget
+      title: "ITASC"
+      python_name: itasc.napari:ITASCWidget
+    # The full install folds the extracted tools' widgets into this single
+    # manifest. npe2 requires a manifest's name to match the providing
+    # distribution, so the standalone itasc-cellpose / itasc-tracking /
+    # itasc-aggregate manifests cannot be re-registered from the itasc
+    # distribution; their contributions are mirrored here instead. The integrated
+    # ITASC app's own per-stage widgets (Cellpose map-building, Cell
+    # Segmentation) live inside the ITASC widget above and are not exposed as
+    # separate menu entries.
+    #
+    # The itasc-cellpose distribution's *standalone* surface — native-mask
+    # segment + laptrack track + embedded basic correction. It is not part of the
+    # integrated pipeline (the pipeline uses the Cellpose widget above); it is
+    # mirrored here only so the full install can also reach the standalone tool.
+    - id: itasc.cellpose_segment_track_widget
+      title: "Cellpose Segment + Track"
+      python_name: itasc.napari.cellpose_segment_track_widget:make_cellpose_segment_track_widget
+    - id: itasc.nucleus_tracking_widget
+      title: "Ultrack Segment + Track"
+      python_name: itasc.napari.nucleus_workflow_widget:make_nucleus_tracking_widget
+    # The ITASC Aggregate app: the full catalog UI restricted to the
+    # Contact Analysis stage + Aggregate capstone (three-dot rail: cell labels,
+    # nucleus labels, contact analysis). Both the full install and the standalone
+    # itasc-aggregate wheel resolve this same factory; the standalone simply
+    # lacks the upstream segmentation/tracking distributions, so it always comes
+    # up contact-only. In the full install this is the slim aggregate-focused
+    # entry alongside the complete ITASC widget above.
+    - id: itasc.contact_analysis_widget
+      title: "ITASC Aggregate"
+      python_name: itasc.napari.main_widget:make_aggregate_app_widget
+  widgets:
+    - command: itasc.main_widget
+      display_name: "ITASC"
+    - command: itasc.cellpose_segment_track_widget
+      display_name: "Cellpose Segment + Track"
+    - command: itasc.nucleus_tracking_widget
+      display_name: "Ultrack Segment + Track"
+    - command: itasc.contact_analysis_widget
+      display_name: "ITASC Aggregate"

itasc-0.2.0.dev0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: itasc
+Version: 0.2.0.dev0
+Summary: Fast, interactive cell tracking
+Project-URL: Homepage, https://github.com/ArturRuppel/ITASC
+Project-URL: Repository, https://github.com/ArturRuppel/ITASC
+Project-URL: Issues, https://github.com/ArturRuppel/ITASC/issues
+Author-email: Artur Ruppel <artur@ruppel.pro>
+License: AGPL-3.0
+License-File: LICENSE
+Keywords: cell-tracking,microscopy,napari,segmentation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: napari
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Requires-Dist: h5py
+Requires-Dist: matplotlib>=3.9.4
+Requires-Dist: napari[all]>=0.4.18
+Requires-Dist: numba
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pyarrow
+Requires-Dist: pydantic
+Requires-Dist: pymaxflow>=1.3.2
+Requires-Dist: pyqtgraph>=0.13
+Requires-Dist: qtpy>=2.3.0
+Requires-Dist: scikit-image
+Requires-Dist: scipy
+Requires-Dist: seaborn>=0.13
+Requires-Dist: sqlalchemy
+Requires-Dist: tifffile
+Provides-Extra: all
+Requires-Dist: cellpose>=4.0; extra == 'all'
+Requires-Dist: torch; extra == 'all'
+Requires-Dist: torchvision; extra == 'all'
+Requires-Dist: ultrack; extra == 'all'
+Provides-Extra: cellpose
+Requires-Dist: cellpose>=4.0; extra == 'cellpose'
+Requires-Dist: torch; extra == 'cellpose'
+Requires-Dist: torchvision; extra == 'cellpose'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.1; extra == 'docs'
+Requires-Dist: myst-parser>=2; extra == 'docs'
+Requires-Dist: sphinx-autobuild>=2024.2; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'docs'
+Requires-Dist: sphinx-design>=0.5; extra == 'docs'
+Requires-Dist: sphinx>=7; extra == 'docs'
+Requires-Dist: sphinxcontrib-mermaid>=0.9; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'test'
+Provides-Extra: tracking
+Requires-Dist: ultrack; extra == 'tracking'
+Description-Content-Type: text/markdown
+
+# ITASC
+
+Segment, track, correct, and quantify cells in time-lapse microscopy, inside napari.
+
+ITASC (Interactive Tracking And Segmentation of Cells) takes raw time-lapse
+stacks to tracked, quantified cells. It segments each frame, links cells across
+time, lets you correct the result by hand where the automatics miss, and
+measures what the tracked cells do. It is a [napari](https://napari.org) plugin
+built for dense, motile monolayers, where segmentation and tracking are the hard
+part.
+
+<!-- hero-start -->
+<p align="center">
+  <img src="docs/_static/napari_timelapse_last.png"
+       alt="ITASC tracking a monolayer in napari" width="100%">
+</p>
+<!-- hero-end -->
+
+## What it does
+
+An ITASC run moves through four stages, each usable on its own:
+
+- **Segment** each frame with [Cellpose-SAM](https://github.com/MouseLand/cellpose).
+  For sparse, well-separated cells its masks are the result; for a dense
+  monolayer its probability and flow output becomes divergence images that
+  separate crowded, variable-shape cells and form the input the tracker runs on.
+- **Track** across time: [Ultrack](https://github.com/royerlab/ultrack) for
+  dense monolayers, [LapTrack](https://github.com/yfukai/laptrack) for sparse,
+  well-separated cells.
+- **Correct** tracks and labels interactively, with editing tools adapted from
+  [EpiCure](https://github.com/Image-Analysis-Hub/Epicure), where the automatic
+  result is wrong.
+- **Quantify** what the tracked cells do, in two outputs:
+  - cell-cell contacts and edges, identified and tracked through T1 transitions,
+    written to a self-describing HDF5 (`.h5`) file.
+  - aggregate analysis of tracked nuclei, cell bodies, and cell-cell contacts
+    (shape and dynamics over time), exported to `.csv` tables.
+
+## How it is organized
+
+ITASC comes in two forms.
+
+The **full app** is the integrated pipeline. A project is a directory with one
+subfolder per position, and the four stages hand off through the `.tif` and HDF5
+files on disk, so you can enter wherever your data already sits or pick up a
+project someone else started.
+
+The **solo distributions** are separate, smaller napari tools, each built for one
+job with its own interface: `itasc-cellpose` segments and tracks channels
+straight into viewer layers, `itasc-tracking` turns foreground and contour maps
+into corrected Ultrack tracks, and `itasc-aggregate` quantifies contacts and T1
+events from finished labels. They are not the full app with stages switched off:
+each ships only the code its job needs and a leaner interface to match.
+
+Pick the one that matches the data you have. Each row links to that tool's guide,
+which covers how to install it and how to use it.
+
+| If you have… | Reach for | It gives you |
+| --- | --- | --- |
+| **Dense, motile cells of varying shape** (a confluent monolayer), from raw stacks to quantified contacts | [itasc\[all\]](docs/manual/full-app.md) | The unified `ITASC` workflow widget, every stage end to end. |
+| **Sparse, well-separated cells** with a cell and/or nucleus marker, to segment and track one or both channels | [itasc-cellpose](docs/manual/cellpose.md) | A local Cellpose-SAM runner for segmentation, then `laptrack` linking across time, plus manual correction of tracks and masks (adapted from [EpiCure](https://github.com/Image-Analysis-Hub/Epicure)). One channel or two. |
+| **Foreground and contour maps already**, to skip the cellpose step | [itasc-tracking](docs/manual/tracking.md) | Ultrack candidate database, solving, browsing, and interactive segmentation and tracking correction. |
+| **Tracked cell labels already**, and you want the aggregate quantification | [itasc-aggregate](docs/manual/aggregate.md) | Cell-cell edges, border edges, and T1 events to HDF5, aggregate quantification to `.csv`. |
+| **Code to build on** | [itasc-core](docs/manual/core.md) | TIFF/path/label-IO helpers, the lineage model, and napari UI primitives. |
+
+## Built on
+
+ITASC reuses the published methods of four tools. If you use the stage that
+depends on one, please cite it:
+
+- **Cellpose-SAM** (segmentation): Pachitariu M, Rariden M, Stringer C.
+  *Cellpose-SAM: superhuman generalization for cellular segmentation.* bioRxiv
+  (2025). [doi:10.1101/2025.04.28.651001](https://doi.org/10.1101/2025.04.28.651001)
+  · [MouseLand/cellpose](https://github.com/MouseLand/cellpose)
+- **Ultrack** (dense tracking): Bragantini J, et al. *Ultrack: pushing the
+  limits of cell tracking across biological scales.* Nature Methods (2025).
+  [doi:10.1038/s41592-025-02778-0](https://doi.org/10.1038/s41592-025-02778-0)
+  · [royerlab/ultrack](https://github.com/royerlab/ultrack)
+- **LapTrack** (sparse tracking): Fukai YT, Kawaguchi K. *LapTrack: linear
+  assignment particle tracking with tunable metrics.* Bioinformatics 39(1),
+  btac799 (2023). [doi:10.1093/bioinformatics/btac799](https://doi.org/10.1093/bioinformatics/btac799)
+  · [yfukai/laptrack](https://github.com/yfukai/laptrack)
+- **EpiCure** (correction tools): Letort G. *EpiCure: a versatile and handy tool
+  for curation of epithelial segmentation.* bioRxiv (2026).
+  [doi:10.64898/2026.03.27.714683](https://doi.org/10.64898/2026.03.27.714683)
+  · [Image-Analysis-Hub/Epicure](https://github.com/Image-Analysis-Hub/Epicure)
+
+## Documentation
+
+- [User guide](docs/index.md): install, the staged workflow, and driving the
+  plugin.
+- [API reference](docs/api/index.md): the programmatic API, generated
+  from the source.
+
+## Status
+
+ITASC is approaching its first public release and JOSS submission. The four
+stages and the file-based project layout are settled and in active research use.
+Installation and the public API are close to final: expect small changes before
+the release and its accompanying manuscript.
+
+## Citing ITASC
+
+Cite the software using the metadata in [`CITATION.cff`](CITATION.cff). A DOI
+and manuscript citation will be added with the public release. For
+pre-publication citation questions, contact Artur Ruppel at `artur@ruppel.pro`.
+
+## License
+
+AGPL-3.0. See [`LICENSE`](LICENSE).
+
+## AI usage
+
+Generative AI tools (OpenAI GPT and Anthropic Claude) assisted with code
+drafting, refactoring, tests, debugging, and documentation. Human authors made
+the scientific, architectural, and design decisions, and are fully responsible
+for all code and other content in the repository.