Defining a face detection method

Face detection classes are in charge of finding faces in image frames.

Two face detection classes are provided : LibFaceDetection (default) and OcvCnnFacedetector.

Face detection classes inherits from abstract class FaceDetector and share a common interface. They are designed as *functions objects* or *functors* using image frame inputs and returning list of Detection instances.

>>> from inaFaceAnalyzer.opencv_utils import imread_rgb
>>> from inaFaceAnalyzer.face_detector import LibFaceDetection
>>> # read image
>>> img = imread_rgb('./media/dknuth.jpg')
>>> # instantiate a detector (costly - to be done a single time)
>>> detector = LibFaceDetection()
>>> #call the detector instance as a function - setting verbose to True is slower, but display intermediate results
>>> ldetections = detector(img, verbose=True)
>>> print(ldetections)
[Detection(bbox=Rect(x1=113.9406801111573, y1=63.12627956950275, x2=287.63299981285394, y2=280.43775060093793), detect_conf=0.9999985098838806)]

class inaFaceAnalyzer.face_detector.FaceDetector(minconf, min_size_px, min_size_prct, padd_prct)

Bases: abc.ABC

__call__(frame, verbose=False)

Call self as a function.

__init__(minconf, min_size_px, min_size_prct, padd_prct)

Common face detection constructor

Parameters

• minconf (float between 0 and 1) – the minimal face detection confidence being returned (default values dependent on the face detection class choosen).

• min_size_px (int) – minimal face size in pixels (default 30): better classification results requires face sizes above 75 pixels.

• min_size_prct (float between 0 and 1) – minimal face size as a percentage of image frame minimal dimension. Allow to focus on the most relevant faces.

• padd_prct (float between 0 and 1) – percentage of black padding pixels to be applied on images before detection (default values are set or each detection class).

get_closest_face(frame, ref_bbox, min_iou=0.7, squarify=True, verbose=False)

Some face corpora may contain pictures with several faces together with the reference bounding box of annotated faces This function is aimed at preprocessing such face corpora Automatic face detection is used, and the detected face with the largest iou with the reference bounding box is returned if no detected face corresponds to this IOU criteria, returns None

most_central_face(frame, contain_center=True, verbose=False)

This method returns the detected face which is closest from the center of the image frame Usefull for preprocessing ML face datasets containing several faces per image

Parameters

• frame (numpy.ndarray (height, width, 3)) – RGB image data.

• contain_center (bool, optional) – if True, the returned face MUST include image center. Defaults to True.

• verbose (bool, optional) – Display detected faces. Defaults to False.

Returns

if a face matching the conditions has been detected, else None

Return type

Detection

output_type

Atomic element returned by face detection classes

class inaFaceAnalyzer.face_detector.LibFaceDetection(minconf=0.98, min_size_px=30, min_size_prct=0, padd_prct=0)

Bases: inaFaceAnalyzer.face_detector.FaceDetector

This class wraps the face detection model provided in libfacedetection : a recent face detection library (2021) that can take advantage of GPU acceleration and is able de detect the smallest faces. It may be slow when used with high resolution images.

For more details, please refer to : Peng, H., & Yu, S. (2021). A systematic iou-related method: Beyond simplified regression for better localization. IEEE Transactions on Image Processing, 30, 5032-5044.

__init__(minconf=0.98, min_size_px=30, min_size_prct=0, padd_prct=0)

Common face detection constructor

Parameters

• minconf (float between 0 and 1) – the minimal face detection confidence being returned (default values dependent on the face detection class choosen).

• min_size_px (int) – minimal face size in pixels (default 30): better classification results requires face sizes above 75 pixels.

• min_size_prct (float between 0 and 1) – minimal face size as a percentage of image frame minimal dimension. Allow to focus on the most relevant faces.

• padd_prct (float between 0 and 1) – percentage of black padding pixels to be applied on images before detection (default values are set or each detection class).

class inaFaceAnalyzer.face_detector.OcvCnnFacedetector(minconf=0.65, min_size_px=30, min_size_prct=0, padd_prct=0.15)

Bases: inaFaceAnalyzer.face_detector.FaceDetector

This class wraps OpenCV default CNN face detection model. Images are fist resized to 300*300 pixels, which may result in missing the smallest faces but allows to get fast detection time.

Contructor is documented in FaceDetector.__init__()

__init__(minconf=0.65, min_size_px=30, min_size_prct=0, padd_prct=0.15)

Parameters

• minconf (float, optional) – minimal face detection confidence. The default is 0.65.

• paddpercent (float, optional) – input frame is copy passted within a black image with black pixel padding. the resulting dimensions is width * (1+2*paddpercent)

class inaFaceAnalyzer.face_detector.IdentityFaceDetector

Bases: inaFaceAnalyzer.face_detector.FaceDetector

This class do not detect faces and return bouding boxes corresponding to the whole image frame. It should be used for processing images or videos corresponding to already-detected cropped faces.

__init__()

Common face detection constructor

Parameters

• minconf (float between 0 and 1) – the minimal face detection confidence being returned (default values dependent on the face detection class choosen).

• min_size_px (int) – minimal face size in pixels (default 30): better classification results requires face sizes above 75 pixels.

• min_size_prct (float between 0 and 1) – minimal face size as a percentage of image frame minimal dimension. Allow to focus on the most relevant faces.

• padd_prct (float between 0 and 1) – percentage of black padding pixels to be applied on images before detection (default values are set or each detection class).