Face-Api

Description

ml5.js has created an API to face-api.js that allows you to access face and face landmark detection.

The ml5.js implementation of face-api does not support expressions, age or gender estimation.

Quickstart

const detectionOptions = {
  withLandmarks: true,
  withDescriptors: false,
};
// Initialize the magicFeature
const faceapi = ml5.faceApi(detectionOptions, modelLoaded);

// When the model is loaded
function modelLoaded() {
  console.log('Model Loaded!');

  // Make some sparkles
  faceapi.detect(myImage, (err, results) => {
    console.log(results);
  });
}

Usage

Initialize

const faceapi = ml5.faceApi(videoOrOptionsOrCallback, optionsOrCallback?, callback?);

Parameters

videoOrOptionsOrCallback: REQUIRED. Notice there is no question mark in front of the input.
optionsOrCallback: OPTIONAL. Notice the ? indicates an optional parameter.

callback: OPTIONAL. A description of some kind of object with some properties. Notice the ? indicates an optional parameter.

{
  withLandmarks: true,
  withDescriptors: true,
  minConfidence: 0.5,
  MODEL_URLS: {
    Mobilenetv1Model: 'https://raw.githubusercontent.com/ml5js/ml5-data-and-models/face-api/models/faceapi/ssd_mobilenetv1_model-weights_manifest.json',
    FaceLandmarkModel: 'https://raw.githubusercontent.com/ml5js/ml5-data-and-models/face-api/models/faceapi/face_landmark_68_model-weights_manifest.json',
    FaceLandmark68TinyNet: 'https://raw.githubusercontent.com/ml5js/ml5-data-and-models/face-api/models/faceapi/face_landmark_68_tiny_model-weights_manifest.json',
    FaceRecognitionModel: 'https://raw.githubusercontent.com/ml5js/ml5-data-and-models/face-api/models/faceapi/face_recognition_model-weights_manifest.json',
  },
};

Properties

.video

Object: An HTML5Video object if one is passed in the constructor

.model

Object: the model

.modelReady

Boolean: true when model is ready and loaded, false when it is not

.config

Object object of configurations of the model

.ready

Boolean: true when model is ready and loaded, false when it is not

Methods

.detect()

Given an image, will run face detection. If a video was passed in the contructor, then it only a callback is necessary to handle the results.

faceapi.detect(optionsOrCallback, configOrCallback, callback);

📥 Inputs

optionsOrCallback: Required. Image | Object | Function. If given an image, this is the image that the face detection will be applied. If given an object, it is to set the configuration. If given a callback, this is to handle the results of the .detect() method.
configOrCallback: Optional. Object | Function. If an image is given as the first parameter, then this will either be an object or a function. If given an object, it is to set the configuration. If given a callback, this is to handle the results of the .detect() method.
callback: Optional. Function. A function to handle the results of .makeSparkles(). Likely a function to do something with the results of makeSparkles.

📤 Outputs

Array: Returns an array of objects. Each object contains {alignedRect, detection, landmarks, unshiftedLandmarks}.

.detectSingle()

Given an image, will run face detection. If a video was passed in the contructor, then it only a callback is necessary to handle the results. .detectSingle() is more accurate.

faceapi.detectSingle(optionsOrCallback, configOrCallback, callback);

📥 Inputs

optionsOrCallback: Required. Image | Object | Function. If given an image, this is the image that the face detection will be applied. If given an object, it is to set the configuration. If given a callback, this is to handle the results of the .detect() method.
configOrCallback: Optional. Object | Function. If an image is given as the first parameter, then this will either be an object or a function. If given an object, it is to set the configuration. If given a callback, this is to handle the results of the .detect() method.
callback: Optional. Function. A function to handle the results of .makeSparkles(). Likely a function to do something with the results of makeSparkles.

📤 Outputs