face-api.js for the Browser

face-api.js for Nodejs

We can use the equivalent API in a nodejs environment by polyfilling some browser specifics, such as HTMLImageElement, HTMLCanvasElement and ImageData. The easiest way to do so is by installing the node-canvas package.

Alternatively you can simply construct your own tensors from image data and pass tensors as inputs to the API.

Furthermore you want to install @tensorflow/tfjs-node (not required, but highly recommended), which speeds things up drastically by compiling and binding to the native Tensorflow C++ library:

To load a model, you have to provide the corresponding manifest.json file as well as the model weight files (shards) as assets. Simply copy them to your public or assets folder. The manifest.json and shard files of a model have to be located in the same directory / accessible under the same route.

In a nodejs environment you can furthermore load the models directly from disk:

awaitfaceapi.nets.ssdMobilenetv1.loadFromDisk('./models')

You can also load the model from a tf.NamedTensorMap:

awaitfaceapi.nets.ssdMobilenetv1.loadFromWeightMap(weightMap)

Alternatively, you can also create own instances of the neural nets:

constnet=newfaceapi.SsdMobilenetv1()awaitnet.loadFromUri('/models')

You can also load the weights as a Float32Array (in case you want to use the uncompressed models):

// using fetchnet.load(awaitfaceapi.fetchNetWeights('/models/face_detection_model.weights'))// using axiosconstres=awaitaxios.get('/models/face_detection_model.weights',{responseType: 'arraybuffer'})constweights=newFloat32Array(res.data)net.load(weights)

High Level API

In the following input can be an HTML img, video or canvas element or the id of that element.

Composition of Tasks

Tasks can be composed as follows:

// all facesawaitfaceapi.detectAllFaces(input)awaitfaceapi.detectAllFaces(input).withFaceExpressions()awaitfaceapi.detectAllFaces(input).withFaceLandmarks()awaitfaceapi.detectAllFaces(input).withFaceLandmarks().withFaceExpressions()awaitfaceapi.detectAllFaces(input).withFaceLandmarks().withFaceExpressions().withFaceDescriptors()awaitfaceapi.detectAllFaces(input).withFaceLandmarks().withAgeAndGender().withFaceDescriptors()awaitfaceapi.detectAllFaces(input).withFaceLandmarks().withFaceExpressions().withAgeAndGender().withFaceDescriptors()// single faceawaitfaceapi.detectSingleFace(input)awaitfaceapi.detectSingleFace(input).withFaceExpressions()awaitfaceapi.detectSingleFace(input).withFaceLandmarks()awaitfaceapi.detectSingleFace(input).withFaceLandmarks().withFaceExpressions()awaitfaceapi.detectSingleFace(input).withFaceLandmarks().withFaceExpressions().withFaceDescriptor()awaitfaceapi.detectSingleFace(input).withFaceLandmarks().withAgeAndGender().withFaceDescriptor()awaitfaceapi.detectSingleFace(input).withFaceLandmarks().withFaceExpressions().withAgeAndGender().withFaceDescriptor()

Face Recognition by Matching Descriptors

To perform face recognition, one can use faceapi.FaceMatcher to compare reference face descriptors to query face descriptors.

First, we initialize the FaceMatcher with the reference data, for example we can simply detect faces in a referenceImage and match the descriptors of the detected faces to faces of subsequent images:

constresults=awaitfaceapi.detectAllFaces(referenceImage).withFaceLandmarks().withFaceDescriptors()if(!results.length){return}// create FaceMatcher with automatically assigned labels// from the detection results for the reference imageconstfaceMatcher=newfaceapi.FaceMatcher(results)

face-api.js predefines some highlevel drawing functions, which you can utilize:

/* Display detected face bounding boxes */constdetections=awaitfaceapi.detectAllFaces(input)// resize the detected boxes in case your displayed image has a different size than the originalconstresizedDetections=faceapi.resizeResults(detections,displaySize)// draw detections into the canvasfaceapi.draw.drawDetections(canvas,resizedDetections)/* Display face landmarks */constdetectionsWithLandmarks=awaitfaceapi.detectAllFaces(input).withFaceLandmarks()// resize the detected boxes and landmarks in case your displayed image has a different size than the originalconstresizedResults=faceapi.resizeResults(detectionsWithLandmarks,displaySize)// draw detections into the canvasfaceapi.draw.drawDetections(canvas,resizedResults)// draw the landmarks into the canvasfaceapi.draw.drawFaceLandmarks(canvas,resizedResults)/* Display face expression results */constdetectionsWithExpressions=awaitfaceapi.detectAllFaces(input).withFaceLandmarks().withFaceExpressions()// resize the detected boxes and landmarks in case your displayed image has a different size than the originalconstresizedResults=faceapi.resizeResults(detectionsWithExpressions,displaySize)// draw detections into the canvasfaceapi.draw.drawDetections(canvas,resizedResults)// draw a textbox displaying the face expressions with minimum probability into the canvasconstminProbability=0.05faceapi.draw.drawFaceExpressions(canvas,resizedResults,minProbability)

Extracting a Canvas for an Image Region

constregionsToExtract=[newfaceapi.Rect(0,0,100,100)]// actually extractFaces is meant to extract face regions from bounding boxes// but you can also use it to extract any other regionconstcanvases=awaitfaceapi.extractFaces(input,regionsToExtract)

Euclidean Distance

// ment to be used for computing the euclidean distance between two face descriptorsconstdist=faceapi.euclideanDistance([0,0],[0,10])console.log(dist)// 10

Retrieve the Face Landmark Points and Contours

constlandmarkPositions=landmarks.positions// or get the positions of individual contours,// only available for 68 point face ladnamrks (FaceLandmarks68)constjawOutline=landmarks.getJawOutline()constnose=landmarks.getNose()constmouth=landmarks.getMouth()constleftEye=landmarks.getLeftEye()constrightEye=landmarks.getRightEye()constleftEyeBbrow=landmarks.getLeftEyeBrow()constrightEyeBrow=landmarks.getRightEyeBrow()

Fetching JSON

Creating an Image Picker

asyncfunctionuploadImage(){constimgFile=document.getElementById('myFileUpload').files[0]// create an HTMLImageElement from a Blobconstimg=awaitfaceapi.bufferToImage(imgFile)document.getElementById('myImg').src=img.src}

Available Models

Face Detection Models

SSD Mobilenet V1

For face detection, this project implements a SSD (Single Shot Multibox Detector) based on MobileNetV1. The neural net will compute the locations of each face in an image and will return the bounding boxes together with it's probability for each face. This face detector is aiming towards obtaining high accuracy in detecting face bounding boxes instead of low inference time. The size of the quantized model is about 5.4 MB (ssd_mobilenetv1_model).

Tiny Face Detector

The Tiny Face Detector is a very performant, realtime face detector, which is much faster, smaller and less resource consuming compared to the SSD Mobilenet V1 face detector, in return it performs slightly less well on detecting small faces. This model is extremely mobile and web friendly, thus it should be your GO-TO face detector on mobile devices and resource limited clients. The size of the quantized model is only 190 KB (tiny_face_detector_model).

The face detector has been trained on a custom dataset of ~14K images labeled with bounding boxes. Furthermore the model has been trained to predict bounding boxes, which entirely cover facial feature points, thus it in general produces better results in combination with subsequent face landmark detection than SSD Mobilenet V1.

This model is basically an even tinier version of Tiny Yolo V2, replacing the regular convolutions of Yolo with depthwise separable convolutions. Yolo is fully convolutional, thus can easily adapt to different input image sizes to trade off accuracy for performance (inference time).

68 Point Face Landmark Detection Models

This package implements a very lightweight and fast, yet accurate 68 point face landmark detector. The default model has a size of only 350kb (face_landmark_68_model) and the tiny model is only 80kb (face_landmark_68_tiny_model). Both models employ the ideas of depthwise separable convolutions as well as densely connected blocks. The models have been trained on a dataset of ~35k face images labeled with 68 face landmark points.

Face Recognition Model

For face recognition, a ResNet-34 like architecture is implemented to compute a face descriptor (a feature vector with 128 values) from any given face image, which is used to describe the characteristics of a persons face. The model is not limited to the set of faces used for training, meaning you can use it for face recognition of any person, for example yourself. You can determine the similarity of two arbitrary faces by comparing their face descriptors, for example by computing the euclidean distance or using any other classifier of your choice.

The neural net is equivalent to the FaceRecognizerNet used in face-recognition.js and the net used in the dlib face recognition example. The weights have been trained by davisking and the model achieves a prediction accuracy of 99.38% on the LFW (Labeled Faces in the Wild) benchmark for face recognition.

The size of the quantized model is roughly 6.2 MB (face_recognition_model).

Face Expression Recognition Model

The face expression recognition model is lightweight, fast and provides reasonable accuracy. The model has a size of roughly 310kb and it employs depthwise separable convolutions and densely connected blocks. It has been trained on a variety of images from publicly available datasets as well as images scraped from the web. Note, that wearing glasses might decrease the accuracy of the prediction results.

Age and Gender Recognition Model

The age and gender recognition model is a multitask network, which employs a feature extraction layer, an age regression layer and a gender classifier. The model has a size of roughly 420kb and the feature extractor employs a tinier but very similar architecture to Xception.

This model has been trained and tested on the following databases with an 80/20 train/test split each: UTK, FGNET, Chalearn, Wiki, IMDB*, CACD*, MegaAge, MegaAge-Asian. The * indicates, that these databases have been algorithmically cleaned up, since the initial databases are very noisy.

Total Test Results

Total MAE (Mean Age Error): 4.54

Total Gender Accuracy: 95%

Test results for each database

The - indicates, that there are no gender labels available for these databases.