Merge pull request #8 from Dynamsoft/_dev

3.2.0

Author: Keillion

.gitignore

@@ -29,6 +29,7 @@ __pycache__
 package-lock.json
 yarn.lock
 .git
+.npmrc
 /*.zip
 /*.py
 /*.exe

Api Reference.url

@@ -1,2 +1,2 @@
 [InternetShortcut]
-URL=https://www.dynamsoft.com/camera-enhancer/docs/programming/javascript/api-reference/?ver=3.1.0
+URL=https://www.dynamsoft.com/camera-enhancer/docs/programming/javascript/api-reference/?ver=3.2.0

LICENSE

@@ -0,0 +1,4 @@
+Copyright © 2003–2022 Dynamsoft. All Rights Reserved.
+
+The use of this software is governed by the Dynamsoft Terms and Conditions.
+https://www.dynamsoft.com/company/license-agreement/

README.md

@@ -7,21 +7,31 @@ Once integrated, your users can open your website in a browser, access their cam
 > **Example Usage**
 >
 > See how Dynamsoft Camera Enhancer helps in camera control and video recognition:
+>
 > - **Barcode scanning from video stream**: check [Dynamsoft Barcode Reader JS User Guide](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/user-guide/?ver=latest)
 > - **MRZ scanning and OCR from video stream**: check [Dynamsoft Label Recognizer JS User Guide](https://www.dynamsoft.com/label-recognition/programming/javascript/user-guide.html?ver=latest&utm_source=dceguide)
 
 In this guide, you will learn step by step on how to integrate the Dynamsoft Camera Enhancer SDK into your website.
 
-**Table of Contents**
-
-* [Getting Started](#getting-started)
-  * [Include the SDK](#include-the-sdk)
-  * [Interact with the SDK](#interact-with-the-sdk)
-* [Hosting the SDK](#hosting-the-sdk)
-* [FAQ](#faq)
-* [API Documentation](#api-documentation)
-* [Release Notes](#release-notes)
-* [Next Steps](#next-steps)
+- [Dynamsoft Camera Enhancer for Your Website](#dynamsoft-camera-enhancer-for-your-website)
+  - [Getting Started](#getting-started)
+    - [Include the SDK](#include-the-sdk)
+      - [Use a CDN](#use-a-cdn)
+      - [Host the SDK yourself](#host-the-sdk-yourself)
+    - [Interact with the SDK](#interact-with-the-sdk)
+      - [Create a `CameraEnhancer` object](#create-a-cameraenhancer-object)
+      - [Configure the `CameraEnhancer` object](#configure-the-cameraenhancer-object)
+      - [Customize the UI](#customize-the-ui)
+  - [Hosting the SDK](#hosting-the-sdk)
+    - [Step One: Deploy the dist folder](#step-one-deploy-the-dist-folder)
+    - [Step Two: Configure the Server](#step-two-configure-the-server)
+    - [Step Three: Include the SDK from the server](#step-three-include-the-sdk-from-the-server)
+  - [FAQ](#faq)
+    - [Can I open the web page directly from the hard drive?](#can-i-open-the-web-page-directly-from-the-hard-drive)
+    - [Why can't I use my camera?](#why-cant-i-use-my-camera)
+  - [API Documentation](#api-documentation)
+  - [Release Notes](#release-notes)
+  - [Next Steps](#next-steps)
 
 ## Getting Started
 
@@ -31,35 +41,37 @@ In this guide, you will learn step by step on how to integrate the Dynamsoft Cam
 
 The simplest way to include the SDK is to use either the [jsDelivr](https://jsdelivr.com/) or [UNPKG](https://unpkg.com/) CDN.
 
-* jsDelivr
+- jsDelivr
 
   ```html
-  <script src="https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@3.1.0/dist/dce.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer/dist/dce.js"></script>
   ```
 
-* UNPKG  
+- UNPKG  
 
   ```html
-  <script src="https://unpkg.com/dynamsoft-camera-enhancer@3.1.0/dist/dce.js"></script>
+  <script src="https://unpkg.com/dynamsoft-camera-enhancer/dist/dce.js"></script>
   ```
 
+> In some rare cases, you might not be able to access the CDN. If this happens, you can use [https://download2.dynamsoft.com/dce/dynamsoft-camera-enhancer-js/dynamsoft-camera-enhancer-js-3.2.0/dist/dce.js](https://download2.dynamsoft.com/dce/dynamsoft-camera-enhancer-js/dynamsoft-camera-enhancer-js-3.2.0/dist/dce.js)
+
 #### Host the SDK yourself
 
 Besides using the CDN, you can also download the SDK and host it locally.
 
 The following shows a few ways to download the SDK.
 
-* From the website
+- From the website
 
   [Download the JavaScript Package](https://www.dynamsoft.com/camera-enhancer/downloads/1000021-confirmation/?utm_source=github)
 
-* yarn
+- yarn
 
   ```cmd
   yarn add dynamsoft-camera-enhancer
   ```
 
-* npm
+- npm
 
   ```cmd
   npm install dynamsoft-camera-enhancer --save
@@ -68,7 +80,7 @@ The following shows a few ways to download the SDK.
 Depending on how you downloaded the SDK and where you put it. You can typically include it like this:
 
 ```html
-<script src="/dce-js-3.1.0/dist/dce.js"></script>
+<script src="/dce-js-3.2.0/dist/dce.js"></script>
 ```
 
 or
@@ -105,8 +117,9 @@ As shown in the code snippet below, before opening the video stream, we need to
 <script>
   (async () => {
       let enhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance();
-      await enhancer.open();
+      await enhancer.setUIElement(Dynamsoft.DCE.CameraEnhancer.defaultUIElementURL);
       document.getElementById("enhancerUIContainer").appendChild(enhancer.getUIElement());
+      await enhancer.open();
   })();
 </script>
 ```
@@ -134,10 +147,11 @@ Dynamsoft.DCE.CameraEnhancer.defaultUIElementURL = "THE-URL-TO-THE-FILE";
 <script>
   (async () => {
     let enhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance();
-    // In order to get the UIElement to put on the page, call open() first.
-    await enhancer.open();
-    // Gets the internally built UI element and bind it to an element on the page.
+    //  Sets the internally built UI element
+    await enhancer.setUIElement(Dynamsoft.DCE.CameraEnhancer.defaultUIElementURL);
+    // Gets the internally built UI element and add it to the page.
     document.getElementById("enhancerUIContainer").appendChild(enhancer.getUIElement());
+    await enhancer.open();
     // The following line hides the close button
     document.getElementsByClassName("dce-btn-close")[0].style.display = "none";
   })();
@@ -173,7 +187,7 @@ Dynamsoft.DCE.CameraEnhancer.defaultUIElementURL = "THE-URL-TO-THE-FILE";
   <select class="dce-sel-resolution"></select>
   ```
 
-  > By default, only 4 hard-coded resolutions (3840 x 2160, 1920 x 1080, 1280 x 720, 640 x 480), are populated as options. You can show a customized set of options by hardcoding them.
+  > By default, only 3 hard-coded resolutions (1920 x 1080, 1280 x 720, 640 x 480), are populated as options. You can show a customized set of options by hardcoding them.
 
   ```html
   <select class="dce-sel-resolution">

dist/dce.esm.js

@@ -36,7 +36,7 @@ export default class CameraEnhancer implements ImageSource {
     private static _engineResourcePath?;
     /**
      * ```js
-     * Dynamsoft.DCE.CameraEnhancer.engineResourcePath = "https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@3.1.0/dist/";
+     * Dynamsoft.DCE.CameraEnhancer.engineResourcePath = "https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@3.2.0/dist/";
      * ```
     */
     static set engineResourcePath(value: string);
@@ -48,6 +48,10 @@ export default class CameraEnhancer implements ImageSource {
     static isStorageAvailable(type: string): boolean;
     /** @ignore */
     static isDCEFrame(value: any): boolean;
+    static testCameraAccess(): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
     private _maxCvsSideLength;
     private _defaultMaxCvsSideLength;
     /** @ignore */
@@ -60,7 +64,7 @@ export default class CameraEnhancer implements ImageSource {
     /**
      * The url of the default UI.
      * ```js
-     * Dynamsoft.DCE.CameraEnhancer.defaultUIElementURL = "https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@3.1.0/dist/dce.ui.html";
+     * Dynamsoft.DCE.CameraEnhancer.defaultUIElementURL = "https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@3.2.0/dist/dce.ui.html";
      * let pEnhancer = null;
      * (async()=>{
      *     let enhancer = await (pEnhancer = pEnhancer || Dynamsoft.DCE.CameraEnhancer.createInstance());
@@ -167,6 +171,14 @@ export default class CameraEnhancer implements ImageSource {
     private _webGLProgramInfo;
     private _webGLBuffers;
     private _softwareScale;
+    private _scaleCenter;
+    private _focusParameters;
+    private _tapFocusEnabled;
+    private _focusSupported;
+    private _focusArea;
+    private _tapDoFocus;
+    private _touchMoved;
+    private _touchMoveEvent;
     private _recordedStates;
     /**
      * @deprecated
@@ -297,6 +309,11 @@ export default class CameraEnhancer implements ImageSource {
     private _arrScanRegionOverlays;
     private _drawingLayersManager;
     private _layerBaseCvs;
+    private _drawingLayerOfTip;
+    private _tipStyleId;
+    private _tipArgs;
+    private _hideTipTimeoutId;
+    onTipSuggested: (occasion: string, message: string) => void;
     /**
      * Set the scan region.
      * ```js
@@ -352,7 +369,7 @@ export default class CameraEnhancer implements ImageSource {
      * ```
      * @see [[getViewDecorator]],[[setViewDecoratorLineWidth]],[[setViewDecoratorStrokeStyle]],[[setViewDecoratorFillStyle]],[[setViewDecoratorMaskFillStyle]]
      */
-    setViewDecorator(type: string | string[], area: Area): void;
+    setViewDecorator(type: "rectangle" | "focus" | "crossline" | "crosshair" | string[], area: Area): void;
     /**
      * Return the view decorator type, area and the decorator itself in a object.
      * @see [[setViewDecorator]]
@@ -364,22 +381,22 @@ export default class CameraEnhancer implements ImageSource {
      * Set the line width for drawing the view decorator.
      * @see [[setViewDecorator]]
      */
-    setViewDecoratorLineWidth(type: string, width: number): void;
+    setViewDecoratorLineWidth(type: "rectangle" | "focus" | "crossline" | "crosshair", width: number): void;
     /**
      * Set the stroke style for drawing the view decorator.
      * @see [[setViewDecorator]]
      */
-    setViewDecoratorStrokeStyle(type: string, style: string): void;
+    setViewDecoratorStrokeStyle(type: "rectangle" | "focus" | "crossline" | "crosshair", style: string): void;
     /**
      * Set the fill style for drawing the view decorator.
      * @see [[setViewDecorator]]
      */
-    setViewDecoratorFillStyle(type: string, style: string): void;
+    setViewDecoratorFillStyle(type: "rectangle" | "focus", style: string): void;
     /**
      * Set the fill style for drawing the mask for the view decorator.
      * @see [[setViewDecorator]]
      */
-    setViewDecoratorMaskFillStyle(type: string, style: string): void;
+    setViewDecoratorMaskFillStyle(type: "rectangle" | "focus", style: string): void;
     /**
      * Might be called when:
      * 1. 'setViewDecoratorLineWidth', 'setViewDecoratorStrokeStyle', 'setViewDecoratorFillStyle' or 'setViewDecoratorMaskFillStyle' is called;
@@ -658,7 +675,7 @@ export default class CameraEnhancer implements ImageSource {
      * ```
      * @see [[off]]
      */
-    on(eventName: string, listener: Function): void;
+    on(eventName: "cameraOpen" | "cameraClose" | "cameraChange" | "resolutionChange" | "played" | "singleFrameAcquired" | "frameAddedToBuffer", listener: Function): void;
     /**
      * Remove the specified event handler.
      * ```js
@@ -672,7 +689,7 @@ export default class CameraEnhancer implements ImageSource {
      * ```
      * @see [[on]]
      */
-    off(eventName: string, listener: Function): void;
+    off(eventName: "cameraOpen" | "cameraClose" | "cameraChange" | "resolutionChange" | "played" | "singleFrameAcquired" | "frameAddedToBuffer", listener: Function): void;
     /**
      * Remove event handlers of specified type.
      * @param eventName
@@ -798,17 +815,44 @@ export default class CameraEnhancer implements ImageSource {
      */
     setExposureCompensation(value: number): Promise<void>;
     getExposureCompensation(): number;
+    private _setHardwareScale;
+    private _getHardwareScale;
+    private _setSoftwareScale;
+    private _getSoftwareScale;
+    private _setScaleCenter;
+    private _resetScaleCenter;
+    private _isVideoCenter;
+    /**
+     *
+     * @param value
+     * @deprecated
+     */
+    private _setZoom;
     /**
      * Adjusts the zoom ratio.
      * Only available when the camera is open.
      * ```js
-     * await enhancer.setZoom(400);
+     * await enhancer.setZoom({factor: 2});
      * ```
      * @see [[getCapabilities]]
      * @category Camera Settings
      */
-    setZoom(value: number): Promise<void>;
+    setZoom(settings: number | {
+        factor: number;
+        centerPoint?: {
+            x: string;
+            y: string;
+        };
+    }): Promise<void>;
+    /**
+     * @returns
+     * @deprecated
+     */
     getZoom(): number;
+    getZoomSettings(): {
+        factor: number;
+    };
+    resetZoom(): Promise<void>;
     /**
      * Adjusts the frame rate. Only available in Chrome, Edge and Safari.
      * Only available when the camera is open.
@@ -830,6 +874,7 @@ export default class CameraEnhancer implements ImageSource {
      * @category Camera Settings
      */
     getFrameRate(): number;
+    private _setFocus;
     /**
      * Adjusts the focus distance. Only available in Chrome and Edge.
      * Only available when the camera is open.
@@ -840,7 +885,22 @@ export default class CameraEnhancer implements ImageSource {
      * @see [[getFocus]],[[getCapabilities]]
      * @category Camera Settings
      */
-    setFocus(mode: string, distance?: number): Promise<void>;
+    setFocus(settings: string | {
+        mode: string;
+    } | {
+        mode: "manual";
+        distance: number;
+    } | {
+        mode: "manual";
+        area: {
+            centerPoint: {
+                x: string;
+                y: string;
+            };
+            width?: string;
+            height?: string;
+        };
+    }, distance?: number): Promise<void>;
     /**
      * Get the focus distance.
      * Only available when the camera is open.
@@ -849,12 +909,16 @@ export default class CameraEnhancer implements ImageSource {
      * ```
      * @see [[setFocus]],[[getCapabilities]]
      * @category Camera Settings
+     * @deprecated
      */
     getFocus(): Object;
-    private _setHardwareScale;
-    private _getHardwareScale;
-    private _setSoftwareScale;
-    private _getSoftwareScale;
+    getFocusSettings(): Object;
+    private _setFocusAndGetContract;
+    private _doFocusDetail;
+    private _setLocalFocus;
+    enableTapToFocus(): Promise<void>;
+    disableTapToFocus(): void;
+    isTapToFocusEnabled(): boolean;
     /**
      * Might be called when:
      * 1. container resizes;
@@ -901,6 +965,10 @@ export default class CameraEnhancer implements ImageSource {
         region?: Region;
         pixelFormat?: PixelFormat;
         scale?: number;
+        scaleCenter?: {
+            x: string;
+            y: string;
+        };
     }): DCEFrame;
     /**
      * @private
@@ -927,6 +995,7 @@ export default class CameraEnhancer implements ImageSource {
      * @see [[maxNumberOfFramesInBuffer]],[[numberOfFramesInBuffer]]
      */
     getFrameFromBuffer(index?: number): DCEFrame;
+    clearFrameBuffer(): void;
     /**
      * Force lose webgl context.
      * @private
@@ -944,6 +1013,7 @@ export default class CameraEnhancer implements ImageSource {
      */
     private _updateDrawingLayersSize;
     _createDrawingLayer(drawingLayerId?: number): import("./drawinglayer").default;
+    deleteDrawingLayer(drawingLayerId: number): void;
     createDrawingLayer(): import("./drawinglayer").default;
     getDrawingLayer(drawingLayerId: number): import("./drawinglayer").default;
     getDrawingLayers(): import("./drawinglayer").default[];
@@ -953,6 +1023,10 @@ export default class CameraEnhancer implements ImageSource {
     getDrawingStyles(): import("..").DrawingStyle[];
     updateDrawingStyle(styleId: number, styleDefinition: any): void;
     clearDrawingLayers(): void;
+    showTip(x: number, y: number, width: number, initialMessage?: string, duration?: number, autoShowSuggestedTip?: boolean): void;
+    hideTip(): void;
+    updateTipMessage(message: string): void;
+    suggestTip(occasion: string, message: string): void;
     private _controler;
     _createControler(): Controler;
     _destroyControler(): void;