feat: add MediaPipe hand landmark support

[tarunbommawar27]

Before submitting

• Self-reviewed the code
• Updated documentation, follow [Google-style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods)
• Added docs entry for autogeneration (if new functions/classes)
• Added/updated tests
• All tests pass locally

Description

Adds support for MediaPipe hand landmarks in the key points module.

This PR adds a new Skeleton.HAND definition for MediaPipe's 21 hand landmarks and extends KeyPoints.from_mediapipe() to parse hand landmark outputs from both current and legacy MediaPipe result formats.

Type of Change

• ✨ New feature (non-breaking change which adds functionality)
• 🧪 Test update

Motivation and Context

MediaPipe hand landmarks contain 21 keypoints per hand. The existing Skeleton enum supported COCO, GHUM, and FaceMesh skeletons, but did not include a hand skeleton. This meant EdgeAnnotator could not automatically draw hand landmark connections.

KeyPoints.from_mediapipe() also handled pose and face landmarks, but did not handle hand landmarks. This PR adds support for both hand_landmarks and multi_hand_landmarks.

Closes #2170

Changes Made

• Added Skeleton.HAND with 21 vertices and 20 MediaPipe hand landmark edges

• Added automatic lookup support through existing SKELETONS_BY_VERTEX_COUNT and SKELETONS_BY_EDGE_COUNT

• Extended KeyPoints.from_mediapipe() to support:

  • hand_landmarks
  • multi_hand_landmarks

• Updated MediaPipe fake test helpers to support hand landmark test cases

• Added tests for the hand skeleton definition and MediaPipe hand landmark parsing

• Made MediaPipe confidence extraction robust by defaulting missing visibility values to 1.0

Testing

• I have tested this code locally
• I have added unit tests that prove my fix is effective or that my feature works
• All new and existing targeted tests pass

Commands run:

python -m uv run pre-commit run --files src/supervision/key_points/core.py src/supervision/key_points/skeletons.py tests/helpers.py tests/key_points/test_core.py tests/key_points/test_skeletons.py

python -m uv run pytest tests/key_points/test_core.py::test_from_mediapipe_input tests/key_points/test_skeletons.py tests/key_points/test_annotators.py -q

Result:

35 passed

Google Colab (optional)

Not applicable.

Screenshots/Videos (optional)

Not applicable.

Additional Notes

The skeleton edges use 1-based indexing to match the existing EdgeAnnotator behavior, which subtracts 1 before indexing into keypoint arrays.

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 82%. Comparing base (14f6f24) to head (465f1a8).
⚠️ Report is 20 commits behind head on develop.

❌ Your patch check has failed because the patch coverage (75%) is below the target coverage (95%). You can increase the patch coverage or adjust the target coverage.
❌ Your project check has failed because the head coverage (82%) is below the target coverage (95%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2283   +/-   ##
=======================================
  Coverage       82%     82%           
=======================================
  Files           66      66           
  Lines         9082    9084    +2     
=======================================
+ Hits          7412    7418    +6     
+ Misses        1670    1666    -4     

🚀 New features to boost your workflow:

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

[Copilot]

Pull request overview

Adds MediaPipe hand-landmark support to the key_points module by introducing a dedicated hand skeleton and extending MediaPipe result parsing to handle both current and legacy hand outputs.

Changes:

• Added Skeleton.HAND (21 vertices / 20 edges) and ensured it is discoverable via existing vertex/edge-count lookup maps.
• Extended KeyPoints.from_mediapipe() to parse hand_landmarks and multi_hand_landmarks, and to default missing per-landmark visibility to 1.0.
• Updated test helpers and expanded unit tests to cover the new hand skeleton and MediaPipe hand parsing.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/supervision/key_points/skeletons.py	Adds the new Skeleton.HAND edge definition and relies on existing lookup-map construction.
src/supervision/key_points/core.py	Extends from_mediapipe() to support hand landmarks and makes confidence extraction more robust.
tests/helpers.py	Adds a fake landmark type without visibility and extends fake MediaPipe results to include hand-related fields.
tests/key_points/test_core.py	Adds MediaPipe hand-landmark parsing test cases.
tests/key_points/test_skeletons.py	Adds tests validating the hand skeleton definition and exact edge list.