tailcyclenet 0.0.1__tar.gz

tailcyclenet-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, HHMI Janelia
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tailcyclenet-0.0.1/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: tailcyclenet
+Version: 0.0.1
+Summary: finetune a posetail tracker into an animal pose estimator (3D multiview, 3D single-view, 2D single-view)
+License-Expression: BSD-3-Clause
+Project-URL: Repository, https://github.com/AI-HHMI/tailcyclenet
+Keywords: animal pose estimation,3d tracking,multi-view,posetail
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: posetail==0.4.1
+Requires-Dist: torch<3,>=2
+Requires-Dist: einops
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy
+Requires-Dist: pyarrow
+Requires-Dist: av>=12
+Requires-Dist: tqdm
+Dynamic: license-file
+
+# tailcyclenet
+
+Finetune a [posetail](https://pypi.org/project/posetail/) point tracker into an animal pose
+estimator. Three settings, one model: **3D multiview**, **3D single-view**, **2D single-view**.
+
+The pipeline detects animals, crops them, and decodes per-keypoint poses through a single window
+loop. It reads one annotation format (`docs/annotation_format.md`) that serves both hand annotation
+and bulk training across datasets of differing keypoint sets, camera counts, and dimensionality.
+This README is the committed reference: what this is, how to run it, and the invariants a
+contributor must not break.
+
+---
+
+## Setup
+
+Dependencies are managed with [pixi](https://pixi.sh). `posetail==0.3.5` is pinned from PyPI.
+
+```bash
+pixi install
+pixi run python -c "import posetail, tailcyclenet"   # sanity check
+pixi run test                                        # test suite
+pixi run lint                                        # ruff
+```
+
+- The `LD_LIBRARY_PATH` prepend in `pyproject.toml` is load-bearing — the env ships a newer
+  `libstdc++` than some hosts, and without it `import scipy.optimize` dies naming only `CXXABI`.
+- posetail >= 0.3.5 ships every behaviour this repo once monkeypatched (per-frame camera offsets,
+  `crop_box_for_points`, `scene_features=`/`input_size=` on the tracker forward); there is no patch
+  layer anymore.
+
+---
+
+## Layout
+
+```
+tailcyclenet/     library: format, dataset, crop rule, model, inference, metrics, detector
+scripts/          train.py  train_detector.py  infer.py  eval.py  convert_*.py
+configs/          base.toml + 2d.toml + 3d.toml + detector.toml (extends one level deep)
+configs/datasets/ per-dataset keypoint and skeleton definitions
+docs/             annotation_format.md — the data format spec (human-owned)
+tests/            invariants (crop rule, converters, geometry)
+```
+
+---
+
+## Training
+
+One estimator trains across every dataset root under `[data].path`; a keypoint embedding table is
+what lets roots with different keypoint sets share a model.
+
+```bash
+# 3D (multiview / single-view)
+pixi run python scripts/train.py --config configs/3d.toml --data <root>
+
+# 2D (single-view)
+pixi run python scripts/train.py --config configs/2d.toml --data <root>
+
+# one node, N gpus: one item per rank, gradients averaged by DDP
+pixi run python scripts/train.py --config configs/3d.toml --data <root> --devices 4
+```
+
+Facts that are easy to get wrong:
+
+- The two configs differ in exactly three keys — `cams_to_sample`, `val_cams_to_sample`,
+  `prob_2d_only` — all camera-count questions a one-camera root cannot ask. `n_keypoints` is
+  **derived from the data, never configured**.
+- The per-rank batch is structurally **1**; `--devices N` is the only batch dimension this repo has.
+  Every iteration count in a config is a **total across ranks** (60,000 is 60,000 samples on any
+  gpu count) and the learning rate is scaled by `sqrt(N)`, so a multi-gpu run is two levers off a
+  single-gpu one; `provenance.toml` records which it was.
+- `[model].gridresid_offset` has **no default and must be stated** — the two values load the same
+  tensors, so a mismatch produces numbers rather than an exception.
+- A run folder writes `keypoint_registry.toml` (the derived keypoint axis) and `provenance.toml`
+  (commit + dirty flag). A config is not a provenance record.
+- The video encoder unfreezes mid-run per `[model].video_encoder_requires_grad` (a bool, or an int
+  iteration to unfreeze at). A run started before the shipped default (8 blocks at 10,000) is not
+  comparable to one after; `false` restores the old arm.
+
+---
+
+## Detector
+
+```bash
+pixi run python scripts/train_detector.py --config configs/detector.toml
+```
+
+The recipe lives in the config, not on the CLI — every default is there with its evidence, and an
+unknown key raises rather than silently training at a default. Only `--out`, `--iters` and
+`--device` override.
+
+One detector per dataset, and `input_wh` defaults to an aspect-matched size rather than a square:
+a square letterbox on a wide frame wastes most of the canvas and can put the animal below the stride
+the FPN can represent. The regression target is `crop.crop_box_for_points` — the detector
+reproduces *the crop the pose model was trained on*, so `[data].boxes` must equal the pose run's
+`[data].box_source`.
+
+---
+
+## Inference and eval
+
+```bash
+# one source session (a dataset root works only if it holds a single session in --split)
+pixi run python scripts/infer.py --run runs/<name> --data <session-dir> --split test \
+    --detector runs/det-<name> --out pred/
+
+# or, straight off raw footage + an anipose calibration
+pixi run python scripts/infer.py --run runs/<name> --out pred/ \
+    --videos rec/ --calibration anipose/calibration.toml --cam-regex 'cam([0-9]+)_' \
+    --detector runs/det-<name> --max-animals 4
+
+pixi run python scripts/eval.py pred/ --data <root> --split test --chunk 500
+```
+
+- **`--out` is a prediction session directory** (`session.toml`, `calibration.toml`, `groups.pq`,
+  `points3d.pq`, `keypoints.pq`, `instances.pq`, `windows.pq`), written a block at a time so nothing
+  is proportional to clip length. `eval.py` and `render.py` both read it; `render.py` finds its own
+  pixels via the session's `[provenance]`.
+- **`--data` and `--videos` are exactly-one-of**, and a run is **one source session** (which may
+  hold many groups). For `--videos`, the camera name is the regex **capture group** and the session
+  is built in memory — nothing is staged.
+- There is **one** window loop. Box sources: annotations, a detections npz (`--boxes`), or a
+  per-dataset detector (`--detector`). Prompt regimes: `none` (query-free), `carry` (previous
+  window's own prediction — what deployment does), `self` (two passes), `labels` (an oracle, gated
+  off by default).
+
+**Defaults are not the recommendation.** The good settings are root-conditional, so sweep them per
+root. Current values: `--anchor carry`, `--overlap 4`, `--refine` derived (on 3D / off 2D),
+`--track on`, `--box-prompt auto`, `--prefetch-windows 1` (bit-exact, performance only),
+`--max-ram` derived from the host. In particular `--anchor` is root-conditional in 2D (a carried
+prior on a crowded root is often the wrong animal's pose) and `--overlap`'s optimum is seam-count
+against seam-size — sweep per root.
+
+Four rules that are *not* root-conditional:
+
+- **`--vis-thresh` has no meaning in 2D at the shipped default** — the visibility head is only
+  trained when `[training.losses].vis_loss_2d_weight` is nonzero (default `0.0`).
+- **`--box-prompt auto` needs a detector or boxes file.** A box-model run without one refuses rather
+  than silently falling back to the GT oracle. Pass `--detector`/`--boxes`, or `--box-prompt none`
+  to withhold the box.
+- Always run `eval.py` with `--chunk 500` on long clips — the bootstrap resamples groups, so a
+  single long clip returns `DEGENERATE`.
+- Use `--min-match-kpts 0.5` for deltas and `0` for absolutes.
+
+The largest lever is not a flag: pose accuracy on a ground-truth crop is far better, at full
+coverage, than through the detector, and on a long clip essentially all coverage loss is `no box`.
+Fix the crop path before tuning identity flags.
+
+---
+
+## Reference
+
+- `docs/annotation_format.md` — the data format spec (human-owned).

tailcyclenet-0.0.1/README.md

@@ -0,0 +1,152 @@
+# tailcyclenet
+
+Finetune a [posetail](https://pypi.org/project/posetail/) point tracker into an animal pose
+estimator. Three settings, one model: **3D multiview**, **3D single-view**, **2D single-view**.
+
+The pipeline detects animals, crops them, and decodes per-keypoint poses through a single window
+loop. It reads one annotation format (`docs/annotation_format.md`) that serves both hand annotation
+and bulk training across datasets of differing keypoint sets, camera counts, and dimensionality.
+This README is the committed reference: what this is, how to run it, and the invariants a
+contributor must not break.
+
+---
+
+## Setup
+
+Dependencies are managed with [pixi](https://pixi.sh). `posetail==0.3.5` is pinned from PyPI.
+
+```bash
+pixi install
+pixi run python -c "import posetail, tailcyclenet"   # sanity check
+pixi run test                                        # test suite
+pixi run lint                                        # ruff
+```
+
+- The `LD_LIBRARY_PATH` prepend in `pyproject.toml` is load-bearing — the env ships a newer
+  `libstdc++` than some hosts, and without it `import scipy.optimize` dies naming only `CXXABI`.
+- posetail >= 0.3.5 ships every behaviour this repo once monkeypatched (per-frame camera offsets,
+  `crop_box_for_points`, `scene_features=`/`input_size=` on the tracker forward); there is no patch
+  layer anymore.
+
+---
+
+## Layout
+
+```
+tailcyclenet/     library: format, dataset, crop rule, model, inference, metrics, detector
+scripts/          train.py  train_detector.py  infer.py  eval.py  convert_*.py
+configs/          base.toml + 2d.toml + 3d.toml + detector.toml (extends one level deep)
+configs/datasets/ per-dataset keypoint and skeleton definitions
+docs/             annotation_format.md — the data format spec (human-owned)
+tests/            invariants (crop rule, converters, geometry)
+```
+
+---
+
+## Training
+
+One estimator trains across every dataset root under `[data].path`; a keypoint embedding table is
+what lets roots with different keypoint sets share a model.
+
+```bash
+# 3D (multiview / single-view)
+pixi run python scripts/train.py --config configs/3d.toml --data <root>
+
+# 2D (single-view)
+pixi run python scripts/train.py --config configs/2d.toml --data <root>
+
+# one node, N gpus: one item per rank, gradients averaged by DDP
+pixi run python scripts/train.py --config configs/3d.toml --data <root> --devices 4
+```
+
+Facts that are easy to get wrong:
+
+- The two configs differ in exactly three keys — `cams_to_sample`, `val_cams_to_sample`,
+  `prob_2d_only` — all camera-count questions a one-camera root cannot ask. `n_keypoints` is
+  **derived from the data, never configured**.
+- The per-rank batch is structurally **1**; `--devices N` is the only batch dimension this repo has.
+  Every iteration count in a config is a **total across ranks** (60,000 is 60,000 samples on any
+  gpu count) and the learning rate is scaled by `sqrt(N)`, so a multi-gpu run is two levers off a
+  single-gpu one; `provenance.toml` records which it was.
+- `[model].gridresid_offset` has **no default and must be stated** — the two values load the same
+  tensors, so a mismatch produces numbers rather than an exception.
+- A run folder writes `keypoint_registry.toml` (the derived keypoint axis) and `provenance.toml`
+  (commit + dirty flag). A config is not a provenance record.
+- The video encoder unfreezes mid-run per `[model].video_encoder_requires_grad` (a bool, or an int
+  iteration to unfreeze at). A run started before the shipped default (8 blocks at 10,000) is not
+  comparable to one after; `false` restores the old arm.
+
+---
+
+## Detector
+
+```bash
+pixi run python scripts/train_detector.py --config configs/detector.toml
+```
+
+The recipe lives in the config, not on the CLI — every default is there with its evidence, and an
+unknown key raises rather than silently training at a default. Only `--out`, `--iters` and
+`--device` override.
+
+One detector per dataset, and `input_wh` defaults to an aspect-matched size rather than a square:
+a square letterbox on a wide frame wastes most of the canvas and can put the animal below the stride
+the FPN can represent. The regression target is `crop.crop_box_for_points` — the detector
+reproduces *the crop the pose model was trained on*, so `[data].boxes` must equal the pose run's
+`[data].box_source`.
+
+---
+
+## Inference and eval
+
+```bash
+# one source session (a dataset root works only if it holds a single session in --split)
+pixi run python scripts/infer.py --run runs/<name> --data <session-dir> --split test \
+    --detector runs/det-<name> --out pred/
+
+# or, straight off raw footage + an anipose calibration
+pixi run python scripts/infer.py --run runs/<name> --out pred/ \
+    --videos rec/ --calibration anipose/calibration.toml --cam-regex 'cam([0-9]+)_' \
+    --detector runs/det-<name> --max-animals 4
+
+pixi run python scripts/eval.py pred/ --data <root> --split test --chunk 500
+```
+
+- **`--out` is a prediction session directory** (`session.toml`, `calibration.toml`, `groups.pq`,
+  `points3d.pq`, `keypoints.pq`, `instances.pq`, `windows.pq`), written a block at a time so nothing
+  is proportional to clip length. `eval.py` and `render.py` both read it; `render.py` finds its own
+  pixels via the session's `[provenance]`.
+- **`--data` and `--videos` are exactly-one-of**, and a run is **one source session** (which may
+  hold many groups). For `--videos`, the camera name is the regex **capture group** and the session
+  is built in memory — nothing is staged.
+- There is **one** window loop. Box sources: annotations, a detections npz (`--boxes`), or a
+  per-dataset detector (`--detector`). Prompt regimes: `none` (query-free), `carry` (previous
+  window's own prediction — what deployment does), `self` (two passes), `labels` (an oracle, gated
+  off by default).
+
+**Defaults are not the recommendation.** The good settings are root-conditional, so sweep them per
+root. Current values: `--anchor carry`, `--overlap 4`, `--refine` derived (on 3D / off 2D),
+`--track on`, `--box-prompt auto`, `--prefetch-windows 1` (bit-exact, performance only),
+`--max-ram` derived from the host. In particular `--anchor` is root-conditional in 2D (a carried
+prior on a crowded root is often the wrong animal's pose) and `--overlap`'s optimum is seam-count
+against seam-size — sweep per root.
+
+Four rules that are *not* root-conditional:
+
+- **`--vis-thresh` has no meaning in 2D at the shipped default** — the visibility head is only
+  trained when `[training.losses].vis_loss_2d_weight` is nonzero (default `0.0`).
+- **`--box-prompt auto` needs a detector or boxes file.** A box-model run without one refuses rather
+  than silently falling back to the GT oracle. Pass `--detector`/`--boxes`, or `--box-prompt none`
+  to withhold the box.
+- Always run `eval.py` with `--chunk 500` on long clips — the bootstrap resamples groups, so a
+  single long clip returns `DEGENERATE`.
+- Use `--min-match-kpts 0.5` for deltas and `0` for absolutes.
+
+The largest lever is not a flag: pose accuracy on a ground-truth crop is far better, at full
+coverage, than through the detector, and on a long clip essentially all coverage loss is `no box`.
+Fix the crop path before tuning identity flags.
+
+---
+
+## Reference
+
+- `docs/annotation_format.md` — the data format spec (human-owned).

tailcyclenet-0.0.1/pyproject.toml

@@ -0,0 +1,129 @@
+[build-system]
+requires = ["setuptools>=64,<81", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tailcyclenet"
+version = "0.0.1"
+description = "finetune a posetail tracker into an animal pose estimator (3D multiview, 3D single-view, 2D single-view)"
+requires-python = ">=3.11"
+readme = "README.md"
+license = "BSD-3-Clause"
+keywords = ["animal pose estimation", "3d tracking", "multi-view", "posetail"]
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "posetail==0.4.1",
+    "torch>=2,<3",
+    "einops",
+    "numpy>=1.26",
+    "scipy",
+    "pyarrow",
+    "av>=12",
+    "tqdm",
+]
+
+[project.urls]
+Repository = "https://github.com/AI-HHMI/tailcyclenet"
+
+[tool.setuptools]
+packages = ["tailcyclenet", "tailcyclenet.detector", "tailcyclenet.infer"]
+
+[tool.pixi.system-requirements]
+libc = { family = "glibc", version = "2.34" }
+
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64"]
+
+[tool.pixi.activation.env]
+# The env ships libstdc++.so.6.0.35, the host may ship 6.0.29 with no CXXABI_1.3.15 -- without
+# this the system copy wins the loader search and `import scipy.optimize` dies inside _highspy.
+LD_LIBRARY_PATH = "$PIXI_PROJECT_ROOT/.pixi/envs/default/lib:$LD_LIBRARY_PATH"
+
+# The env and repo both live on NFS, so a cold import pays ~2x NFS round-trips per module
+# (torch's ~500 modules dominate startup); PYTHONPYCACHEPREFIX redirects the bytecode cache to a
+# local path, which also survives reboots. Unset it to restore upstream behaviour.
+PYTHONPYCACHEPREFIX = "${HOME}/.cache/tailcyclenet/pycache"
+
+# A loader worker's per-item frame-buffer churn grows glibc's arenas unboundedly in a standalone
+# probe and flat under this cap; live, it made no measurable difference either way, but it is the
+# one arm with independent evidence behind it.
+MALLOC_ARENA_MAX = "2"
+
+[tool.pixi.pypi-dependencies]
+# posetail is a LIBRARY here, never modified: pinned to the PyPI release (a checkout lives at
+# ../posetail-next for READING only). 0.4.1 lands every workaround this repo carried -- the
+# cube.py patches, crop_box_for_points, input_size=/scene_features=, T=1 guard, occlusion/vis guards --
+# and adds loading packaged TrackerEncoder weights from Hugging Face.
+posetail = "==0.4.1"
+# The pytorch branch, not PyPI's 0.8.0: its Camera is an nn.Module whose projection,
+# triangulation and Jacobians are torch ops, so camera geometry runs on GPU with the model.
+# Declares itself 0.7.2, satisfying posetail's `aniposelib>=0.7.0`.
+aniposelib = { git = "https://github.com/lambdaloop/anipose-lib.git", branch = "pytorch" }
+tailcyclenet = { path = ".", editable = true }
+torch = { version = "<3", index = "https://download.pytorch.org/whl/cu128" }
+torchvision = { version = "*", index = "https://download.pytorch.org/whl/cu128" }
+torchaudio = { version = "*", index = "https://download.pytorch.org/whl/cu128" }
+# A2: the DINOv3 torch.hub repo's own logging module imports this unconditionally
+# (dinov3/logging/__init__.py) -- not a DINOv3 model dependency per se, just a hard import in
+# the hub checkout, so it has to be present before `torch.hub.load('facebookresearch/dinov3', ...)`
+# can even build the module tree.
+termcolor = "*"
+
+[tool.pixi.feature.dev.dependencies]
+python-build = "*"
+twine = "*"
+
+[tool.pixi.environments]
+default = { solve-group = "default" }
+dev = { features = ["dev"], solve-group = "default" }
+
+[tool.pixi.dependencies]
+python = "3.11.*"
+cuda-toolkit = "12.8.*"
+numpy = "==1.26"
+scipy = "<1.17"
+setuptools = "<81"
+pip = "*"
+pyarrow = "*"
+matplotlib = "*"
+pytest = "*"
+# noarch, pure python, needs only pytest + execnet, so it cannot collide with the exact pins
+# below; it parallelises the 29 model builds that dominate the suite.
+pytest-xdist = "*"
+# `--timeout=N` for a suite whose failure mode is a HANG (a loader futex deadlock when anything
+# decodes video before the workers fork), not an assertion. noarch/pure-python like xdist. Not
+# applied by default: the model-building tests are legitimately slow and a global cap would flake.
+pytest-timeout = "*"
+# noarch and pure python, like xdist and timeout above, so it cannot collide with the exact pins
+# the note below is about.
+ruff = "*"
+av = ">=18.0.0,<19"
+# Deliberately NOT listed: toml, opencv, pillow, wandb, schedulefree. posetail pins them
+# EXACTLY and is itself pinned, so the versions are already determined in pixi.lock; re-declaring
+# duplicates a pin that conflicts the moment posetail moves, or asks for `*` and conflicts
+# immediately. If posetail ever drops one, add it here at posetail's own version. Video decoding
+# is provided directly by PyAV above.
+
+[tool.pixi.tasks]
+# `-n 8`, default per-test distribution (loadfile pins all 29 model builds to one worker and the
+# wall clock barely moves); each worker re-pays the ~14 s torch import, which is the floor.
+test = "pytest tests/ -q -n 8"
+lint = "ruff check . && python scripts/lint_comments.py"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = ["scratch", "dev"]
+
+# Pinned, not ruff's default: 0.16 widened the implied set to autofix rules that rewrite import
+# blocks and dict() calls repo-wide. Widening it is a deliberate act with its own diff.
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tailcyclenet-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tailcyclenet-0.0.1/setup.py

@@ -0,0 +1,5 @@
+from setuptools import setup
+
+# All metadata lives in pyproject.toml [project]. Keep discovery explicit: the repository
+# also contains large data and environment directories that make recursive discovery slow.
+setup(packages=["tailcyclenet", "tailcyclenet.detector", "tailcyclenet.infer"])

tailcyclenet-0.0.1/tailcyclenet/__init__.py

@@ -0,0 +1,11 @@
+"""tailcyclenet -- posetail finetuned into an animal pose estimator.
+
+No monkeypatching: posetail >= 0.3.5 ships every behaviour this repo once had to patch in.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("tailcyclenet")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"