tracking-keypoints

Tracking Keypoints

Use this sub-skill when a task involves supervision keypoint data, keypoint annotation, keypoint-to-detection conversion for tracking, persistent tracker_id workflows, line-crossing/counting that depends on tracker identity, or migration away from deprecated keypoint/tracker APIs.

Route here for

• KeyPoints, keypoint_confidence, detection_confidence, visible, KeyPoints.merge, KeyPoints.with_nms, and KeyPoints.as_detections.
• Keypoint adapters such as KeyPoints.from_ultralytics, from_inference, from_mediapipe, from_yolo_nas, from_detectron2, and from_transformers.
• VertexAnnotator, EdgeAnnotator, VertexLabelAnnotator, VertexEllipseAreaAnnotator, VertexEllipseOutlineAnnotator, VertexEllipseHaloAnnotator, and the VertexEllipseAnnotator alias.
• ByteTrack, ByteTrackTracker, tracker_id, track_objects, track labels, TraceAnnotator, DetectionsSmoother, and LineZone when persistent identity is central to the answer.
• Deprecated supervision.keypoint, deprecated sv.ByteTrack, old ByteTrack threshold names, and the KeyPoints.confidence rename.

Route away

• Build, filter, save, or reason about ordinary Detections, masks, polygon zones, line-zone geometry, sinks, or slicers when tracker continuity is not central: use detection-and-zones.
• Non-keypoint detection/mask/label visualization and annotator catalog choices: use annotators.
• Image/video I/O, primitive drawing, OpenCV backend diagnosis, GUI/window problems, and video codecs: use media-utils.
• Dataset conversion or detection metric evaluation: use the corresponding dataset or metrics sub-skill.

Operating checklist

1. Identify the active container. Pose/keypoint model outputs should become sv.KeyPoints; tracking, line crossing, traces, smoothing, and most labels operate on sv.Detections with tracker_id.
2. Prefer sv.KeyPoints or supervision.key_points. Do not introduce new supervision.keypoint imports; that path is compatibility-only and scheduled for removal.
3. Use keypoint_confidence for per-anchor scores and detection_confidence for whole-skeleton scores. Treat KeyPoints.confidence and confidence= as deprecated compatibility shims.
4. Before keypoint annotation, decide whether missing/weak anchors should be hidden with key_points.visible. When visible is None, annotators treat anchors as visible except that all-zero coordinates are skipped.
5. Before keypoint tracking, convert with key_points.as_detections(...), ensure the resulting detections have confidence scores and positive-area boxes, then run a tracker. Prefer the external ByteTrackTracker package when available; sv.ByteTrack is only a deprecated compatibility fallback in this version.
6. Use the tracked Detections object for tracker labels, traces, detection smoothing, and LineZone.trigger(...). Missing tracker_id is the first thing to check when these workflows do nothing or raise.
7. Put detailed API choices and recipes in tracking-keypoints.md, and failure repair steps in troubleshooting.md. Use the bundled draw_zones.py helper only for interactive polygon authoring in a GUI-capable environment.

Required context to keep in answers

• Target package facts: supervision 0.31.0.dev0, Python >=3.10, base install pip install supervision.
• Model adapters require their own model/framework packages; they are not part of the base supervision install.
• ByteTrackTracker comes from the optional external trackers package. sv.ByteTrack still exists as a lazy compatibility export in this target, but it is deprecated and should not be presented as stable.
• Native OpenCV is optional for the package. Interactive helpers require a GUI display and an OpenCV-compatible drawing/video backend; the documented fallback backend may render or decode differently from native OpenCV.
• Do not recommend original repository docs, examples, tests, scripts, local checkout paths, or generated skill import steps as runtime dependencies.