logo logo

DOT Web Face Auto Capture

v2.3.1

Introduction

Web DOT Face Auto Capture is a web component using video stream from available phone or web camera to automatically capture an image of user’s face with the required quality. The component renders the video stream and overlays it with a placeholder and instructions to guide the user to position their face correctly.

Supported Browsers

Web DOT Face Auto Capture was tested with:

  • Chrome on desktop (Windows, Mac and Linux)

  • Firefox on desktop (Windows and Linux)

  • Chrome on Android and iPhone

  • Firefox on Android and iPhone

  • Safari on iPhone

The components does not work reliably with Safari on Mac.

Privacy and security

This component can only be used in secure contexts due to MediaDevices API used for handling camera access. A secure context is, in short, a page loaded using HTTPS or the file:/// URL scheme, or a page loaded from localhost. Before accessing any camera, component must always get user’s permission. Browsers may offer a once-per-domain permission feature, but they must ask at least the first time, and the user has to specifically grant ongoing permission if they choose to do so. Browsers are required to display an indicator that shows that a camera or microphone is in use. More details can be found on MDN docs.

Basic Setup

Initialization

To integrate the Web DOT Face Auto Capture, following line has to be added to dependecies in package.json:

"dependencies": {
    "dot-face-auto-capture": "file:dot-face-auto-capture-[VERSION].tgz"
},

where [VERSION] is the Web DOT Face Auto Capture version integrated. This installs dot-face-auto-capture as an external module that can be use then (just like any other module in the code) For example, one could do import 'dot-face-auto-capture'; in the app.

Usage

Component has to be wrapped inside parent node with a defined height and width. The video stream will not render, if the height is zero.
Properties cameraOptions needs to be passed into component after <x-dot-face-auto-capture/> tag was rendered.

import 'dot-face-auto-capture';

const FaceCamera = (props) => {
  useEffect(() => {
    const faceAutoCaptureHTMLElement = document.getElementById('x-dot-face-auto-capture');
    faceAutoCaptureHTMLElement.cameraOptions = props;
  });

  return <x-dot-face-auto-capture id="x-dot-face-auto-capture" />;
};

const Page = () => {

  const handleFacePhotoTaken = (image, resolution) => {
    // ...
  };

  const modelUrls = {
    modelJSON: "blaze_model/face_4cl/model.json",
    modelBin: "blaze_model/face_4cl/group1-shard1of1.bin",
  };

  return (
    <div className="container" style="height: 500px; width: 500px;">
      <FaceCamera
        imageType="png"
        cameraFacing="user"
        photoTakenCb={handleFacePhotoTaken}
        modelUrls={modelUrls}
      />
    </div>
  );
};

Hosting of detection models

The component needs to have access to a face detection model consisting of a binary and JSON. These are distributed in the package and need to be hosted by the website provider. If using Create React App copy model.json and group1-shard1of1.bin to public folder. In our example the final path is public/blaze_model/face_4cl/group1-shard1of1.bin and public/blaze_model/face_4cl/model.json.

Face Auto Capture Component

  • (Optional) ['png'] string imageType – Format of the image returned after successful capture

    • 'jpeg'

    • 'png'

  • (Optional) ['user'] string cameraFacing – Defines which camera to acquire from browser’s getUserMedia API

    • 'user' – The video source is facing toward the user; this is the selfie or front-facing camera on a smartphone

    • 'environment' – The video source is facing away from the user, thereby viewing their environment; this is the back camera on a smartphone

  • function photoTakenCb – Callback on successful image capture

  • (Optional) function onError – Callback for case that an error occurred (see Handling errors)

    • (e: Error) ⇒ void

  • object modelUrls - Object with path to the models needed for detection

    • string modelJSON - URL link to the location where the model is hosted

    • string modelBin - URL link to the location where the model is hosted

  • (Optional) object thresholds - Detection configuration

    • (Optional) [0.12] number faceConfidence - Detection confidence threshold

    • (Optional) [0.02] number optimalFaceSizeLimit - Optimal face size ratio deviation tolerance

    • (Optional) [0.42] number optimalFaceSizeParam - Optimal face size ratio

    • (Optional) [0.07] number faceCenterLimit - Tolerance between the image center and the face center

  • (Optional) object uiCustomisation - UI customization of the component (see UI Customization).

Callback parameters

  • Blob image – Returned image on successful capture

  • object data

    • object cameraSettings - MediaTrackSettings object containing used webcam settings. The object in addition contains device name.

    • (Optional) object detection - Object contains all detection parameters and its values. Present if image was taken using auto capture (not manual capture).

    • object imageResolution - Width and height of the captured image.

UI Customization

  • (Optional) object placeholder - Placeholder customization

    • (Optional) enum facePlaceholder - One of the predefined placeholders in component that can be selected:

      • 'circle-solid'

      • 'ellipse-solid'

      • 'man-solid'

      • 'woman-solid'

      • 'square-rounded-dash'

      • 'square-rounded-solid'

      • 'square-dash'

      • 'square-solid'

    • (Optional) string customSVG - Alternatively, in a future release, a string with custom svg will be able to be provided (see UI Customization examples)

  • (Optional) object instructions - Modification of default messages for localization or customization

    • (Optional) ['Stay still…'] string candidate_selection - Shown when all validations are passed, i.e. image is suitable for capture

    • (Optional) ['Move back'] string face_too_close - Shown when the face is too close to the camera

    • (Optional) ['Move closer'] string face_too_far - Shown when the face is too far from the camera

    • (Optional) ['Center your face'] string face_centering - Shown when the face is not centered in the placeholder

    • (Optional) ['Show your face'] string face_not_present - Shown when no face is detected

  • (Optional) colors - Colors in Web DOT Face Auto Capture may be customized in integration

    • (Optional) ['white'] color placeholderColor - Color of the placeholder lines

    • (Optional) ['#00BFB2'] color placeholderColorSuccess - Color of the placeholder lines when all validations are passed

    • (Optional) ['white'] color instructionColor - Instruction background color

    • (Optional) ['#00BFB2'] color instructionColorSuccess - Instruction background color when all validations are passed

    • (Optional) ['black'] color instructionTextColor - Instruction text color

UI Customization examples

<FaceCamera
  modelUrls={modelUrls}
  photoTakenCb={handleFacePhotoTaken}
  uiCustomisation = {{
    placeholder: {
      facePlaceholder: 'ellipse-solid',
    },
    instructions: {
      face_too_close: 'Your face is too close',
      face_too_far: 'Your face is too far',
    },
    colors: {
      placeholderColor: '#EEEEEE',
      instructionTextColor: '#080808',
    },
  }}
/>

Custom SVG placeholder images are not yet supported, but will be available in a future release

Handling errors

Component uses the MediaDevices API that provides access to connected media input devices like cameras and microphones. If the user denies permission, or webcam is not available, then error is thrown and handled by onError callback. List of possible errors you can find on MDN docs.

Download

Github repository

Appendix

Changelog

2.3.1 - 2022-01-10

Fixed

  • Fix bug causing integration error

2.3.0 - 2022-01-05

Added

  • add cameraSettings into photoTakenCb callBack function

  • Redesign of the UI of Face Auto Capture component.

Changed

  • photoTakenCb callBack function structure

2.2.2 - 2021-12-17

  • Incremental version upgrade

2.2.1 - 2021-12-09

Changed

  • Hide switch camera button if there is only 1 webcam available

2.2.0 - 2021-11-30

Added

  • thresholds.faceConfidence - Detection confidence threshold with default value 0.12

  • modelUrls - Object with path to the models needed for detection

Changed

  • integrated new neural network for face detection

  • dynamic import of TensorFlow.js libraries

2.1.0 - 2021-11-18

  • First released version

← DOT Web Face Auto Capture
DOT Web Face Auto Capture →