{
  "name": "napari-cotrack",
  "display_name": "napari-cotrack",
  "visibility": "public",
  "icon": "",
  "categories": [],
  "schema_version": "0.2.1",
  "on_activate": null,
  "on_deactivate": null,
  "contributions": {
    "commands": [
      {
        "id": "napari-cotrack.make_widget",
        "title": "Open napari-cotrack panel",
        "python_name": "napari_cotrack.plugin:NapariCotrackWidget",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      }
    ],
    "readers": null,
    "writers": null,
    "widgets": [
      {
        "command": "napari-cotrack.make_widget",
        "display_name": "napari-cotrack",
        "autogenerate": false
      }
    ],
    "sample_data": null,
    "themes": null,
    "menus": {},
    "submenus": null,
    "keybindings": null,
    "configuration": []
  },
  "package_metadata": {
    "metadata_version": "2.4",
    "name": "napari-cotrack",
    "version": "0.1.7",
    "dynamic": null,
    "platform": null,
    "supported_platform": null,
    "summary": "Anchor-based keypoint tracking through CoTracker3, as a napari plugin.",
    "description": "# napari-cotrack\n\nA napari plugin for **anchor-based keypoint tracking through CoTracker3**.\nLabel a few frames in napari; CoTracker3 propagates those keypoints across\nthe rest of the video; iterate by fixing wrong predictions and re-running.\n\n## Install\n\nThe recommended path on every platform is the one-shot bootstrap script. It\ninstalls [`uv`](https://docs.astral.sh/uv/) if you don't already have it, then\n`uv tool install napari-cotrack` — putting `napari-cotrack` on your PATH and\nfetching the ~1.5 GB of Python deps (torch, napari, cv2, …) on first run.\n\n**macOS / Linux:**\n```bash\ncurl -LsSf https://raw.githubusercontent.com/RaulSimpetru/napari-cotrack/main/scripts/install.sh | bash\n```\n\n**Windows (PowerShell):**\n```powershell\nirm https://raw.githubusercontent.com/RaulSimpetru/napari-cotrack/main/scripts/install.ps1 | iex\n```\n\nThen run `napari-cotrack`. To upgrade later: `uv tool upgrade napari-cotrack`.\n\n### Already have uv?\n```bash\nuv tool install napari-cotrack\nnapari-cotrack\n```\n\n### Working in a clone of the repo?\n```bash\nuv sync\nuv run napari-cotrack\n```\n\n### Optional: install ffmpeg for the fast extract-all path\n\nStage 4's \"Extract all frames\" runs in a single ffmpeg pass (~10–50× faster on\nH.264 sources) when ffmpeg is on `PATH`, otherwise falls back to a per-frame\nimageio loop.\n\n| OS | Install ffmpeg |\n|---|---|\n| macOS | `brew install ffmpeg` |\n| Ubuntu / Debian | `sudo apt install ffmpeg` |\n| Windows | `winget install ffmpeg` (or download from gyan.dev) |\n\n## Tested platforms\n\n- **macOS arm64 (Apple Silicon)** — primary development target, end-to-end\n  tested on a real 1500-frame project.\n- **Linux x86_64** and **Windows x86_64** — code is portable (PyQt6 +\n  pathlib + ffmpeg subprocess + napari thread_worker), all deps publish\n  wheels for these platforms, but I haven't run the GUI on them.\n  Open an issue if anything breaks — should be a small fix.\n\n## The five-stage loop\n\nThe dock widget mirrors the loop:\n\n1. **Extract anchor frames** — every Nth frame, or top K most diverse via\n   k-means on RGB histograms.\n2. **Label keypoints** — load anchors into the viewer and click them in.\n   One Points layer named `labels`, colour driven by a `bodypart` property.\n   Click moves an existing point at the same `(frame, bodypart)` instead\n   of duplicating, then auto-advances to the next bodypart.\n3. **Track with CoTracker3** — propagates labels (anchors + every\n   `corrections/round_*` folder) across the whole video. Runs in a napari\n   `thread_worker`, log streams into the dock pane.\n4. **Review and fix** — extract every video frame as PNG (ffmpeg fast path\n   if available), load them into napari, fix wrong predictions, **Promote**\n   to write only the changed rows into a new `corrections/round_NNN/`. Or\n   detect scene-confusion jumps and extract a representative frame per bad\n   range.\n5. **Render and inspect** — Hampel + 1€ filter, then the cv2 overlay\n   renderer with bodypart trails. `Play with ffplay` on the result.\n\nRe-running stage 3 after a correction round folds those new labels in\nautomatically.\n\n## On-disk format\n\nA project is a directory ending in `.naparitracker/`:\n\n```\n<name>.naparitracker/\n  project.toml          # video path, bodyparts, per-stage knobs\n  anchors/\n    img0023.png ...\n    labels.csv          # long-form: frame,bodypart,x,y,vis\n  corrections/\n    round_001/labels.csv\n    round_002/labels.csv\n  tracks.csv            # dense: every (frame, bodypart)\n  tracks_filtered.csv\n  overlay.mp4\n  review/\n    img0000.png ...\n    labels.csv          # prefilled from tracks.csv\n    baseline.csv        # snapshot for diff-promote\n```\n\n`project.toml` is hand-editable TOML. Every stage's knobs version with the\nproject, so `git diff` on `project.toml` shows what changed.\n\n## Headless CLIs\n\nEvery stage is also a module CLI for batch / scripted use:\n\n```bash\nuv run python -m napari_cotrack.pipeline.extract anchors \\\n    --video VIDEO --output PROJECT/anchors \\\n    --bodyparts thumb,index,middle,ring,wrist \\\n    --mode diverse --n 30\n\nuv run python -m napari_cotrack.pipeline.track    --project PROJECT\nuv run python -m napari_cotrack.pipeline.filter   --project PROJECT\nuv run python -m napari_cotrack.pipeline.render   --project PROJECT\nuv run python -m napari_cotrack.pipeline.review extract-all --project PROJECT --force\nuv run python -m napari_cotrack.pipeline.review promote     --project PROJECT\nuv run python -m napari_cotrack.pipeline.review jumps       --project PROJECT [--extract-corrections]\n```\n\nAll accept `--verbose` for per-chunk / per-bodypart detail.\n\n## Tests\n\n```bash\nuv run python -m pytest tests/\n```\n\nCovers extract uniform/diverse, label-CSV union semantics, sparse-frame\nmapping, CSV round-trip. Stage 3 (track) needs a real GPU + checkpoint;\nsmoke against the synthetic fixture in `tests/_make_fixture.py`.\n\n## Keyboard\n\nWhile editing in napari:\n- **N** / **Shift+N** — next / previous bodypart (avoids napari's\n  default Tab/Up/Down)\n- **Ctrl+S** / **Cmd+S** — save labels.csv\n- **Right** / **Left** — next / prev frame (napari default)\n- **Delete** — remove selected points (napari default)\n\nSave also fires automatically when you close napari, as a safety net.\n",
    "description_content_type": "text/markdown",
    "keywords": "cotracker,keypoints,napari,napari-plugin,tracking",
    "home_page": null,
    "download_url": null,
    "author": null,
    "author_email": "\"Raul C. Simpetru\" <raul.simpetru@fau.de>",
    "maintainer": null,
    "maintainer_email": null,
    "license": "MIT",
    "classifier": [
      "Development Status :: 4 - Beta",
      "Framework :: napari",
      "Intended Audience :: Science/Research",
      "License :: OSI Approved :: MIT License",
      "Operating System :: MacOS",
      "Operating System :: POSIX :: Linux",
      "Programming Language :: Python :: 3 :: Only",
      "Programming Language :: Python :: 3.12",
      "Topic :: Scientific/Engineering :: Image Processing"
    ],
    "requires_dist": [
      "einops>=0.8",
      "imageio[ffmpeg]>=2.37",
      "matplotlib>=3.10",
      "napari>=0.5",
      "numpy>=2.4",
      "opencv-python>=4.10",
      "pandas>=3.0",
      "pyqt6>=6.7",
      "scikit-learn>=1.5",
      "scipy>=1.17",
      "tomli-w>=1.2",
      "torch>=2.11",
      "torchvision>=0.26",
      "tqdm>=4.65"
    ],
    "requires_python": ">=3.12",
    "requires_external": null,
    "project_url": [
      "Homepage, https://github.com/RaulSimpetru/napari-cotrack",
      "Repository, https://github.com/RaulSimpetru/napari-cotrack",
      "Issues, https://github.com/RaulSimpetru/napari-cotrack/issues",
      "Changelog, https://github.com/RaulSimpetru/napari-cotrack/releases"
    ],
    "provides_extra": null,
    "provides_dist": null,
    "obsoletes_dist": null
  },
  "npe1_shim": false
}