Stacked on #560 (PR 24).

Closes #98 — centroid-only inference is the first new user-facing capability after the inference refactor (PRs 0–24 were all parity-preserving).

Two changes in one PR

1. Centroid-only inference (the feature)

• Predictor.from_model_paths now accepts a centroid-only model_paths list and returns a Predictor whose layer is a bare CentroidLayer. Auto-detected when only "centroid" is among the detected model types.
• Outputs.to_instances / to_labels accept an anchor_ind kwarg. When pred_keypoints is None but pred_centroids is populated, the centroid is packaged into a PredictedInstance with the coordinate at the anchor slot (or node 0 if unset) and NaN at every other node. Per-instance score = centroid confidence.
• Predictor._packaging_anchor_ind() resolves the slot from self.layer.anchor_ind when the layer is a CentroidLayer; None otherwise.
• --centroid-only CLI flag (with --centroid_only underscore variant) for the case where both centroid + centered-instance models are configured but the user wants centroid-only output. Routes through from_model_paths(centroid_only=True).
• FilterPipeline emits a UserWarning and falls back to IoU when overlapping_method='oks' is requested on centroid-only outputs (OKS needs keypoints).
• docs/guides/centroid-only-inference.md documents the NaN semantics, anchor-node convention, and interaction with filters / tracking / metrics.

2. Anchor-default convention: bbox-midpoint → mean of visible nodes

Per-user-request, the project-wide convention for "what's the centroid when anchor_part isn't set, or the anchor node isn't visible" is changed from bounding-box midpoint to the NaN-ignoring mean of all visible nodes.

• sleap_nn/data/instance_centroids.py: new find_points_mean helper. generate_centroids now uses it for both the no-anchor and missing-anchor fallback paths.
• find_points_bbox_midpoint retained for callers that explicitly want bbox-midpoint behavior.
• Docstrings updated in config/model_config.py, inference/topdown.py, inference/layers/centroid.py.
• Both training (via custom_datasets) and inference (via CentroidLayer + legacy CentroidCrop) pick up the change automatically — they share the same generate_centroids helper.

Behavior shift to call out for review. Centroid models trained on the old bbox-midpoint convention will see a slightly different GT centroid target whenever the anchor node is missing for an instance. For symmetric instances the two are identical; for asymmetric ones (long tails, sprawled limbs) they differ by up to a few pixels. Re-training is recommended only when anchor_part was unset in the original training config.

Test plan

• pytest tests/data/test_instance_centroids.py — 3 passed (1 new — confirms mean ≠ bbox-midpoint on skewed instances; 1 new — find_points_mean ignores NaN).
• pytest tests/inference/test_centroid_only.py — 9 passed (factory auto-detect; anchor=None default; explicit anchor_ind; per-instance score; out-of-range raise; .slp round-trip; OKS-warn + IoU-fallback; IoU silent; tracking-via-centroids smoke).
• pytest tests/cli/test_centroid_only_cli.py — 4 passed (--centroid-only in --help; flag → factory kwarg; default-off; underscore variant accepted).
• pytest tests/inference/ tests/cli/ tests/data/test_instance_centroids.py — 404 passed, 23 skipped (CUDA-gated).
• pytest tests/data/ — 104 passed (full data suite — confirms anchor-default change doesn't regress training pipeline).
• pytest tests/test_predict.py tests/inference/test_topdown.py — 20 passed (legacy run_inference + legacy CentroidCrop paths still work with the new mean-of-nodes fallback).
• black --check sleap_nn tests — clean.
• ruff check sleap_nn/ — clean.

Anchor-slot decision

When packaging centroid-only Outputs into a PredictedInstance, we have to pick one skeleton-node index to receive the centroid coordinate (sleap-io has no "mean of nodes" slot in PredictedInstance). The packaging slot defaults to node 0 when anchor_part is unset — distinct from the centroid value fallback (mean of visible nodes). These are different concerns: the value is "what's the centroid here?", the slot is "where in the output array does it go?".

Files

Modified:

• sleap_nn/data/instance_centroids.py — new find_points_mean; generate_centroids uses it.
• sleap_nn/inference/factory.py — _select_layer accepts centroid-only; from_model_paths(centroid_only=True) forces dispatch.
• sleap_nn/inference/outputs.py — to_instances / to_labels accept anchor_ind; new _to_instances_centroid_only.
• sleap_nn/inference/predictor.py — _packaging_anchor_ind + _to_labels threads it through.
• sleap_nn/inference/filters.py — OKS-on-centroid-only warn + IoU fallback.
• sleap_nn/cli.py — --centroid-only flag wired into both _run_in_memory_new_flow and _run_stream_to_file.
• sleap_nn/config/model_config.py, sleap_nn/inference/topdown.py, sleap_nn/inference/layers/centroid.py — docstring updates.
• tests/data/test_instance_centroids.py, tests/inference/test_factory.py, tests/inference/test_tracking.py — test updates for new defaults + signature changes.

Created:

• docs/guides/centroid-only-inference.md
• tests/inference/test_centroid_only.py (9 tests)
• tests/cli/test_centroid_only_cli.py (4 tests)

🤖 Generated with Claude Code