目录

faceDetector (Face Detection)

The face detection service supports the capability of detecting 2D faces. It detects the number of faces, facial position, feature points (left and right eye centers, nose, and mouth corners), and posture (pitch, roll, and yaw) in a specified image. Bounding boxes of detected faces are sorted by size.

Compared with the Vision Kit liveness detection service used for videos, this face detection service is used for images.

Since: 5.0.0(12)

Modules to Import

import { faceDetector } from '@kit.CoreVisionKit';

VisionInfo

Visual information to be recognized. Currently, only the visual information about the PixelMap type in color data format RGBA_8888 is supported.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.AI.Face.Detector

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Name Type Read-Only Optional Description
pixelMap image.PixelMap Yes No Image to be recognized. For details about the image requirements, see Constraints.

FaceRecognitionConfiguration

Configuration of face occlusion detection. If this parameter is specified during initialization and detection, additional detection functions will be enabled.

System capability: SystemCapability.AI.Face.Detector

Model restriction: This API can be used only in the stage model.

Since: 5.0.2(14)

Name Type Read-Only Optional Description
faceBlock boolean Yes No

Indicates whether to enable face occlusion detection.

The value true indicates yes, and the value false indicates no. The default value is false.

FaceBlock

Enumeration of face occlusion detection results.

System capability: SystemCapability.AI.Face.Detector

Model restriction: This API can be used only in the stage model.

Since: 5.0.2(14)

Name Value Description
UNINITIALIZED -1 Face occlusion detection is not enabled.
UNBLOCKED 0 Not occluded.
BLOCKED 1 Occluded.

FacePoint

Specifies the pixel point position.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.AI.Face.Detector

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Name Type Read-Only Optional Description
x number Yes No Horizontal (X) coordinate of a pixel point.
y number Yes No Vertical (Y) coordinate of a pixel point.

FacePose

Direction of a face in 3D space. For details about the coordinate system, please refer to the world coordinate system.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.AI.Face.Detector

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Name Type Read-Only Optional Description
yaw number Yes No Angle of moving a head left and right, that is, rotating around the vertical Y axis (localRotationY). Value range: [–180, 180]
pitch number Yes No Angle of moving a head up and down, that is, rotating around the transverse X axis (localRotationX). Value range: [–180, 180]
roll number Yes No Angle of tilting a head from side to side, that is, rotating around the sagittal Z axis (localRotationZ). Value range: [–180, 180]

FaceRectangle

Bounding box of a face. Describes the position and size of the face rectangle, including the coordinates of the upper left corner, width, and height.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.AI.Face.Detector

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Name Type Read-Only Optional Description
left number Yes No X coordinate of the upper left corner of a bounding box.
top number Yes No Y coordinate of the upper left corner of a bounding box.
width number Yes No Width of the face rectangle, in pixels.
height number Yes No Height of the face rectangle, in pixels.

Face

Face detection result, including the number of faces, coordinates, face posture, and confidence of the detection result.

System capability: SystemCapability.AI.Face.Detector

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Name Type Read-Only Optional Description
probability number Yes No

Confidence of the face detection result. The value is a floating point number ranging from 0 to 1. A larger value indicates a higher confidence.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
block FaceBlock Yes Yes

Face occlusion result. The default value is FaceBlock.UNINITIALIZED, indicating that face occlusion detection is disabled. If faceBlock is set to true in FaceRecognitionConfiguration during initialization to enable occlusion detection, FaceBlock.UNBLOCKED (no occlusion) or FaceBlock.BLOCKED (occlusion) is returned.

Since: 5.0.2(14)
pose FacePose Yes No

Face pose.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
rect FaceRectangle Yes No

Face bounding box list.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
points Array<FacePoint> Yes No

Array of facial landmarks, including the left and right eye centers, nose, as well as left and right mouth corners. The sequence is as follows: left eye center, right eye center, nose, left mouth corner, and right mouth corner.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

faceDetector.init

init(): Promise<boolean>

Initializes the face detection service. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.AI.Face.Detector

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Returns:

Type Description
Promise<boolean>

Indicates whether the initialization is successful, which is returned through a promise.

The value true indicates yes, and the value false indicates no.

Example:

import { faceDetector } from '@kit.CoreVisionKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

async function initAndReleaseFaceDetector() {
  // Initialize the face detection service.
  const initResult = await faceDetector.init();
  hilog.info(0x0000, 'faceDetectorSample', `Face detector initialization result:${initResult}`);

  if (initResult) {
    hilog.info(0x0000, 'faceDetectorSample', 'Face detector initialized successfully');

    // Add the code for using the face detection service.

    // Release the face detection service after the usage is complete.
    await faceDetector.release();
    hilog.info(0x0000, 'faceDetectorSample', 'Face detector released successfully');
  } else {
    hilog.error(0x0000, 'faceDetectorSample', 'Failed to initialize face detector');
  }
}

@Entry
@Component
struct Page {

  build() {
    Column(){
      Button('initAndReleaseFaceDetector').onClick(() => {
        // Call the function.
        void initAndReleaseFaceDetector();
      })
    }
  }
}

faceDetector.init

init(faceRecognitionConfiguration: FaceRecognitionConfiguration): Promise<boolean>

Initializes the face occlusion detection service. In the same process, as long as one face detection service has occlusion detection enabled and this service has not been released, all other face detection services within that process will also have occlusion detection enabled. This API uses a promise to return the result.

System capability: SystemCapability.AI.Face.Detector

Model restriction: This API can be used only in the stage model.

Since: 5.0.2(14)

Parameters:

Parameter Type Mandatory Description
faceRecognitionConfiguration FaceRecognitionConfiguration Yes Configuration of face occlusion detection.

Returns:

Type Description
Promise<boolean>

Indicates whether the initialization is successful, which is returned through a promise.

The value true indicates yes, and the value false indicates no.

Error codes:

For details about the error codes, please refer to Core Vision Kit Error Codes.

ID Error Message
401 The parameter check failed.

Example:

import { faceDetector } from '@kit.CoreVisionKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

async function initAndReleaseFaceDetector() {
  let config: faceDetector.FaceRecognitionConfiguration = {
    faceBlock: true
  };
  // Initialize the face occlusion detection service.
  const initResult = await faceDetector.init(config);
  hilog.info(0x0000, 'faceDetectorSample', `Face detector initialization result:${initResult}`);

  if (initResult) {
    hilog.info(0x0000, 'faceDetectorSample', 'Face detector initialized successfully');

    // Add the code for using the face detection service.

    // Release the face detection service after the usage is complete.
    await faceDetector.release();
    hilog.info(0x0000, 'faceDetectorSample', 'Face detector released successfully');
  } else {
    hilog.error(0x0000, 'faceDetectorSample', 'Failed to initialize face detector');
  }
}

@Entry
@Component
struct Page {

  build() {
    Column(){
      Button('initAndReleaseFaceDetector').onClick(() => {
        // Call the function.
        void initAndReleaseFaceDetector();
      })
    }
  }
}

faceDetector.release

release(): Promise<void>

Releases the face detection service. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.AI.Face.Detector

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Returns:

Type Description
Promise<void> Promise that returns no value.

Example:

import { faceDetector } from '@kit.CoreVisionKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

async function initAndReleaseFaceDetector() {
  // Initialize the face detection service.
  const initResult = await faceDetector.init();
  hilog.info(0x0000, 'faceDetectorSample', `Face detector initialization result:${initResult}`);

  if (initResult) {
    hilog.info(0x0000, 'faceDetectorSample', 'Face detector initialized successfully');

    // Add the code for using the face detection service.

    // Release the face detection service after the usage is complete.
    await faceDetector.release();
    hilog.info(0x0000, 'faceDetectorSample', 'Face detector released successfully');
  } else {
    hilog.error(0x0000, 'faceDetectorSample', 'Failed to initialize face detector');
  }
}

@Entry
@Component
struct Page {

  build() {
    Column(){
      Button('initAndReleaseFaceDetector').onClick(() => {
        // Call the function.
        void initAndReleaseFaceDetector();
      })
    }
  }
}

faceDetector.detect

detect(visionInfo: VisionInfo): Promise<Array<Face>>

Detects face information in an image. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.AI.Face.Detector

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
visionInfo VisionInfo Yes Image instance (including faces).

Returns:

Type Description
Promise<Array<Face>> Face detection result returned through a promise.

Error codes:

For details about the error codes, please refer to Core Vision Kit Error Codes.

ID Error Message
200 Run timed out, please try again later.
401 The parameter check failed.
1008800001 Failed to run face detector, please try again.
1008800002 The face detector service is abnormal.

Example:

import { faceDetector } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { fileIo } from '@kit.CoreFileKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';

async function faceDetectTest() {
  let imageSource: image.ImageSource | undefined = undefined;
  let chooseImage: PixelMap | undefined = undefined;

  // Select an image from the gallery.
  let photoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
  photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
  photoSelectOptions.maxSelectNumber = 1;
  let photoPicker: photoAccessHelper.PhotoViewPicker = new photoAccessHelper.PhotoViewPicker();
  let photoSelectResult = await photoPicker.select(photoSelectOptions);
  let uri = photoSelectResult.photoUris[0];
  if (uri === undefined) {
    hilog.info(0x0000, 'faceDetectorSample', 'uri is undefined');
    return;
  }

  // Convert the image into a pixel map.
  let file = await fileIo.open(uri, fileIo.OpenMode.READ_ONLY);
  imageSource = image.createImageSource(file.fd);
  chooseImage = await imageSource.createPixelMap();
  hilog.info(0x0000, 'faceDetectorSample', 'chooseImage:', chooseImage);
  if (!chooseImage) {
    return;
  }

  // Call the face detection API.
  let visionInfo: faceDetector.VisionInfo = {
    pixelMap: chooseImage
  };
  let data: faceDetector.Face[] = await faceDetector.detect(visionInfo);
  if (data.length === 0) {
    hilog.info(0x0000, 'faceDetectorSample', 'No face is detected in the image.');
  } else {
    let faceString = JSON.stringify(data);
    hilog.info(0x0000, 'faceDetectorSample', 'faceString data is ' + faceString);
  }

  // Release resources.
  if (chooseImage && imageSource) {
    void chooseImage.release();
    void imageSource.release();
  }
  if (file) {
    await fileIo.close(file);
  }
}

@Entry
@Component
struct Page {

  build() {
    Column(){
      Button('faceDetectTest').onClick(() => {
        // Call the function.
        void faceDetectTest();
      })
    }
  }
}