feat(metrics): add COCO keypoint mAP (OKS) for sv.KeyPoints

[8rulerstar]

Description

Closes #2686.

Thank you for maintaining supervision! This follows up on the feature proposal in #2686.

Adds sv.metrics.KeypointMeanAveragePrecision, the COCO keypoint mAP. It reuses COCOEvaluator and replaces only the IoU step with Object Keypoint Similarity, ported from pycocotools' computeOks with the keypoint parameters (maxDets=20, medium/large areas, COCO sigmas). Ignore regions for targets without visible keypoints and crowd targets follow COCO.

import supervision as sv
from supervision.metrics import KeypointMeanAveragePrecision

metric = KeypointMeanAveragePrecision()  # COCO sigmas for 17-point skeletons
for predictions, targets in zip(predictions_list, targets_list):
    metric.update(predictions, targets)  # one sv.KeyPoints per image

print(metric.compute())

The fix(metrics) commit is a small related fix: the shared precision guard used np.finfo(np.float32).eps, while pycocotools uses np.spacing(1), so a perfect box prediction scored 0.99999988 instead of 1.0. It is its own commit so it can be split into a separate PR if you prefer.

Motivation and Context

There is no pose metric in sv.metrics yet; evaluating sv.KeyPoints means converting to COCO JSON and running pycocotools. Details in #2686. I had no answers to the open questions there yet, so I went with the defaults proposed in the issue and am happy to change any of them:

• Only the metric and its result are public. The OKS helper, COCO sigmas and max detections stay private (_keypoint_oks_batch, _COCO_KEYPOINT_SIGMAS, _KEYPOINT_MAX_DETECTIONS).
• One PR, with the epsilon fix kept as its own commit.
• Targets read data["area"], data["xyxy"] and data["iscrowd"]; predictions read data["xyxy"] for the size bucket.
• The pycocotools comparison is a script in this description, not a test dependency.

Changes Made

• metrics/keypoint_mean_average_precision.py: KeypointMeanAveragePrecision and KeypointMeanAveragePrecisionResult (plot(), to_pandas(), printable COCO-style summary).

• detection/utils/iou_and_nms.py: private _keypoint_oks_batch, including the COCO expanded-box branch for targets without visible keypoints.

• metrics/mean_average_precision.py:

  • The accumulator reads the largest max_dets instead of the literal 100. Box, mask and OBB results are unchanged with the default settings; a regression test covers it.
  • Plot, pandas and mean helpers are shared between the box and keypoint results instead of duplicated.
  • Separate commit: EPS = np.spacing(1).

• Docs page, mkdocs entry, changelog entries.

• Review follow-up: keypoints given as (N, K, 3) use only the planar xy[..., :2]; sigmas must be positive and finite; docs describe NaN keypoints and zero target areas precisely; more tests for result helpers and edge cases.

Testing

Compared with pycocotools 2.0.11 COCOeval(..., "keypoints"), all five summary values (AP, AP50, AP75, APm, APl):

Data	Max abs difference
200 COCO val2017 images, yolo11n-pose predictions, 853 targets incl. 19 crowd and 267 without visible keypoints	2.8e-9
Synthetic, 60 seeds: multiple classes, 10% crowd, targets without visible keypoints, more than 20 predictions per image	1.4e-8
Synthetic, 40 seeds incl. a 5-point skeleton with custom sigmas	1.1e-8

Without target boxes, targets with no visible keypoints are skipped and the COCO subset differs by up to 8.6e-3; this is documented.

• uv run pytest tests/metrics tests/detection: 2673 passed, 1 skipped. Doctests of the changed modules pass. pre-commit on changed files passes (incl. mypy).

• The epsilon test fails on develop (0.9999998807907104 == 1.0) and passes with the fix. On random data, box, mask and OBB scores move up by at most 5e-8.

• 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

• keypoint visible is boolean in sv.KeyPoints, so COCO v=1 and v=2 are both treated as labelled, as in pycocotools.
• Out of scope for now: AR metrics and per-keypoint breakdowns.
• I can add the comparison script to this description or the test suite, whichever you prefer.

Thank you for taking the time to review this. Any feedback is very welcome, and I'm glad to adjust the API, naming or structure to whatever fits supervision best.

[codecov]

Codecov Report

❌ Patch coverage is 99.41860% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 93%. Comparing base (67c9600) to head (a1e990b).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop   #2687    +/-   ##
========================================
  Coverage       93%     93%            
========================================
  Files           81      82     +1     
  Lines        12238   12526   +288     
========================================
+ Hits         11360   11674   +314     
+ Misses         878     852    -26     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Copilot review overview

🟡 Changes recommended

Valid three-coordinate KeyPoints can crash or miscompute OKS, while infinite sigmas can make unrelated poses perfect matches.

Review effort: Balanced
Findings: 1 · 1 · 5

Open (7)

• Handle 3-column keypoints as planar coordinates with visibility · New
• Reject non-finite sigma values · New
• Document zero-area OKS behavior accurately · New
• Correct zero-area OKS behavior description · New
• Clarify float32 bias removal in the spacing comment · New
• Add semantic IDs to compound parameter sets · New
• Move test into the MeanAveragePrecision test class · New

What changed in this PR

Adds COCO-compatible keypoint mAP evaluation for sv.KeyPoints using Object Keypoint Similarity.

Changes:

• Introduces keypoint mAP metrics, OKS matching, and public exports.
• Adds extensive parity and regression tests.
• Adds API documentation, navigation, and changelog entries.

File	Description
src/​supervision/​detection/​utils/​iou_and_nms.py	Implements OKS calculation and COCO sigmas.
src/​supervision/​metrics/​keypoint_mean_average_precision.py	Implements keypoint mAP evaluation and result reporting.
src/​supervision/​metrics/​mean_average_precision.py	Shares reporting helpers and updates precision/max-detection handling.
src/​supervision/​metrics/​__init__.py	Exports the new metric API.
tests/​metrics/​test_keypoint_mean_average_precision.py	Tests OKS, COCO parity, categories, and reporting.
tests/​metrics/​test_mean_average_precision.py	Adds epsilon and max-detection regressions.
docs/​metrics/​keypoint_mean_average_precision.md	Documents the public API.
mkdocs.yml	Adds the documentation page to navigation.
docs/​changelog.md	Records the feature and precision fix.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

NaN handling and its documentation do not match the claimed pycocotools behavior.

3 open findings

• Finite-coordinate masking diverges from pycocotools for NaN inputs · New
• Incorrect claim that NaN keypoints contribute nothing like pycocotools · New
• Inaccurate pycocotools comparison for NaN keypoint handling · New

7 resolved since last review

• Handle 3-column keypoints as planar coordinates with visibility
• Reject non-finite sigma values
• Move test into the MeanAveragePrecision test class
• Add semantic IDs to compound parameter sets
• Clarify float32 bias removal in the spacing comment
• Correct zero-area OKS behavior description
• Document zero-area OKS behavior accurately

🧠 Review effort: Balanced