DOT Web Palm Capture

v7.2.1

Introduction

DOT Web Palm Capture is set of Non-ui component and Ui component web components to capture image of an palm.

Non-ui component is a web component that renders the video stream from an available phone or web camera to automatically capture an image of an palm with the required quality.

Ui component is a web component that renders an overlay over video stream. Overlay includes a placeholder, camera control buttons and instructions to guide the user to position the palm correctly.

Supported Browsers

DOT Web Palm Capture was tested with:

Chrome on desktop (Windows, Mac and Linux) and mobile (Android, iPhone)
Firefox on desktop (Windows, Mac and Linux) and mobile (Android)****
Edge on Windows
Safari on Mac, iPad and iPhone
WebView on Android*
SafariVC on iPad and iPhone**
WKWebView on iPad and iPhone***

Known issues:

* Some older Android phones can experience issues with camera stream initialization using WebRTC. Our web components will work on most of them, but camera stream could be slow and laggy. This issue is caused by device and can be experienced in any website using WebRTC in Android WebView.

** Components are tested with SafariVC on devices iPhone 7 and newer with iOS 15 or iPadOS 15 or newer. Older devices or iOS versions are not officially supported and might experience issues.

*** In order to run DOT Web Palm Capture in WKWebView on iPhone or iPad, allowsInlineMediaPlayback and mediaTypesRequiringUserActionForPlayback properties on WKWebViewConfiguration must be set to true.

**** Some older and/or low-end Android phones can experience issues with camera stream initialization using WebRTC when using Firefox browser. Our web components might display The webcam is already in use by another application error. This issue is caused by the Firefox’s implementation of initialization of camera and can be experienced in any website using WebRTC in Firefox on Android. It is recommended to use other supported browsers in those cases.

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, the component must always get the 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.

Non-ui component

Requirements

Minimum required camera resolution for appropriate results is 720x720. Anything less is insufficient.

Initialization

DOT Web Palm Capture can be installed via NPM, yarn or pnpm

npm install @innovatrics/dot-palm-capture

To manually integrate the DOT Web Palm Capture, download latest version from the Github repository. Add following line to dependencies in your package.json:

"dependencies": {
    "@innovatrics/dot-palm-capture": "file:innovatrics-dot-palm-capture-[VERSION].tgz",
}

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

Usage

Palm capture component is a web component which uses custom HTML <x-dot-palm-capture/> tag. Properties cameraOptions needs to be passed into component after <x-dot-palm-capture/> tag was rendered.

import type {
  PalmCameraProps,
  HTMLPalmCaptureElement,
  PalmCallback
} from "@innovatrics/dot-palm-capture";

import { useCallback, useEffect } from "react";
import "@innovatrics/dot-palm-capture";

const PalmCamera = (props: PalmCameraProps) => {
  useEffect(() => {
    const palmAutoCaptureHTMLElement = document.getElementById(
      "x-dot-palm-capture"
    ) as HTMLPalmCaptureElement | null;

    if (palmAutoCaptureHTMLElement) {
      palmAutoCaptureHTMLElement.cameraOptions = props;
    }
  })

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

const Page = () => {

  const handlePalmPhotoTaken: PalmCallback = ({ image, data }, content) => {
    // ...
  };

  // Save function reference to prevent unnecessary reload of component
  const handleError = useCallback(
    (error: Error) => {
      alert(error)
    },
    [],
  );

  return (
    <PalmCamera
      cameraFacing="environment"
      onPhotoTaken={handlePalmPhotoTaken}
      onError={handleError}
      sessionToken="1111-222-333-4444"
    />
  );
};

Alternatively, you can use useRef and useLayoutEffect to render a web component with its props.

import type {
  PalmCameraProps,
  HTMLPalmCaptureElement
} from '@innovatrics/dot-palm-capture';

import { useLayoutEffect, useRef } from 'react';
import '@innovatrics/dot-palm-capture';

const PalmCamera = (props: PalmCameraProps) => {
  const ref = useRef<HTMLPalmCaptureElement | null>(null);

  useLayoutEffect(() => {
    const element = ref.current;

    if (element) {
      element.cameraOptions = props;
    }
  }, [props]);

  return <x-dot-palm-capture ref={ref} id="x-dot-palm-capture" />;
};

TypeScript

Declaration file is bundled inside package. To use with TypeScript, import types from @innovatrics/dot-palm-capture.

import type { PalmCallback, PalmCameraProps } from "@innovatrics/dot-palm-capture";

Hosting dot-assets files

During the initialization phase of the component, the component loads the required assets files, such as WASM binary files, javascript chunks, license etc, via HTTP fetch request. Please note that we do not provide any hosting for those files. That’s why it is essential that the customer provides the component with all files from our distribution. To do so, please:

copy dot-assets directory from our distribution into your distribution every time you update to new version of the component. If you are using package manager, you can find dot-assets directory in node_modules/@innovatrics/dot-palm-capture/dot-assets.
copy iengine.lic (or license.lic) file into dot-assets folder in your distribution.

Structure of the directory in our distribution

@innovatrics/
|__ dot-palm-capture/
    |__ dot-assets/ <-- copy this directory
        |__ palm/
            |__ wasm/
                |-- sam.wasm
                |-- sam_simd.wasm
            |-- dot-<CHUNK_HASH>.js
            ...
        |__ wasm/
            |-- dot_embedded_bg.wasm
    |-- package.json
    |-- README.md
    ...

Example of the dot-assets dir structure in integrator’s application

public/
  |__ dot-assets/ <-- do not change the name or structure of this directory (only add folders for another components when needed)
      |__ palm/
          |__ wasm/
              |-- sam.wasm
              |-- sam_simd.wasm
          |-- dot-<CHUNK_HASH1>.js
          |-- dot-<CHUNK_HASH2>.js
          ...
      ... <-- if you are using other components (e.g. document), the folders with assets of these components will be here (eg. document/)
      |__ wasm/
          |-- dot_embedded_bg.wasm
      |-- iengine.lic
  ...

By default, the component will try to fetch the desired files from <PROJECT_ORIGIN>/dot-assets/. This can be changed using assetsDirectoryPath property. For example, if assetsDirectoryPath=/my-directory property is provided, the component will try to fetch the desired files from <PROJECT_ORIGIN>/my-directory/dot-assets/. Please note that structure and the name of the directory must be preserved. For more information, check out our samples on Github where you can find real examples of how to host files in various technologies such as React, Angular, Vue, etc.

Please note, that if you use multiple components (e.g. palm and document) you need to make sure, that all of the needed files are present in appropriate folders:

public/
  |__ dot-assets/ <-- do not change the name or structure of this directory (only add folders for another components when needed)
      |__ face/ <-- copied from @innovatrics/dot-palm-capture
          |__ palm/
              |-- sam.wasm
              |-- sam_simd.wasm
          |-- dot-<CHUNK_HASH1>.js
          |-- dot-<CHUNK_HASH2>.js
      |__ another_component/ <-- copied from another components' node_modules
          |__ wasm/
              |-- sam.wasm
              |-- sam_simd.wasm
          |-- dot-<CHUNK_HASH1>.js
          |-- dot-<CHUNK_HASH2>.js
      ...
  ...

Troubleshooting

If you are having difficulties with hosting wasm files, check your browser console in dev tools. You should see an error message with more details about the problem. It’s also a good idea to look at the network tab in the developer tools and check that the wasm file has been loaded correctly. Please pay close attention to the actual response of the wasm load request, as an HTTP 200 status does not necessarily mean that the wasm file was loaded correctly. If you see application/wasm in response type, then wasm file was loaded correctly. If you see e.g. text/html in response type, then wasm file was not loaded correctly.

Licensing

In order to support wide adoption of the components, a free mode was developed in addition to the premium mode used by licensed customers.

Free mode

Components run in the free mode by default. This mode does not impose any feature limits, it just displays an watermark overlay over the component, to indicate not-licensed deployment. The overlay looks as on the image below:

Premium

To run components in premium mode, dot_embedded_bg.wasm and valid license files are needed. To initialize WASM binary file please follow a steps in [Hosting WASM files]. To use your license file you need to copy it to project public directory within dot-assets directory as <PROJECT_ORIGIN>/dot-assets/iengine.lic. By default, the component will try to fetch the desired license file from <PROJECT_ORIGIN>/dot-assets/iengine.lic or <PROJECT_ORIGIN>/dot-assets/license.lic*. This can be changed using assetsDirectoryPath property.

* Please note that fetching license from <PROJECT_ORIGIN>/dot-assets/license.lic by default is deprecated and will be removed in future versions. Please use <PROJECT_ORIGIN>/dot-assets/iengine.lic instead.

If one of the following steps fails, then component will run in [Freemium] mode:

WASM binary file not found
license file not found
license is not valid

In order to obtain the license, please contact your Innovatrics’ representative.

Properties

(Optional) string cameraFacing – Defines which camera to acquire from browser’s getUserMedia API. Default camera facing for mobile phones is set to environment and for others platforms is set to user
- '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 onPhotoTaken – Callback on successful image capture
- (image, data) ⇒ void - (see Callback parameters)
function onError – Callback for the case that an error occurred (see Handling errors)
- (e: Error) ⇒ void
(Optional) string assetsDirectoryPath - Path to the dot-assets directory
(Optional) string sessionToken – Unique identifier of the session
(Optional) object thresholds - Detection configuration
- (Optional) [0.8] number confidenceThreshold - Detection confidence threshold
- (Optional) [0.25] number brightnessLowThreshold - Low brightness threshold
- (Optional) [0.9] number brightnessHighThreshold - High brightness threshold
- (optional) [0.03] number outOfBoundsThreshold - Palm out of bounds threshold
- (Optional) [0.06] number sharpnessThreshold - Low sharpness threshold
- (Optional) [0.34] number sizeSmallThreshold - Small size threshold
- (Optional) [0.46] number sizeLargeThreshold - Large size threshold
(Optional) HTMLElement styleTarget - Provide an alternate DOM node to inject styles. DOM node has to exist inside DOM before auto-capture component is initialized. This is useful when rendering components in a shadow DOM. By default, the styles are injected into the <head> element of the palm. See [style-target] example for more details.

Callback parameters

object data
- Blob image – Returned image on successful capture in jpeg format
- object data
  - 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.
Uint8Array content - output for DOT Digital Identity Service

Multi capture

Palm capture component allows you to capture an unlimited number of palms without the need to reinitialize the webcam and detector. This allows you to capture two sides of a palm or multiple palms. Component calls onPhotoTaken callback on every captured palm photo. When onPhotoTaken is called, detection is paused. Camera stream and palm detector stay initialized. Component is in waiting state. You should implement a custom UI for waiting state (e.g. overlay over our component). We provide a default UI, but it is not customizable.

To continue detection, dispatch continue-detection event.

Implement dispatch 'continue-detection' event

import { dispatchControlEvent, PalmCustomEvent, ControlEventInstruction } from "@innovatrics/dot-palm-capture/events";

const continueDetection = () => {
  dispatchControlEvent(PalmCustomEvent.CONTROL, ControlEventInstruction.CONTINUE_DETECTION)
};

Without importing @innovatrics/dot-palm-capture/events.

function continueDetection() {
  document.dispatchEvent(
    new CustomEvent("palm-capture:control", {
      detail: { instruction: "continue-detection" },
    }),
  );
}

Capture mode

Defines a strategy for how a detection captures the desired image.

Auto capture

It is an automated process that attempts to capture multiple valid images and selects the best one from them. If the component captures at least two valid images, it enters a phase called candidate selection. Once this phase is complete, the best image is selected and returned by the component using the onPhotoTaken callback.

Wait for request

It is a manual process that allows you to capture an image on request. In this mode, the component is ready and waiting for your command. More details about how to request an image can be found in Control Events. Once the component receives a request, it returns either the first image or the first valid image using the onPhotoTaken callback.

Please note that in this mode, the candidate selection phase used in Auto capture is ignored.

Handling errors

When an error occurs we call onError callback with one parameter of type Error. We set name property to AutoCaptureError and also message with more details. Component renders default UI for error state but is not customizable, and integrator should implement own error handling. Component uses the MediaDevices API that provides access to connected media input devices like cameras and microphones. If the user denies permission to access or the webcam is not present, an error is thrown. We provide original error thrown by browser inside cause property of the error object. List of possible errors can be found on MDN docs.

Error example:

{
  name: "AutoCaptureError",
  message: "The webcam is already in use by another application",
  cause: DOMException: Could not start video source // Original error thrown by browser MediaDevices API
}

Ui component

Requirements

Both components must be wrapped in parent div with position: relative.

<div style={{position: "relative"}}>
  <PalmUi showCameraButtons />
  <PalmCamera
    cameraFacing="environment"
    onPhotoTaken={handlePhotoTaken}
    onError={onError}
  />
</div>

Initialization

UI component can be installed via NPM, yarn or pnpm

npm install @innovatrics/dot-auto-capture-ui

To manually integrate UI component, download latest version from the Github repository. Add following line to dependencies in your package.json:

"dependencies": {
    "@innovatrics/dot-auto-capture-ui": "file:innovatrics-dot-auto-capture-ui-[VERSION].tgz",
}

where [VERSION] is the DOT Web Palm Capture version integrated. This installs dot-auto-capture-ui as an external module that can be used (just like any other module in the code). For example, one could do import '@innovatrics/dot-auto-capture-ui'; in the app.

Usage

Palm capture UI component is an web component which uses custom HTML <x-dot-palm-capture-ui /> tag. Properties props needs to be passed into component after <x-dot-palm-capture-ui /> tag was rendered.

import type { PalmUiProps, HTMLPalmUiElement } from "@innovatrics/dot-auto-capture-ui/palm";

import { useEffect } from "react";
import "@innovatrics/dot-auto-capture-ui/palm";

const PalmUi = (props: PalmUiProps) => {
  useEffect(() => {
    const uiElement = document.getElementById("x-dot-palm-capture-ui") as HTMLPalmUiElement | null;

    if (uiElement) {
      uiElement.props = props;
    }
  });

  return <x-dot-palm-capture-ui id="x-dot-palm-capture-ui" />;
};

Alternatively, you can use useRef and useLayoutEffect to render a web component with its props.

import type { PalmUiProps, HTMLPalmUiElement } from "@innovatrics/dot-auto-capture-ui/palm";

import { useLayoutEffect, useRef } from "react";
import "@innovatrics/dot-auto-capture-ui/palm";

const PalmUi = (props: PalmUiProps) => {
  const ref = useRef<HTMLPalmUiElement | null>(null);

  useLayoutEffect(() => {
    const element = ref.current;

    if (element) {
      element.props = props;
    }
  }, [props]);

  return <x-dot-palm-capture-ui id="x-dot-palm-capture-ui" ref={ref} />;
};

TypeScript

Declaration files are bundled inside package. Just import types from @innovatrics/dot-auto-capture-ui/palm.

Properties

(Optional) object instructions - Modification of default messages for localization or customization
- (Optional) ['Hold still…'] string candidate_selection - Shown when all validations are passed, i.e. image is suitable for capture
- (Optional) ['Center your palm'] string palm_centering - Shown when the palm is not centered inside the placeholder
- (Optional) ['Position your palm'] string palm_not_present - Shown when no palm is detected
- (Optional) ['Move closer'] string palm_too_far - Shown when the palm is too far from the camera
- (Optional) ['Move back'] string palm_too_close - Shown when the palm is too close to the camera
- (Optional) ['More light needed'] string sharpness_too_low - Shown when the palm found in the image is not sharp enough
- (Optional) ['More light needed'] string brightness_too_low - Shown when the image is too dark
- (Optional) ['Less light needed'] string brightness_too_high - Shown when the image is too bright
(Optional) theme - Modification of theme properties.
- (Optional) colors - To customize colors of following properties
  - (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
- (Optional) font - To customize font with following properties
  - (Optional) ['Montserrat'] string family - Font family. Please note that the chosen font must be installed and available in the styles of the web components for it to display correctly.
  - (Optional) [14] number minimumSize - Minimum font size, from which the actual font size is calculated relative to the component width/height
  - (Optional) ['normal'] string style - Font style
  - (Optional) [600] string|number weight - Font weight
(Optional) appStateInstructions - Modification of default messages for component state
- (Optional) loading - Component loading state
  - (Optional) ['Loading. Please wait.'] string text - Text shown while component is loading
  - (Optional) [true] boolean visible - Show/hide loading instruction while component is loading
- (Optional) waiting - Component waiting state
  - (Optional) ['Waiting for input'] string text - Text shown while component is waiting
  - (Optional) [true] boolean visible - Show/hide waiting instruction while component is waiting
(Optional) [false] boolean showDetectionLayer - Show/hide detection layer on top of component
(Optional) [false] boolean showCameraButtons - Show/hide camera buttons (switch camera and toggle mirror) on top of component
(Optional) HTMLElement styleTarget - Provide an alternate DOM node to inject styles. DOM node has to exist inside DOM before auto-capture component is initialized. This is useful when rendering components in a shadow DOM. By default, the styles are injected into the <head> element of the palm. See [style-target] example for more details.
(Optional) ['AUTO_CAPTURE'] captureMode - Defines a strategy for how a detection captures the desired image
- 'AUTO_CAPTURE' - It is a standard way of how a detection captures an image. See Auto capture
- 'WAIT_FOR_REQUEST' - Detection waits for request to capture an image. See Wait for request

Example how to use UI properties:

<PalmUi
  theme={{ colors: { placeholderColor: "green" }, font: { style: 'italic' } }}
  placeholder="id-dash"
  instructions={{ candidate_selection: "Candidate selection" }}
  appStateInstructions={{ loading: { text: "Component is loading", visible: true } }}
  showDetectionLayer
  showCameraButtons
/>

Example how to import fonts (using head in main html file):

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="" href="" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Title</title>
    <!-- import font in the head -->
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Montserrat&display=swap" rel="stylesheet">
    <!------->
  </head>
</html>

Example how to use styleTarget prop with Ui component when using Shadow DOM: This approach also works for Non-ui component.

import type { PalmUiProps, HTMLPalmUiElement } from "@innovatrics/dot-auto-capture-ui/palm";
import "@innovatrics/dot-auto-capture-ui/palm";
import { useEffect } from "react";

const PalmUi = (props: PalmUiProps) => {
  useEffect(() => {
    const uiElement = document.getElementById(
      "x-dot-palm-capture-ui"
    ) as HTMLPalmUiElement | null;

    const styleNode = document.createElement('div');

    uiElement?.shadowRoot?.append(styleNode);

    if (uiElement) {
       uiElement.props = {
        ...props,
        styleTarget: styleNode,
      };
    }
  });

  return <x-dot-palm-capture-ui id="x-dot-palm-capture-ui" />;
};

HTML of example above will look like this:

<x-dot-palm-capture-ui id="x-dot-palm-capture-ui">
  #shadow-root (open)
    <div>
      <style data-styled="active" data-styled-version="6.1.0">
        /* CSS styles will be injected here*/
      </style>
    </div>
</x-dot-palm-capture-ui>

Custom Events - Optional

Communication between components is based on custom events. Ui component is mostly listening to events dispatched by Non-ui component. In case of CONTROL event, Ui component dispatches control events to control Non-ui component.

When using default Ui component, only dispatch continue-detection event has to be implemented to use Multi capture.

Type of Events

Currently all events being used are described in this section. These are sufficient to build custom UI layer.

enum PalmCustomEvent - Event names dispatched by components
- CONTROL = 'palm-capture:control' - Events dispatched from Ui component to control Non-ui component. Described in Control Events section
- CAMERA_PROPS_CHANGED = 'palm-capture:camera-props-changed' - Notifies UI when camera properties has changed
- INSTRUCTION_CHANGED = 'palm-capture:instruction-changed' - Notifies the UI when the instruction has changed and whether it has been escalated
- STATE_CHANGED = 'palm-capture:state-changed' - Notifies UI when state of Non-ui component has changed
- DETECTED_PALM_CHANGED = 'palm-capture:detected-palm-changed' - Notifies UI when palm corners are detected. Used in Detection Layer, has no effect if showDetectionLayer = false
- VIDEO_ELEMENT_SIZE = 'palm-capture:video-element-size' - Notifies UI when HTML video element size has changed
enum ComponentCustomEvent - Event names dispatched by components
- REQUEST_CAPTURE - dot-custom-event:request-capture - Event dispatched from outside of Non-ui component to request capture when component is running in WAIT_FOR_REQUEST capture mode. Described in Control Events section

Usage

Import @innovatrics/dot-palm-capture/events to use event types and and dispatch control events.

Listening to the Events

All event listeners are already implemented in default Ui component. Skip this section if you are using default Ui component.

All PalmCustomEvent events, except CONTROL, are dispatched by Palm Auto Capture Non-ui component. Ui component listens to these events to make appropriate changes. See the example below how to register event listeners.

import type {
  PalmInstructionChangeEvent,
  CameraPropsChangeEvent,
  CameraStateChangeEvent,
  DetectedPalmChangeEvent,
  VideoElementSizeChangeEvent
} from "@innovatrics/dot-palm-capture/events";
import { PalmCustomEvent } from "@innovatrics/dot-palm-capture/events";
import type {
  AppState,
  DetectedPalmCorners,
  PalmInstructionCode,
  Resolution,
  AutoCaptureError
} from "@innovatrics/dot-palm-capture";
import { useEffect, useState } from "react";


const Events = () => {
  const [instructionCode, setInstructionCode] = useState<{ code?: PalmInstructionCode; isEscalated: boolean }>();
  const [cameraResolution, setCameraResolution] = useState<Resolution | undefined>();
  const [isMirroring, setIsMirroring] = useState<boolean | undefined>();
  const [appState, setAppState] = useState<AppState | undefined>();
  const [error, setError] = useState<AutoCaptureError | undefined>();
  const [detectedPalmCorners, setDetectedPalmCorners] = useState<DetectedPalmCorners | undefined>();
  const [videoElementSize, setVideoElementSize] = useState<DOMRect | undefined>();


  useEffect(() => {
    const handleInstruction = (event: PalmInstructionChangeEvent) => {
       setInstructionCode({
        code: event?.detail?.instructionCode,
        isEscalated: event?.detail?.isEscalated ?? false,
      });
    };

    const handleCameraProps = (event: CameraPropsChangeEvent) => {
      setCameraResolution(event?.detail?.cameraResolution);
      setIsMirroring(event?.detail?.isMirroring);
    };

    const handleAppState = (event: CameraStateChangeEvent) => {
      setAppState(event?.detail?.appState);

      const error = event?.detail?.error;

      if (error) {
        setError(error);
      }
    };

    const handleDetectedPalm = (event: DetectedPalmChangeEvent) => {
      setDetectedPalmCorners(event?.detail?.detectedCorners);
    };

    const handleVideoElementSize = (event: VideoElementSizeChangeEvent) => {
      setVideoElementSize(event.detail?.size)
    }

    document.addEventListener(PalmCustomEvent.INSTRUCTION_CHANGED, handleInstruction);
    document.addEventListener(PalmCustomEvent.CAMERA_PROPS_CHANGED, handleCameraProps);
    document.addEventListener(PalmCustomEvent.STATE_CHANGED, handleAppState);
    document.addEventListener(PalmCustomEvent.DETECTED_PALM_CHANGED, handleDetectedPalm);
    document.addEventListener(PalmCustomEvent.VIDEO_ELEMENT_SIZE, handleVideoElementSize)

    return () => {
      document.removeEventListener(PalmCustomEvent.INSTRUCTION_CHANGED, handleInstruction);
      document.removeEventListener(PalmCustomEvent.CAMERA_PROPS_CHANGED, handleCameraProps);
      document.removeEventListener(PalmCustomEvent.STATE_CHANGED, handleAppState);
      document.removeEventListener(PalmCustomEvent.DETECTED_PALM_CHANGED, handleDetectedPalm);
      document.removeEventListener(PalmCustomEvent.VIDEO_ELEMENT_SIZE, handleVideoElementSize);
    };
  }, [])
}

Without importing @innovatrics/dot-palm-capture/events you can use values of PalmCustomEvent directly.

const instructionChangeEvent = "palm-capture:instruction-changed";

function handleInstructionChange(event) {
  console.log(event.detail.instructionCode)
  console.log(event.detail.isEscalated)
}

document.addEventListener(instructionChangeEvent, handleInstructionChange);

/**
 * remove event listener when you're done
 */
document.removeEventListener(instructionChangeEvent, handleInstructionChange);

Control Events

Control events are dispatched from outside of Non-ui component to control it.

`PalmCustomEvent.CONTROL`

Events are dispatched from Ui component to control Non-ui component.

enum ControlEventInstruction
- CONTINUE_DETECTION = 'continue-detection' - Controls Multi capture
- SWITCH_CAMERA = 'switch-camera' - Notifies Palm Auto Capture to use different camera
- TOGGLE_MIRROR = 'toggle-mirror' - Notifies Palm Auto Capture to mirror video stream

import { dispatchControlEvent, PalmCustomEvent, ControlEventInstruction } from "@innovatrics/dot-palm-capture/events";

export const Dispatch = () => {

  const continueDetection = () => {
    dispatchControlEvent(PalmCustomEvent.CONTROL, ControlEventInstruction.CONTINUE_DETECTION)
  }

  const switchCamera = () => {
    dispatchControlEvent(PalmCustomEvent.CONTROL, ControlEventInstruction.SWITCH_CAMERA)
  }

  const toggleMirror = () => {
    dispatchControlEvent(PalmCustomEvent.CONTROL, ControlEventInstruction.TOGGLE_MIRROR)
  }

  return (
    <div>
      <button onClick={continueDetection}>Continue detection</button>
      <button onClick={switchCamera}>Switch camera</button>
      <button onClick={toggleMirror}>Mirror camera</button>
    </div>
  )
}

Without importing @innovatrics/dot-palm-capture/events you can use values of PalmCustomEvent and ControlEventInstruction directly.

const continueDetection = () => {
  document.dispatchEvent(
    new CustomEvent("palm-capture:control", {
      detail: { instruction: "continue-detection" },
    }),
  );
}

`ComponentCustomEvent.REQUEST_CAPTURE`

enum RequestCaptureInstruction
- FIRST_FRAME = 'first-frame' - Notifies Palm Auto Capture to capture the very first image right after capturing this event. Validation and detection results are not evaluated in the process
- FIRST_VALID_FRAME = 'first-valid-frame' - Notifies Palm Auto Capture to capture the very first valid image right after capturing this event. Validation and detection results are evaluated in the process

import { dispatchCaptureEvent, ComponentCustomEvent, RequestCaptureInstruction } from "@innovatrics/dot-palm-auto-capture/events";

export const Dispatch = () => {

  const captureAnyImage = () => {
    dispatchCaptureEvent(ComponentCustomEvent.REQUEST_CAPTURE, RequestCaptureInstruction.FIRST_FRAME)
  }

  const captureValidImage = () => {
    dispatchCaptureEvent(ComponentCustomEvent.REQUEST_CAPTURE, RequestCaptureInstruction.FIRST_VALID_FRAME)
  }

  return (
    <div>
      <button onClick={captureAnyImage}>Capture any image</button>
      <button onClick={captureValidImage}>Capture valid image</button>
    </div>
  )
}

Without importing @innovatrics/dot-palm-auto-capture/events you can use values of ComponentCustomEvent and RequestCaptureInstruction directly.

const captureAnyImage = () => {
  document.dispatchEvent(
    new CustomEvent("dot-custom-event:request-capture", {
      detail: { instruction: "first-frame" },
    }),
  );
}

const captureValidImage = () => {
  document.dispatchEvent(
    new CustomEvent("dot-custom-event:request-capture", {
      detail: { instruction: "first-valid-frame" },
    }),
  );
}

Example of using components together

import type { PalmCallback } from "@innovatrics/dot-palm-capture";
import {
  dispatchControlEvent,
  PalmCustomEvent,
  ControlEventInstruction
} from "@innovatrics/dot-palm-capture/events";
import { useCallback } from "react";

import PalmCamera from "./camera";
import PalmUi from "./PalmUi";

const PalmAutoCapture = () => {
  const handlePhotoTaken: PalmCallback = ({ image, data }, content) => {
    console.log(image, data);
  }

  const handleError = useCallback(
    (error: Error) => {
      alert(error)
    },
    [],
  );

  const handleContinueDetection = () => {
    dispatchControlEvent(PalmCustomEvent.CONTROL, ControlEventInstruction.CONTINUE_DETECTION)
  };

  return (
    <div>
      <button onClick={handleContinueDetection}>Continue detection</button>
      <div style={{ position: "relative" }}>
        <PalmUi />
        <PalmCamera
          cameraFacing="environment"
          onPhotoTaken={handlePhotoTaken}
          onError={handleError}
        />
      </div>
    </div>
  );
};

typescript events types import

7.2.0 - 2025-03-24

First released version