AI Face Detect API

CUTOS Face Recognition Service Features:

• Supports face register, search, unregister, and comparison.

Installation

npm install @cutos/ai-face-detect

Import Dependencies

import {Face} from '@cutos/ai-face-detect'

Model File Resource Path Configuration

1. Automatic Installation (Recommended)

When running npm install, the installation script will automatically download the model files and copy them into the project directory:

public/cutos-ai-face-models/

No additional action is required from developers. Once installation is complete, the project can be used directly.

2. Manual Installation

If automatic installation fails or manual setup is preferred, follow the steps below:

(1) Locate the downloaded model files in the dependency package directory:

/node_modules/@cutos/ai-face-detect/cutos-ai-face-models/

(2) Copy this entire directory into the project path public/cutos-ai-face-models/. The final directory structure should look like this:

public/
├── cutos-ai-face-models/   # Model file directory
│   ├── blaze_face_short_range.tflite
│   ├── vision_wasm_internal.js
│   └── vision_wasm_internal.wasm
├── config.json
├── index.html
└── thumbnail.png

Face

Constructor, creates a face recognition service instance

const faceInstance = new Face();

Face.init

Initialize the face recognition gateway service

faceInstance.init(gwClient);

• gwClient： Object, instance of the face recognition gateway service.

Face.detectSingleFace

Detect a single face in the camera stream

faceInstance.detectSingleFace(videoElement);

• videoElement: <video> Element

Example:

//index.html
 <video class="cam-video" autoplay muted playsinline id="cam"></video>
        ...
//main.js
const $cam = document.querySelector('#cam')
const result = faceInstance.detectSingleFace($cam);
console.log(result)

• Example return result:

{
  "face": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAA",
  "fullFrame": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAA",
  "score": 0.9609517455101013
}

• result.face: The detected face image.
• result.fullFrame: The original camera frame (Blob in base64).
• result.score: Confidence score (0--1), recommended above 0.9 to consider detection successful.

Face.register

Register a face image

faceInstance.register(fullFrame)

• fullFrame：Base64 formatted image

Example:

const id = faceInstance.register('data:image/jpeg;base64,/9jtUgA.../Z);')
console.log(id)

• Example return result:

"f956ac67-0dd8-4dc4-ae5b-55f37d99bc6b" //Returns ID after successful registration

Face.search

Search for a registered face

faceInstance.search(fullFrame)

• fullFrame：Base64 formatted image

Example:

const result = faceInstance.search('data:image/jpeg;base64,/9jtUgA.../Z);');
console.log(result)

• Example return result:

{
  "id": "f956ac67-0dd8-4dc4-ae5b-55f37d99bc6b",
  "payload": {},
  "score": 0.9953916239059821
}

• result.id: Matched ID.
• result.score: Matching score.

Face.unregister

Unregister a face ID

faceInstance.unregister(id);

Example:

const id = faceInstance.unregister("f956ac67-0dd8-4dc4-ae5b-55f37d99bc6b");
console.log(id)

• Example return result:

"f956ac67-0dd8-4dc4-ae5b-55f37d99bc6b" //Returns ID after successful unregistration

Face.compare

Compare two faces

faceInstance.compare(image1, image2);

• image1: Base64 formatted image of face 1.
• image2: Base64 formatted image of face 2.

Example:

const score = faceInstance.compare('data:image/jpeg;base64,/9j/4...', 'data:image/jpeg;base64,/9j/4...');
console.log(score)

• Example return result:

0.9973043918609619 //Recommended above 0.9 to consider a successful match