{"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}