{"record":{"id":"d16be8eedf70710a","repo":"roboflow/supervision","slug":"keypoints-detection-confidence-must-be-given-for-n","errorCode":null,"errorMessage":"KeyPoints detection_confidence must be given for NMS to be executed.","messagePattern":"KeyPoints detection_confidence must be given for NMS to be executed\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/key_points/core.py","lineNumber":1350,"sourceCode":"\n        Examples:\n            ```python\n            from supervision import _cv2 as cv2\n            import supervision as sv\n            from rfdetr import RFDETRKeypointPreview\n\n            image = cv2.imread(\"<SOURCE_IMAGE_PATH>\")\n            model = RFDETRKeypointPreview()\n\n            key_points = model.predict(image)\n            key_points = key_points.with_nms(threshold=0.5)\n            ```\n        \"\"\"\n        if len(self) == 0:\n            return self\n\n        if self.detection_confidence is None:\n            raise ValueError(\n                \"KeyPoints detection_confidence must be given for NMS to be executed.\"\n            )\n\n        if not class_agnostic and self.class_id is None:\n            raise ValueError(\n                \"KeyPoints class_id must be given for NMS to be executed. If \"\n                \"you intended to perform class agnostic NMS set \"\n                \"class_agnostic=True.\"\n            )\n\n        xy = self.xy\n        valid = ~np.all(xy == 0, axis=-1)\n        if self.visible is not None:\n            valid = valid & self.visible\n        x_min = np.min(np.where(valid, xy[..., 0], np.inf), axis=1)\n        y_min = np.min(np.where(valid, xy[..., 1], np.inf), axis=1)\n        x_max = np.max(np.where(valid, xy[..., 0], -np.inf), axis=1)\n        y_max = np.max(np.where(valid, xy[..., 1], -np.inf), axis=1)","sourceCodeStart":1332,"sourceCodeEnd":1368,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/key_points/core.py#L1332-L1368","documentation":"Raised by KeyPoints.with_nms() when detection_confidence is None. NMS (non-max suppression) ranks overlapping detections by confidence and must discard low-confidence ones; without a per-skeleton detection_confidence array there is no score to sort on, so supervision refuses to run instead of silently producing arbitrary suppression.","triggerScenarios":"Calling key_points.with_nms(threshold=0.5) on a KeyPoints instance constructed without the detection_confidence argument (e.g. manually built from raw xy arrays, or from a connector that does not populate it, such as from_mediapipe pose landmarks).","commonSituations":"Using MediaPipe pose output (which has per-landmark confidence but no whole-detection confidence) and applying NMS; or constructing KeyPoints manually from inference output and forgetting to pass detection_confidence.","solutions":["Pass detection_confidence when constructing the KeyPoints: sv.KeyPoints(xy=..., class_id=..., detection_confidence=scores_array).","If you only have per-keypoint confidence, derive a per-detection score (e.g. mean of keypoint_confidence) and use it as detection_confidence.","Skip NMS when no detection confidence exists — it is not applicable to single-pose or connector outputs without detection scores."],"exampleFix":"// before\nkp = sv.KeyPoints(xy=xy, class_id=class_id)\nkp = kp.with_nms(threshold=0.5)  # ValueError\n\n// after\nkp = sv.KeyPoints(xy=xy, class_id=class_id, detection_confidence=scores)\nkp = kp.with_nms(threshold=0.5)","handlingStrategy":"type-guard","validationCode":"if kp.detection_confidence is None:\n    raise RuntimeError(\"Model output lacks detection_confidence; cannot NMS\")\nkp = kp.with_nms(threshold=0.5)","typeGuard":"def can_nms(kp: sv.KeyPoints) -> bool:\n    return kp.detection_confidence is not None","tryCatchPattern":"try:\n    kp = kp.with_nms(threshold=0.5)\nexcept ValueError as e:\n    if \"detection_confidence\" in str(e):\n        # derive a score or skip NMS\n        pass\n    else:\n        raise","preventionTips":["Always pass detection_confidence when constructing KeyPoints that will be NMS'd.","Treat NMS as optional: guard with `if kp.detection_confidence is not None:`.","For single-pose models (one skeleton per frame) NMS is unnecessary — skip it."],"tags":["keypoints","nms","confidence","validation"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}