Extract faces from a given image Args: img_path (str or list of str ornp.ndarray or IO[bytes]): Path to the first image. Accepts exact image path as a string, list of string, numpy array (BGR), a file object that supports at least `.read` and is opened in bi
(
img_path: Union[str, NDArray[Any], IO[bytes], List[str], List[NDArray[Any]], List[IO[bytes]]],
detector_backend: str = "opencv",
enforce_detection: bool = True,
align: bool = True,
expand_percentage: int = 0,
grayscale: bool = False,
color_face: str = "rgb",
normalize_face: bool = True,
anti_spoofing: bool = False,
max_faces: Optional[int] = None,
)
| 45 | |
| 46 | |
| 47 | def extract_faces( |
| 48 | img_path: Union[str, NDArray[Any], IO[bytes], List[str], List[NDArray[Any]], List[IO[bytes]]], |
| 49 | detector_backend: str = "opencv", |
| 50 | enforce_detection: bool = True, |
| 51 | align: bool = True, |
| 52 | expand_percentage: int = 0, |
| 53 | grayscale: bool = False, |
| 54 | color_face: str = "rgb", |
| 55 | normalize_face: bool = True, |
| 56 | anti_spoofing: bool = False, |
| 57 | max_faces: Optional[int] = None, |
| 58 | ) -> Union[List[Dict[str, Any]], List[List[Dict[str, Any]]]]: |
| 59 | """ |
| 60 | Extract faces from a given image |
| 61 | |
| 62 | Args: |
| 63 | img_path (str or list of str ornp.ndarray or IO[bytes]): Path to the first image. |
| 64 | Accepts exact image path as a string, list of string, numpy array (BGR), a file object |
| 65 | that supports at least `.read` and is opened in binary mode, or base64 encoded images. |
| 66 | |
| 67 | detector_backend (string): face detector backend. Options: 'opencv', 'retinaface', |
| 68 | 'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8n', 'yolov8m', 'yolov8l', 'yolov11n', |
| 69 | 'yolov11s', 'yolov11m', 'yolov11l', 'yolov12n', 'yolov12s', 'yolov12m','yolov12l' |
| 70 | 'centerface' or 'skip' (default is opencv) |
| 71 | |
| 72 | enforce_detection (boolean): If no face is detected in an image, raise an exception. |
| 73 | Default is True. Set to False to avoid the exception for low-resolution images. |
| 74 | |
| 75 | align (bool): Flag to enable face alignment (default is True). |
| 76 | |
| 77 | expand_percentage (int): expand detected facial area with a percentage. |
| 78 | |
| 79 | grayscale (boolean): (Deprecated) Flag to convert the output face image to grayscale |
| 80 | (default is False). |
| 81 | |
| 82 | color_face (string): Color to return face image output. Options: 'rgb', 'bgr' or 'gray' |
| 83 | (default is 'rgb'). |
| 84 | |
| 85 | normalize_face (boolean): Flag to enable normalization (divide by 255) of the output |
| 86 | face image output face image normalization (default is True). |
| 87 | |
| 88 | anti_spoofing (boolean): Flag to enable anti spoofing (default is False). |
| 89 | |
| 90 | Returns: |
| 91 | results (List[Dict[str, Any]]): A list of dictionaries, where each dictionary contains: |
| 92 | |
| 93 | - "face" (np.ndarray): The detected face as a NumPy array in RGB format. |
| 94 | |
| 95 | - "facial_area" (Dict[str, Any]): The detected face's regions as a dictionary containing: |
| 96 | - keys 'x', 'y', 'w', 'h' with int values |
| 97 | - keys 'left_eye', 'right_eye' with a tuple of 2 ints as values. |
| 98 | left eye and right eye are eyes on the left and right respectively with respect |
| 99 | to the person itself instead of observer. |
| 100 | |
| 101 | - "confidence" (float): The confidence score associated with the detected face. |
| 102 | |
| 103 | - "is_real" (boolean): antispoofing analyze result. this key is just available in the |
| 104 | result only if anti_spoofing is set to True in input arguments. |