@capacitor-mlkit/face-detection
v8.0.0TypeScript
Capacitor plugin for ML Kit Face Detection.
0/weekUpdated 1 months agoApache-2.0Unpacked: 182.8 KB
Published by Robin Genz
npm install @capacitor-mlkit/face-detection@capacitor-mlkit/face-detection
Unofficial Capacitor plugin for ML Kit Face Detection.[^1]
Compatibility
| Plugin Version | Capacitor Version | Status |
| -------------- | ----------------- | -------------- |
| 8.x.x | >=8.x.x | Active support |
| 7.x.x | 7.x.x | Deprecated |
| 6.x.x | 6.x.x | Deprecated |
Installation
``bash`
npm install @capacitor-mlkit/face-detection
npx cap sync
Attention: This plugin only supports CocoaPods for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see this comment.
$3
#### Dependencies
You need to add the following meta data in the application tag in your AndroidManifest.xml:
`xml`
#### Variables
If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:
- $mlkitFaceDetectionVersion version of com.google.mlkit:face-detection (default: 16.1.7)$playServicesMlkitFaceDetectionVersion
- version of com.google.android.gms:play-services-mlkit-face-detection (default: 17.1.0)
This can be useful if you encounter dependency conflicts with other plugins in your project.
$3
#### Minimum Deployment Target
Make sure to set the deployment target in your ios/App/Podfile to at least 15.5:
`ruby`
platform :ios, '15.5'
Configuration
No configuration required for this plugin.
Demo
A working example can be found here: robingenz/capacitor-mlkit-plugin-demo
Usage
`typescript
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(...)
* Interfaces
* Enums
$3
`typescript`
processImage(options: ProcessImageOptions) => Promise
Detects human faces from the supplied image.
Only available on Android and iOS.
| Param | Type |
| ------------- | ------------------------------------------------------------------- |
| options | ProcessImageOptions |
Returns: Promise<ProcessImageResult>
Since: 5.1.0
--------------------
$3
#### 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 |
$3
#### 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:
- Terms & Privacy
- Android Data Disclosure
- iOS Data Disclosure
Changelog
See CHANGELOG.md.
License
See LICENSE.
[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.