Skip to content

Latest commit

 

History

History

face-detection

README.md

@capacitor-mlkit/face-detection

Unofficial Capacitor plugin for ML Kit Face Detection.1

Installation

npm install @capacitor-mlkit/face-detection
npx cap sync

Android

You need to add the following meta data in the application tag in your AndroidManifest.xml:

<meta-data android:name="com.google.mlkit.vision.DEPENDENCIES" android:value="face"/>
<!-- To use multiple models: android:value="face,model2,model3" -->

Variables

This plugin will use the following project variables (defined in your app’s variables.gradle file):

  • $mlkitFaceDetectionVersion version of com.google.mlkit:face-detection (default: 16.1.5)
  • $playServicesMlkitFaceDetectionVersion version of com.google.android.gms:play-services-mlkit-face-detection (default: 17.1.0)

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-mlkit-plugin-demo

Usage

import { FaceDetection, PerformanceMode, LandmarkMode, ContourMode, ClassificationMode } from '@capacitor-mlkit/face-detection';

const processImage = async () => {
  const { faces } = await FaceDetection.processImage({
    path: 'path/to/image.jpg',
    performanceMode: PerformanceMode.Fast,
    landmarkMode: LandmarkMode.All,
    contourMode: ContourMode.All,
    classificationMode: ClassificationMode.All,
    minFaceSize: 0.1,
    enableTracking: false,
  });
  return faces;
};

API

processImage(...)

processImage(options: ProcessImageOptions) => Promise<ProcessImageResult>

Detects human faces from the supplied image.

Only available on Android and iOS.

Param Type
options ProcessImageOptions

Returns: Promise<ProcessImageResult>

Since: 5.1.0

Interfaces

ProcessImageResult

Prop Type Description Since
faces Face[] The detected faces. 5.1.0

Face

Represents a face detected by FaceDetector.

Prop Type Description Since
bounds Rect Returns the axis-aligned bounding rectangle of the detected face. 5.1.0
landmarks FaceLandmark[] Returns a list of face landmarks. 5.1.0
contours FaceContour[] Returns a list of face contours. 5.1.0
trackingId number Returns the tracking ID if the tracking is enabled. 5.1.0
headEulerAngleX number Returns the rotation of the face about the horizontal axis of the image. Positive euler X is the face is looking up. 5.1.0
headEulerAngleY number Returns the rotation of the face about the vertical axis of the image. Positive euler y is when the face turns toward the right side of the image that is being processed. 5.1.0
headEulerAngleZ number Returns the rotation of the face about the axis pointing out of the image. Positive euler z is a counter-clockwise rotation within the image plane. 5.1.0
smilingProbability number Returns a value between 0.0 and 1.0 giving a probability that the face is smiling. 5.1.0
leftEyeOpenProbability number Returns a value between 0.0 and 1.0 giving a probability that the face's left eye is open. 5.1.0
rightEyeOpenProbability number Returns a value between 0.0 and 1.0 giving a probability that the face's right eye is open. 5.1.0

Rect

Rect holds four integer coordinates for a rectangle.

Prop Type Description Since
left number The X coordinate of the left side of the rectangle. 5.1.0
top number The Y coordinate of the top of the rectangle. 5.1.0
right number The X coordinate of the right side of the rectangle. 5.1.0
bottom number The Y coordinate of the bottom of the rectangle. 5.1.0

FaceLandmark

Represent a face landmark. A landmark is a point on a detected face, such as an eye, nose, or mouth.

Prop Type Description Since
type LandmarkType Gets the FaceLandmark.LandmarkType type. 5.1.0
position Point Gets a 2D point for landmark position, where (0, 0) is the upper-left corner of the image. 5.1.0

Point

Point holds two coordinates

Prop Type
x number
y number

FaceContour

Represent a face contour. A contour is a list of points on a detected face, such as the mouth.

Prop Type Description Since
type ContourType Gets the FaceContour.ContourType type. 5.1.0
points Point[] Gets a list of 2D points for this face contour, where (0, 0) is the upper-left corner of the image. 5.1.0

ProcessImageOptions

Prop Type Description Default Since
path string The local path to the image file. 5.1.0
performanceMode PerformanceMode Defines options to control accuracy / speed trade-offs in performing face detection. PerformanceMode.Fast 5.1.0
landmarkMode LandmarkMode Defines options to enable face landmarks or not. LandmarkMode.None 5.1.0
contourMode ContourMode Defines options to enable face contours or not. ContourMode.None 5.1.0
classificationMode ClassificationMode Defines options for characterizing attributes such as "smiling" * and "eyes open". ClassificationMode.None 5.1.0
minFaceSize number Sets the smallest desired face size, expressed as a proportion of the width of the head to the image width. 0.1 5.1.0
enableTracking boolean Enables face tracking, which will maintain a consistent ID for each face when processing consecutive frames. Tracking should be disabled for handling a series of non-consecutive still images. false 5.1.0

Enums

LandmarkType

Members Value Description Since
MouthBottom 0 The center of the subject's bottom lip. 5.1.0
LeftCheek 1 The midpoint between the subject's left mouth corner and the outer corner of the subject's left eye. For full profile faces, this becomes the centroid of the nose base, nose tip, left ear lobe and left ear tip. 5.1.0
LeftEar 3 The midpoint of the subject's left ear tip and left ear lobe. 5.1.0
LeftEye 4 The center of the subject's left eye cavity. 5.1.0
MouthLeft 5 The subject's left mouth corner where the lips meet. 5.1.0
NoseBase 6 The midpoint between the subject's nostrils where the nose meets the face. 5.1.0
RightCheek 7 The midpoint between the subject's right mouth corner and the outer corner of the subject's right eye. For full profile faces, this becomes the centroid of the nose base, nose tip, right ear lobe and right ear tip. 5.1.0
RightEar 9 The midpoint of the subject's right ear tip and right ear lobe. 5.1.0
RightEye 10 The center of the subject's right eye cavity. 5.1.0
MouthRight 11 The subject's right mouth corner where the lips meet. 5.1.0

ContourType

Members Value Description Since
Face 1 The outline of the subject's face. 5.1.0
LeftEyebrowTop 2 The top outline of the subject's left eyebrow. 5.1.0
LeftEyebrowBottom 3 The bottom outline of the subject's left eyebrow. 5.1.0
RightEyebrowTop 4 The top outline of the subject's right eyebrow. 5.1.0
RightEyebrowBottom 5 The bottom outline of the subject's right eyebrow. 5.1.0
LeftEye 6 The outline of the subject's left eye cavity. 5.1.0
RightEye 7 The outline of the subject's right eye cavity. 5.1.0
UpperLipTop 8 The top outline of the subject's upper lip. 5.1.0
UpperLipBottom 9 The bottom outline of the subject's upper lip. 5.1.0
LowerLipTop 10 The top outline of the subject's lower lip. 5.1.0
LowerLipBottom 11 The bottom outline of the subject's lower lip. 5.1.0
NoseBridge 12 The outline of the subject's nose bridge. 5.1.0
NoseBottom 13 The outline of the subject's nose bridge. 5.1.0
LeftCheek 14 The center of the left cheek. 5.1.0
RightCheek 15 The center of the right cheek. 5.1.0

PerformanceMode

Members Value Description Since
Fast 1 Indicates a preference for speed in the options that may make an accuracy vs. speed trade-off. This will tend to detect fewer faces and may be less precise in determining values such as position, but will run faster. 5.1.0
Accurate 2 Indicates a preference for accuracy in the options that may make an accuracy vs. speed trade-off. This will tend to detect more faces and may be more precise in determining values such as position, at the cost of speed. 5.1.0

LandmarkMode

Members Value Description Since
None 1 Does not perform landmark detection. 5.1.0
All 2 Detects FaceLandmark for a given face. 5.1.0

ContourMode

Members Value Description Since
None 1 Does not perform contour detection. 5.1.0
All 2 Detects FaceContour for a given face. Note that it would return contours for up to 5 faces 5.1.0

ClassificationMode

Members Value Description Since
None 1 Does not perform classification. 5.1.0
All 2 Performs "eyes open" and "smiling" classification. 5.1.0

Terms & Privacy

This plugin uses the Google ML Kit:

Changelog

See CHANGELOG.md.

License

See LICENSE.

Footnotes

  1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. ↩