Defining a face detection method

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

Two face detection classes are provided :

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)[source]

Bases: ABC

__call__(frame, verbose=False)[source]

Perform face detection on image frames

Parameters:

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

  • verbose (bool, optional) – display intermediate results such as detected faces Not to be used in production. Defaults to False.

Returns:

list of Detection instances

__init__(minconf, min_size_px, min_size_prct, padd_prct)[source]

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)[source]

To be used for processing ML datasets and training new face classification models.

Some face corpora images may contain several annotated faces. This method return the detected face having the largest IOU with target ref_box. The IOU must be > to min_iou.

Parameters:

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

  • ref_bbox (tuple or Rect) – reference face bounding box (x1, y1, x2, y2).

  • min_iou (float, optional) – minimal acceptable intersection over union between the detected face to be returned and the reference bounding box. Defaults to .7.

  • squarify (TYPE, optional) – if True, returns the smallest square bounding box containing the detected face. If False returns the original detected face bounding box. Defaults to True.

  • verbose (TYPE, optional) – display intermediate results. Defaults to False.

Returns:

detected face matching the criteria (largest IOU with ref_bbox and IOU > min_iou), else None

Return type:

Detection or None

most_central_face(frame, contain_center=True, verbose=False)[source]

To be used for processing ML datasets and training new face classification models.

Some ML face corpora images containing several faces, with the target annotated face at the center.

This method returns the detected face which is closest from the center of the image frame

Parameters:

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

  • 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)[source]

Bases: 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)[source]

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)[source]

Bases: 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.

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

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.IdentityFaceDetector[source]

Bases: 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__()[source]

IdentityFaceDetector Constructor does not require arguments