{"record":{"id":"07aa8c583c3fa3e6","repo":"deepinsight/insightface","slug":"skipped-multi-face-image-face-count-faces","errorCode":null,"errorMessage":"skipped multi-face image ({face_count} faces)","messagePattern":"skipped multi-face image \\((.+?) faces\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"python-package/insightface/gui/core/evaluation.py","lineNumber":170,"sourceCode":"                (det[:, 0] + det[:, 2]) / 2.0 - img_center[1],\n                (det[:, 1] + det[:, 3]) / 2.0 - img_center[0],\n            ]\n        )\n        offset_dist_squared = np.sum(np.power(offsets, 2.0), axis=0)\n        return faces[int(np.argmax(bounding_box_size - offset_dist_squared * 2.0))]\n    except Exception:\n        return max(faces, key=_face_area)\n\n\ndef _select_face_from_faces(faces, image_shape, path: Path, policy: str, stage: str):\n    del path, stage\n    face_count = len(faces)\n    if face_count == 0:\n        raise ValueError(\"no face detected\")\n    if face_count > 1 and policy == MULTI_FACE_REQUIRE_ONE:\n        raise ValueError(f\"multiple faces detected ({face_count}); expected exactly one face\")\n    if face_count > 1 and policy == MULTI_FACE_SKIP:\n        raise ValueError(f\"skipped multi-face image ({face_count} faces)\")\n    if face_count > 1 and policy == MULTI_FACE_USE_CENTERED_LARGEST:\n        return _largest_centered_face(faces, image_shape)\n    if face_count > 1:\n        return max(faces, key=_face_area)\n    return faces[0]\n\n\ndef select_face_by_policy(faces, image_shape, policy: str = MULTI_FACE_REQUIRE_ONE, path: str | Path = \"\", stage: str = \"\"):\n    return _select_face_from_faces(\n        faces,\n        image_shape,\n        Path(path) if path else Path(\"image\"),\n        _normalize_multi_face_policy(policy),\n        stage,\n    )\n\n\ndef multi_face_policy_help(policy: str) -> str:","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/core/evaluation.py#L152-L188","documentation":"Raised by _select_face_from_faces when an image contains more than one face and the multi-face policy is MULTI_FACE_SKIP. The evaluation refuses to guess which face is the subject, so the image is treated as unusable for that stage. It is one of several policy-driven ValueError branches handling multi-face ambiguity.","triggerScenarios":"Calling run_identity_verification_evaluation / run_identity_identification_evaluation (or _embedding_for_image) with multi_face_policy='skip' (or a value normalized to it) on a dataset where images contain 2+ detected faces.","commonSituations":"Group photos or crowd shots in an identity folder; background posters/faces detected alongside the subject; test fixtures built with collages; policy configured globally as 'skip' but dataset not curated.","solutions":["Switch multi_face_policy to 'use_largest' or 'centered_largest' so a deterministic face is chosen","Curate the dataset to single-face images (crop or remove multi-face files)","Pre-scan images with engine.detect_faces and exclude any with len(faces) > 1 before running evaluation","If multi-face images are expected to fail, catch the error per-path (errors list already records stage/path) and continue"],"exampleFix":"# before\nresult = run_identity_verification_evaluation(..., multi_face_policy=\"skip\")\n# after\nresult = run_identity_verification_evaluation(..., multi_face_policy=\"centered_largest\")","handlingStrategy":"validation","validationCode":"img = read_image(path)\nfaces = engine.detect_faces(img, source_path=str(path))\nusable = len(faces) == 1 or multi_face_policy != \"skip\"","typeGuard":null,"tryCatchPattern":"try:\n    emb = _embedding_for_image(path, engine, multi_face_policy=policy)\nexcept ValueError as e:\n    if \"skipped multi-face\" in str(e):\n        continue  # or retry with centered_largest policy","preventionTips":["Pre-scan dataset with detect_faces and flag multi-face images","Prefer centered_largest policy for in-the-wild datasets","Curate identity folders to single-subject photos"],"tags":["insightface","multi-face","face-detection","policy","evaluation"],"backgroundTag":"multi-face-policy-skip","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}