FaceDetectorComponent Documentation

The FaceDetectorComponent is a web component built using StencilJs designed to handle video and image inputs for face detection purposes. It can operate in either video camera or file upload mode, depending on configuration.

Installation

To install the package via npm, use the following command:

npm install @jaak.ai/face-detector

Properties

| Property | Type | Description | |----------|-------------------|----------------------------------------------------------| | config | ConfigComponent | Configuration for the face detector component (optional) | |

Usage Example

<face-detector
  config={{
    width: '640px',
    height: '480px',
    enableMicrophone: true,
    mode: 'video-camera',
    placeholder: 'Upload your document',
    buttonText: 'Upload',
    documentAccept: 'image/*',
    description: 'Please upload an image file.',
    size: 2048
  }}
  onStatus={(event) => handleStatusChange(event.detail)}
  onComponentError={(event) => handleComponentError(event.detail)}
  onFileResult={(event) => handleFileResult(event.detail)}
></face-detector>

ConfigComponent Interface

Detailed interface for configuring the FaceDetectorComponent:

| Property | Type | Description | |-----------------------------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | width | string | Width of the video element. Default: '500px'. | | height | string | Height of the video element. Default: '400px'. | | enableMicrophone | boolean | Indicates whether the microphone should be enabled. Default: false. | | mode | string | Operational mode, either 'video-camera' or 'upload-file'. | | placeholder | string | Placeholder text for file input. | | buttonText | string | Text displayed on the upload button. | | documentAccept | string | Specifies the types of files that can be uploaded. | | description | string | Description displayed near the file input. | | size | number | Maximum file size allowed in kilobytes. | | videoDuration | number | Duration for video recording in seconds. | | video | MediaTrackConstraints | Duration for video recording in seconds. | | cameraSource | string | Specifies which camera to use for video capture when multiple sources are available, such as 'user' (front camera) or 'environment' (rear camera). This helps in selecting the appropriate camera based on the application's needs. | | videoFormat | string | Defines the preferred video resolution and frame rate format, such as '1920x1080@30' for 1080p video at 30 frames per second. This setting is used to configure the video output according to the capabilities of the media device and the requirements of the application. | | autoRecorder | boolean | If the system detect a face on video-cam mode, it will record a video(videoDuration) | | hideFaceTracker | boolean | Hides the monitoring shape that overlaps in the face found during video transmission. default: false | | disableFaceDetection | boolean | Deactivate the face detection system, the component does not search for faces during the video. default: false | | progressiveAutoRecorder | boolean | The component does not stop recording videos after your first recording. Notice: you will need to close the life cycle manually. default: false | | muteFaceDetectionMessages | boolean | No messages from the face detection will be sent during video transmission default: false | | hideTimer | boolean | The recording indicator will not be displayed during the processdefault: false | | timerStyles | TimerStyles | Define the styles of the recording indicator during the process | | faceTrackerStyles | FaceTrackerStyles | Define the styles of the figure on the face found by the detection system | | offlineModel | boolean | Load the faces detection system without making internet requests (local storage) |

TimerStyles Interface

Interface detailing the styles of timer recording indicator:

| Property | Type | Description | |----------------------|----------|----------------------------------------------------------------------------------| | color | string | Color of the progress indicator text. | | circleColor | string | Color of the filled part of the progress circle. | | circleColorEmpty | string | Color of the empty part of the progress circle. | | circleColorSuccess | string | Color of the progress circle when the task succeeds. | | width | number | Width of the progress circle in pixels. | | height | number | Height of the progress circle in pixels. | | fontSize | number | Font size of the progress indicator text in pixels. | | posX | number | Horizontal position of the progress indicator. It accepts 0 - 100. default: 50 | | posY | number | Vertical position of the progress indicator. It accepts 0 - 100. default: 50 | | strokeWidth | number | Width of the stroke of the progress circle in pixels. | | dashArray | string | Stroke dash pattern of the progress circle. |

FaceTrackerStyles Interface

Interface detailing the styles of face tracker indicator:

| Property | Type | Description | |----------------|----------|------------------------------------------------------------| | validColor | string | Optional color used to indicate a valid face detection. | | invalidColor | string | Optional color used to indicate an invalid face detection. |

FileResult Interface

Interface detailing the result of a file operation:

| Property | Type | Description | |----------|----------|--------------------------------------------| | base64 | string | Base64 encoded string of the file content. | | type | string | MIME type of the file (optional). | | name | string | Original name of the file (optional). | | size | number | Size of the file in bytes (optional). |

FaceDetectionMessage Interface

Interface detailing the result of FaceDetection operation:

| Property | Type | Description | |-------------------|-----------|-----------------------------------------------------------------------------| | label | string | A label describing the overall result of the face detection. | | details | string | Additional details about the face detection result. | | faceExist | boolean | Indicates whether a face was detected or not. | | correctPosition | boolean | Indicates whether the detected face is in the correct position as required. |

StatusFaceDetector Values

This enum represents the various status states that the FaceDetectorComponent can emit during its operation:

| Status | Description | |----------------|------------------------------------------------------------------| | NOT_LOADED | Initial state before any operations have started. | | LOADING | The component is currently loading necessary resources. | | LOADED | All resources are loaded, and the component is ready to be used. | | RECORDING | The component is currently recording video. | | ERROR | An error has occurred in one of the processes. | | UPLOADING | The component is uploading a file. | | RUNNING | The component is actively processing input or data. | | SNAPSHOTTING | The component is taking a snapshot or still image. | | FINISHED | The component has completed all processing and recording tasks. |

webComponentError Interface

Interface detailing when the component throws Error operation:

| Property | Type | Description | |-----------|----------|----------------------------------------------------------| | label | string | A descriptive label summarizing the error. | | code | string | An optional code identifying the type of error. | | details | any | Optional additional data or information about the error. |

Events

| Event Name | Emits | Description | |------------------------|------------------------|---------------------------------------------------------------------------------------------------------| | status | StatusFaceDetector | Emits the current status of the component, indicating different operational states. | | componentError | webComponentError | Emits an error object containing details about an error that occurred in the component. | | fileResult | FileResult | Emits the result of a file operation, typically after a recording or snapshot has been processed. | | faceDetectionMessage | FaceDetectionMessage | Emits messages related to face detection results, including details about detection status and quality. |

Methods

| Name | Parameters | Result | Description | |-----------------------|------------------------------------------|--------------------|------------------------------------------------------------------------------------------------------------------| | turnOffFaceDetector | None | void | Deactivates the face detector, hides the model shape, and unsubscribes from the detection service. | | switchMode | newMode: video-cameraor upload-file | void | Switches the component mode between 'video-camera' and 'upload-file', and either resets or stops as appropriate. | | stopComponent | None | void | Stops the component's operations by invoking the internal stopCore method. | | restartComponent | None | void | Resets the component to its initial configured state using resetCore. | | getMode | None | string | Returns the current mode of the component. | | recordVideo | None | string | Starts video recording and returns the video in Base64 format if successful. | | takeSnapshot | None | string | Captures a snapshot and returns the image in Base64 format if successful. | | getVideoElement | None | HTMLVideoElement | Retrieves the video element from the video camera component. | | getStream | None | MediaStream | Retrieves the media stream from the video camera component. | | toggleCamera | None | void | Toggles the video camera between front and back modes, if applicable. | | stopVideoStream | None | void | Stops the video stream from the video camera component. | | restartVideoStream | None | void | Resumes the video stream from the video camera component. | | resetFaceDetector | resetHard: boolean | void | Resets the face detector to its default state and optionally performs a hard reset. |

Example Usage of FaceDetectorComponent

This example demonstrates how to implement the FaceDetectorComponent in a simple HTML and JavaScript setup. It includes configuration of the component, handling various events, and switching operational modes.

HTML and JavaScript Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Face Detector Example</title>
</head>
<body>
<!-- Include the Face Detector component -->
<face-detector id="faceDetector"></face-detector>

<script type="module">
  // Select the face-detector component
  const faceDetector = document.getElementById('faceDetector');

  // Configure the component with initial settings
  faceDetector.config = {
    width: '640px',
    height: '480px',
    enableMicrophone: false,
    mode: 'video-camera', // or 'upload-file' for file upload mode
    placeholder: 'Upload your image',
    buttonText: 'Upload File',
    documentAccept: 'image/*',
    description: 'Please upload an image for face detection',
    size: 2048, // Max file size in kilobytes
    videoDuration: 5 // Duration in seconds for video recording
  };

  // Handle the status event
  faceDetector.addEventListener('status', event => {
    console.log('Status event:', event.detail);
    // You can update UI based on status here
  });

  // Handle errors
  faceDetector.addEventListener('componentError', event => {
    console.error('Error event:', event.detail);
    // Display error messages to the user
  });

  // Handle file results
  faceDetector.addEventListener('fileResult', event => {
    console.log('File result event:', event.detail);
    // Process the file result, e.g., display the image or video
  });

  // Example of using a component method to switch modes
  function switchToUploadMode() {
    faceDetector.switchMode('upload-file');
  }

  // Add more functionality or interaction logic as needed
</script>
</body>
</html>

React Implementation Example for FaceDetectorComponent

This section provides an example of how to integrate and use the FaceDetectorComponent within a React application.

import React, { useState, useEffect } from 'react';

const FaceDetector = () => {
  const [status, setStatus] = useState('');
  const [error, setError] = useState(null);
  const [fileResult, setFileResult] = useState(null);

  useEffect(() => {
    // Ensure custom elements are defined
    if (!customElements.get('face-detector')) {
      import('@jaak-ai/face-detector');
    }
  }, []);

  const handleStatusChange = (event) => {
    setStatus(event.detail);
  };

  const handleError = (event) => {
    setError(event.detail);
  };

  const handleFileResult = (event) => {
    setFileResult(event.detail);
  };

  return (
    <div>
      <face-detector
        id="faceDetector"
        onStatus={handleStatusChange}
        onComponentError={handleError}
        onFileResult={handleFileResult}
        config={JSON.stringify({
          width: '640px',
          height: '480px',
          enableMicrophone: true,
          mode: 'video-camera',
          placeholder: 'Upload your image',
          buttonText: 'Upload File',
          documentAccept: 'image/*',
          description: 'Please upload an image for face detection',
          size: 2048,
          videoDuration: 5
        })}
      ></face-detector>

      <div>Status: {status}</div>
      <div>Error: {error && error.label}</div>
      <div>File Result: {fileResult && fileResult.base64}</div>
    </div>
  );
};

export default FaceDetector;

Angular Implementation Example for FaceDetectorComponent

This section provides an example of how to integrate and use the FaceDetectorComponent within an Angular application.

import { Component, OnInit } from '@angular/core';

@Component({
 selector: 'app-root',
 template: `
   <face-detector
     (status)="handleStatus($event)"
     (componentError)="handleError($event)"
     (fileResult)="handleFileResult($event)"
     [config]="config">
   </face-detector>

   <div>Status: {{ status }}</div>
   <div>Error: {{ error?.details }}</div>
   <div>File Result: {{ fileResult?.base64 }}</div>
 `
})
export class AppComponent implements OnInit {
 status: string;
 error: any;
 fileResult: any;
 config = {
   width: '640px',
   height: '480px',
   enableMicrophone: true,
   mode: 'video-camera',
   placeholder: 'Upload your image',
   buttonText: 'Upload File',
   documentAccept: 'image/*',
   description: 'Please upload an image for face detection',
   size: 2048,
   videoDuration: 5
 };

 ngOnInit(): void {
   // Custom element registration or any initialization logic
 }

 handleStatus(event: CustomEvent) {
   this.status = event.detail;
 }

 handleError(event: CustomEvent) {
   this.error = event.detail;
 }

 handleFileResult(event: CustomEvent) {
   this.fileResult = event.detail;
 }
}

Additional Info

This package needs library dependencies, if is necessary you can install manually dependencies using this command:

npm install @jaak.ai/video-camera @jaak.ai/file-uploader

This component is designed, developed and owned by JAAK and is their intellectual property. Visit more details in https://jaak.ai