@goteam/face-api

This package leverages the power of @mediapipe/tasks-vision, a robust framework for computer vision tasks. If you wish to tailor your facial recognition experience to your unique needs and preferences, we encourage you to explore the extensive documentation provided by the Mediapipe team. This documentation offers comprehensive insights and resources for customizing and enhancing your facial recognition capabilities

Installation

 npm install @goteam/face-api

---

Quick Start

• Instantiating Face API

  You can quickly set up the Face API by importing the FaceApi class and creating an instance. Optionally, you can specify a model file path as a parameter.

  import { FaceApi } from "@goteam/face-api"
  
  /**
   * Create an instance of the Face API.r 
   * 
   * @param {?String} model - (Optional) Specify a model file path.
   */
  const faceApi = await FaceApi.make();

• Face Detector

  Once you've instantiated the FaceApi class, you can access the face detector module to work with face detection.

  /**
   * To use the face detector module, provide an HTMLVideoElement as a parameter.
   * 
   * @param {HTMLVideoElement} video - HTML video element for face detection.
   * @param { FaceDetectorOptions } config - (optional)
   */
  const faceDetector = faceApi.faceDetector(config);
  
  // Once you have the faceDetector instance, you can chain methods to perform actions.
  
  /**
   * Display bounding boxes around detected faces in the video.
   */
  faceDetector.withBoundingBox();
  
  /**
   * Display bounding boxes around detected faces in the video.
   * @param {String} rgba - Change the color of the bounding box.
   */
  faceDetector.setBoundingBoxColor(rgba);
  
  /**
   * Hide bounding boxes around detected faces in the video.
   */
  faceDetector.hideBoundingBox();
  
  /**
   * Generate an HTMLImageElement containing the detected face(s).
   * 
   * @param { getFaceParameters } params
   * If more faces are detected than allowed, it throws a { NumberOfFacesAllowedError }.
   */
  faceDetector.getFaces(params);
  
  /**
   * Sets the source of the video or image element.
   *
   * @param {HTMLVideoElement|HTMLImageElement} source - The video or image element to set as the source.
   * @return {FaceDetector} - Returns the current instance of the object.
   */
  faceDetector.setSource(source);

  This quick start guide helps you set up the Face API, instantiate it, and use the face detector module to perform face detection tasks efficiently.

  • Image Segmentation

    /**
     * To use the image segmenter module.
     * 
     * @param { ImageSegmenterOptions } config - (optional)
     */
    const segmenter = faceApi.imageSegmenter(config);
    
    /**
     * Extract segments from images
     * @param {HTMLImageElement} - The image source to be extracted
     * @param {?Array} - (optional) The image source to be extracted
     * 
     * @return HTMLImageElement
     */
    segmenter.extractSegment(image, segments);

• Face Matcher

  You can utilize the face matcher by accessing the faceAPI variable.

  /**
   * To work with the face matcher module, you can directly invoke the `matcher` method.
  *
  * @param { ImageEmbedderOptions } config - (optional) You can also provide configuration settings for the matcher.
  */
  const faceMatcher = faceApi.matcher(config);
  
  /**
  * Retrieve the floating-point embeddings of the image. Please note that this will return embeddings only for the first detected person.
  * @param {String | HTMLImageElement} image: - the image source for generate image embeddings
  *
  * @return Embedding
  */
  faceMatcher.getEmbeddings(image);
  
  /**
  * Obtain similarities between the source image supplied to the samples.
  */
  faceMatcher.similarities(source: HTMLVideoElement | HTMLImageElement): Promise<number | undefined>;

  For a more streamlined and cleaner approach, you can chain these methods as follows:

  const similarities = faceMatcher.setSamples(imageSamples).similarities(image);