Description

KeyPoints.with_nms() raises a zero-size reduction error after boolean filtering removes every joint from a nonempty batch. It now preserves those skeletons and their aligned fields, consistent with skeletons whose joints are all unusable.

import numpy as np
import supervision as sv

key_points = sv.KeyPoints(
    xy=np.array([[[10., 10.], [20., 20.]]]),
    class_id=np.array([0]),
    detection_confidence=np.array([0.9]),
)
filtered = key_points[np.array([[False, False]])]
filtered.with_nms()  # Previously raised ValueError; now keeps the skeleton.

Motivation and Context

Public keypoint filtering can produce valid (N, 0, 2) coordinates. The bounding-box reductions ran before the existing no-valid-joints handling and could not reduce the empty joint axis.

#2401 and merged #2402 addressed indexing and as_detections. Merged #2563 addressed nonfinite joints in NMS. Open #2633 populates detection confidence in pose connectors. This change addresses the separate empty-axis failure.

Changes Made

• Give the four bounding-box reductions their existing positive/negative infinity sentinels as initial values, allowing empty axes to reach the existing zero-area-box handling.
• Keep the usual NMS validation and selection path, preserving class-aware and class-agnostic behavior, aligned fields, and returned-object semantics.
• Add 11 cases covering one/multiple skeletons, boolean filtering, optional fields, required fields, and threshold validation; clarify the method docstring and add an Unreleased changelog entry.

Testing

All commands ran in this branch's independent worktree based on 8c7df2388ce46f16139edc498c2bc3874493b4bc.

• Clean base: uv run pytest --cov=supervision — 4316 passed, 24 skipped; 91% coverage.

• New regression class against unchanged implementation: uv run pytest tests/key_points/test_core.py::TestKeyPointsWithNmsEmptyJoints — 8 failed with the expected zero-size reduction error (including two masked threshold-validation errors), 3 existing required-field checks passed.

• Fixed NMS cases: uv run pytest tests/key_points/test_core.py -k 'nms or Nms' — 33 passed.

• Full suite: uv run pytest --cov=supervision — 4327 passed, 24 skipped; 91% coverage.

• Relevant doctests: uv run pytest --doctest-modules src/supervision/key_points/core.py — 10 passed.

• uv run pre-commit run --all-files — all 22 hooks passed after formatting.

• git diff --check — passed.

• Added/updated tests, and the full suite passes locally

• Updated docs (docstrings / mkdocs entry) for new or changed public API

• Added a changelog entry in docs/changelog.md under Unreleased (skip for lint/type/format-only or pure doc changes)

Additional Notes

Validation used Python 3.13.9 and NumPy 2.3.1 with the supported OpenCV-free backend. The same 24 pre-existing skips remained before and after: 23 require optional OpenCV and one requires optional rasterio. No public API or dependency changes.