Package `facedetection_python_module`

FaceDetection Model:

Overview

FaceDetection model is supposed to detect faces at very high speed robustly across a variety of environments even with fullHD resolution videos/images.Detector's very high speed allows it be used as a plug&play model for various use cases where finding a facial-region is crucial and first step before further processing like applying filters or any other interactive experience.

It is based on the mobileNetV2 architecture for feature extraction and YOLO architecture for generating bounding boxes for all the faces in any given frame/image.It handles all pre-processing and post-processing calculations thus allowing user to pass in any image/frame and get the facial bounding-box/boxes in the image/frame space,hence becoming a truly plug&play model in any pipeline.

Features

maintains very high speed even with large number of faces in an image.
Works robustly even with large scale and resolution variations.
Work with all versions of python3 (tested with python3 only).
Highly portable being a compiled python module.
Minimal dependencies (all dependencies are standard DLLs).
Only expected python dependencies are numpy and opencv(for reading/displaying images purpose).

Benchmarks

Architecture	OS	Time*(ms)
Intel i5-8300H Cpu @ 2.30GHz	Windows	< 7ms
NVIDIA GTX 1050	Windows	4-5ms

Time measured in python runtime averaging over 100 loops.
Time measured with inputs upto FULL-HD resolutions.
(All resolutions are resized to fixed input-size specified by model before further processing.)

Usage


import numpy as np
import cv2
import facedetection_python_module as fd            #load the module
#import facedetection_cuda_python_module as fd      #for gpu based module.

frame = cv2.imread("./test.jpg")                    #read the frame/image, Format: [BGR Uint8]
fd.load_model("./facedetection.bin")                #initialize the model and load weights.
face_bboxes = fd.detect_face(frame,conf_threshold=0.9)  #detect face/faces.    

for count in range(num_detected_faces):
    x1,y1,x2,y2,confidence = face_bboxes[count]
    cv2.rectangle(frame,(int(x1),int(y1)),(int(x2),int(y2)),(0,255,0),1)

cv2.imshow("frame",frame)
cv2.waitKey(0)

Resources:

MobileNet: https://arxiv.org/abs/1704.04861
YOLO: https://arxiv.org/abs/1506.02640

How to install

Note

Once SDK has been downloaded into a local directory. Follow these steps.

cd into directory. i.e at the root of directory.
Make sure all the requirements have been fulfilled as stated in requirements.
On Windows run following command at the root of the directory :

pip install .

On Linux run following command at the root of the directory :

pip install .

Functions

def detect_face(frame, conf_threshold=0.85, nms_threshold=0.45, max_count=50)

detects face/faces in the given frame/image and return bounding boxes for faces detected in original frame coordinates. Coordinates can be direclty plotted on the frame/image passed.

Inputs:

frame: Numpy array of shape [H,W,3] with Uint8 data-type, BGR data expected, generally resulting from routines like ``cv2.imread("<test.jpg>")``

conf_threshold:float threshold to suppress predictions with confidence less than this threshold.

nms_threshold:float threshold used by Non Maximum Suppression to suppress overlapping boxes with IOU greater than this value.

max_count:float maximum number of faces to be detected in a single image/frame.

Returns:

facial_bounding_boxes:  Numpy float32 array of shape [number_faces_detected,5] . where each row is of format (left,top,right,bottom,confidence) aka (x1,y1,x2,y2,confidence) format.

def load_model(weightsPath)

Initialize model and load Weights/parameters from the specified path using weightsPath argument.

Inputs:

weightsPath:str /path/to/weights   generally a file with <code>.bin</code> extension.