@idscan/idvc2 2.0.1

package/README.md

@@ -0,0 +1,727 @@
+## Overview
+
+Upon being switched on, the library integrates the component of capturing the documents and faces from a video to your page.
+
+## Use cases
+
+- Capture and determination of the document type
+- Capture of pdf417
+- Capture of MRZ
+- Capture of faces
+
+## Recommendations
+
+Use a modern phone with a good camera having the definition of not less than 8 megapixels.
+The capture must be made in a well-lighted room. A document must be located at the uniform background.
+
+## Limitations
+
+This component works in phones with the operating system Android in the browser Chrome (minimum version 52) and in phones with the operating system iOS (minimum version 11) in the browser Safari
+
+## Installation
+
+```
+$ npm install @idscan/idvc
+```
+
+This component contains JS, CSS files which require the mandatory import into your project.
+
+1. Before importing, it is necessary to set the webpack-configuration.
+
+*Note: The project must use the webpack 4 and later versions.*
+
+1.1. Add the following rules of loading to the field rules
+```javascript
+{
+  test: /\.css$/,
+  use: ["style-loader", "css-loader"]
+}
+```
+
+1.2. If you prefer to use neural networks from your domain, you should add the 'CopyWebpackPlugin' into the section 'plugins' which will copy the files, which are necessary for the work of the neural network, from the folder to another folder that should be selected by you.
+
+*Note: The structure inside the folder of the component 'networks' must be saved on the server with due regard to the nesting.
+There are binary files in the folder which do not have the extension. These files must be provided by the server with the header `Content-Type: application/octet-stream`.*
+
+*copy-webpack-plugin v.5 and below*
+```javascript
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+
+new CopyWebpackPlugin ([{
+  from: 'node_modules/@idscan/idvc/dist/networks/*',
+  to: 'networks/[name].[ext]',
+  toType: 'template',
+}]);
+```
+*copy-webpack-plugin v.6 and above*
+```javascript
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+
+new CopyWebpackPlugin({
+  patterns: [
+    {
+      from: 'node_modules/@idscan/idvc/dist/networks/*',
+      to: 'networks/[name][ext]',
+      toType: 'template',
+    },
+  ],
+});
+```
+
+1.3. Import the library and css to your project.
+
+```javascript
+import IDVC from '@idscan/idvc'
+import '@idscan/idvc/dist/css/idvc.css'
+
+```
+## Initialization
+
+Create an instance of the object 'IDVC'. The object takes one object of the component configuration as a parameter.
+
+Available fields:
+
+**el** (string) – id of an element on the page where the component will be integrated.
+
+**licenseKey** (string) – key for the library
+
+**autoContinue** (boolean) - this option switches on/off the automatic transition to the next step. Default: false
+
+**resizeUploadedImage** (integer) - sets the maximum size for manually loaded pictures. Default: -1
+
+**fixFrontOrientAfterUpload** (boolean) - this option provides the possibility to adjust the correct position of the document in case of manual uploading. Default: false
+
+**useCDN** (boolean) - set to true if you prefer to load neural networks from cdn instead of your domain. Default: false
+
+**networkUrl** (string) - path to the folder with neural networks. Specify the path on the server if you need to remove the folder to another location. The default path is 'networks'. Default: 'networks'
+
+**language** (string) - The option sets the language used for the translation of the text in the library
+
+**realFaceMode** (string) - option that enable advanced capture with volumetric face detection. Available values: 'auto', 'none', 'all'. Auto - enable "realFaceMode" only for iphone. All - enable "realFaceMode" for all devices. None - disable this option. Default: 'auto'
+
+**documentTypes** (array) - The option that describes what steps needs for each document type you are needed.
+
+***type*** (array) – array of types of acceptable documents. If you are going to use the component for the document validation, you can limit the list of acceptable documents.
+
+Available types (int):
+
+- **ID (1)** – USA driver license and USA ID (non-driver license), Canadian driver licenses,
+- **Passport (2)** – with 2 lines MRZ
+- **PassportCard (3)** – with 3 lines MRZ (most European IDs, USA passports/cards)
+- **GreenCard (6)** – USA Permanent Resident Cards (only MRZ),
+- **InternationalId (7)** – Internationally approved U.S. IDs with 3 lines MRZ
+- **VIN (8)** – Vehicle Identification Number
+- **Barcode (9)** – 1-d and 2-d barcodes
+
+***steps*** (array) – array of steps which are necessary for you. Every step represents an object with the fields 'type', 'name' and unnecessary 'mode'. The field 'name' is the name of a step, which will be represented in the header.
+The field 'name' is a string type. Represents the step's name.
+
+The field 'mode' is an object that contains two fields: 'uploader' and 'video'. It turns on/off ability of image capturing via file upload and video capture.
+```javascript
+  mode: { uploader: true, video: true }
+```
+
+The field 'type' is a type of a step. Possible variants are:
+- front – capture of a document
+- mrz – detection, capture and parsing of the mrz-code of a document
+- pdf – detection and capture of pdf417 of a document
+- face – detection and capture of a face using the front camera
+- barcode – detection, capture and parsing 1 dimensional (barcodes) or 2 dimensional (qr codes)
+- photo – capture of an image on click without analysis
+
+Steps can be combined in any order and in any combinations, except for the step 'auto'.
+
+E.g.:
+```javascript
+documentTypes: [
+  {
+    type: "ID",
+    steps:[
+      { type: 'front', name: 'Document Front', mode: { uploader: true, video: true } },
+      { type: 'pdf', name: 'Document PDF417 Barcode' , mode: { uploader: true, video: true } },
+      { type: 'face', name: 'Face', mode: { uploader: false, video: true } }
+    ]},
+  {
+    type: "Passport",
+    steps:[
+      { type: 'mrz', name: 'Passport Front' , mode: { uploader: true, video: true } },
+      { type: 'face', name: 'Face', mode: { uploader: false, video: true } }
+    ]},
+]
+```
+
+**onChange** - callback-function which will be called after change one step. The returnable value is the object with the type and the image
+
+**onCameraError** - The function that is invoked in case if the camera is not available. The response value is the object with the error code and the message
+
+**onReset** - callback-function which will be called after reset all the steps. The returnable value is the object with the steps
+
+**onRetakeHook** - the function that will be called before reset the current step. The returnable value is the object with the current step
+
+**onMounted** - the function that will be called on the component mounted. This function doesn't return a value.
+
+**changeLanguage** - the function that changes languages of the library.
+
+**submit** - callback-function which will be called after completing all the steps. The returnable value is the object with the following content:
+```javascript
+{
+  steps: [{
+    img: "",
+    type: "front",
+  },
+  …],
+  documentType: 1,
+}
+```
+where documentType – id of a document type ( ID – 1, Passport - 2, PassportCard – 3, GreenCard – 6, InternationalId – 7)
+
+steps – steps with the type and the image in the format 'base64'.
+
+Also, if you use automatic capture, in the "back" step **trackstring** will be returned (raw PDF417 data from Barcode encoded in base64)
+
+Config example:
+
+```javascript
+new IDVC ({
+  el: 'videoCapturingEl',
+  licenseKey: '',
+  networkUrl: 'networks',
+  documentTypes: [
+    {
+      type: "ID",
+      steps:[
+        { type: 'front', name: 'Document Front', mode: { uploader: true, video: true } },
+        { type: 'pdf', name: 'Document PDF417 Barcode', mode: { uploader: true, video: true } },
+        { type: 'face', name: 'Face', mode: { uploader: false, video: true } }
+      ]},
+    {
+      type: "Passport",
+      steps:[
+        { type: 'mrz', name: 'Passport Front' },
+        { type: 'face', name: 'Face' }
+      ]},
+  ]
+})
+```
+
+*Note: Request a license key for the library by emailing
+ [sales@idscan.net](mailto:sales@idscan.net) or [support@idscan.net](mailto:support@idscan.net)*
+
+## Style Customization
+
+To tweak the theme of the component you can redeclare variables in CSS custom properties. Don't forget to place the CSS file with redeclared variables below the component's CSS file. Redeclaration of CSS custom properties looks like this:
+```CSS
+ .idvc {
+   --btn-border-radius-big: 40px;
+   --color-background-white: #000000;
+ }
+```
+
+The component has the following customizable properties:
+
+**--btn-border-radius-big**
+
+*default: 4px*
+
+- radius of retake, continue, submit buttons
+
+**--btn-border-radius-small**
+
+*default: 4px*
+
+- radius of the manual switch button
+- radius of the messagebox
+
+**--color-text-secondary-light**
+
+*default: #C4C4C4*
+
+- 'select document type' menus's checkmark
+
+**--color-positive-light**
+
+*default: #17EA4C*
+
+- success frame on capturing
+
+**--border-color-divider**
+
+*default: #C0C0C0*
+
+- message box's default border color
+- 'select document type' menus's devider
+
+**--color-primary-light-2**
+
+*default: #DCE7FD*
+
+- primary button hover, focus colors
+
+**--color-primary-light-7**
+
+*default: #85AAF7*
+
+- transparent button hover and focus background color
+
+**--color-primary-light-9**
+
+*default: #6291F4*
+
+- transparent button border hover, focus colors
+- 'select document type' menus's selected item background
+
+**--color-primary-dark-2**
+
+*default: #080D18*
+
+- primary button active colors
+- transparent button active font color and border color
+
+**--color-background-subheader**
+
+*default: #F5F6F9*
+
+- background of the bottom part of the active step in 'steps' section
+- 'type not defined' select background of the modal window
+- scrollbar of 'result' modal window
+
+**--color-background-white**
+
+*default: #FFF*
+
+- uploader's background
+- background of 'result' modal window container
+- background of 'type not defined' modal window
+- background of 'document type-hint’ section
+
+**--border-color-base**
+
+*default: #DCDFE6*
+
+- border of 'type not defined' modal window select
+- border of 'document type-hint' section
+- borders of top part in 'steps' section
+- bottom icons of inactive step in 'steps' section
+- image background  in 'steps' section
+
+**--color-primary**
+
+*default: #5185F3*
+
+- background of primary buttons
+- active step name, icon, and bottom line of the active step in 'steps' section
+- uploader labels, border
+- manual take picture button in video capturing
+- change the document type in 'document type-hint' section
+- step name on hover in 'steps' section
+- guideline inscription
+- background of the upload icon in the uploader
+- uploader's emphasized descriptions
+- disabled primary buttons
+- disabled button border
+- spinner's color
+
+**--color-success**
+
+*default: #13CE66*
+
+- succeeded steps in 'steps' section
+- face shape when capturing the video in face step
+- capture progress
+- valid sign of 'result' modal window container
+- hints on video capture
+- background of uploader's success sign
+
+**--color-danger**
+
+*default: #FF4949*
+
+- background and bottom border of the step error in 'steps' section
+- header of 'type not defined' modal window
+- invalid sign of 'result' modal window container
+- license error text
+
+**--color-warning**
+
+*default: #FFC632*
+
+- warning sign of uploader
+
+**--color-text-secondary**
+
+*default: #909399*
+
+- scrollbar of 'result' modal window
+- library version
+- descriptions of the uploader
+- close sign of 'result' modal window
+- name of the inactive step in 'steps' section
+
+**--color-black**
+
+*default: #000*
+
+- face shape icon in video capturing when the face is not detected at the face step
+- shadow of 'type not defined' modal window
+- caption of 'type not defined' modal window select
+- uploader's bold descriptions
+- shadow of 'result' modal window
+- bottom border of 'result' modal window row
+- options of change the document type in 'document type-hint' section
+- uploader's error sign stroke
+- uploader's error description
+
+**--color-white**
+
+*default: #FFF*
+
+- caption of buttons
+- border and caption of manual take picture button
+- upload icon
+- header description of 'type not defined' modal window
+- uploader success sign's checkmark
+- description of capture progress
+
+## Version history
+- **2.0.0**
+  - deprecated: isShowManualSwitchButton. Now the decision is made on a step config
+  - deprecated: enableFlash. Now it shows only if device/browser supports flashlight.
+  - deprecated: showSubmitBtn. The submit button is always turned on.
+  - deprecated: isShowVersion. The Library version is always showing.
+  - deprecated: tapOnVideo.
+  - deprecated: tapBackSide.
+  - deprecated: tapFace.
+  - deprecated: showForceCapturingBtn.
+  - deprecated: minPDFframes.
+  - deprecated: capturingMode.
+  - deprecated: showPreviewForOneStep.
+  - deprecated: priority. Now the priority is selected by camera availability.
+  - deprecated: parseMRZ.
+  - deprecated: enableGeolocation.
+  - deprecated: enableLimitation. Now limitation shows only if the system not supports needed features.
+  - deprecated: steps.
+  - deprecated: types.
+  - deprecated: displayParsedData.
+  - changed behavior: autoContinue.
+  - feat: documentTypes. Now the "documentTypes" option is a union of steps and types.
+  - feat: add translation.
+
+- **1.12.17**
+  - added: onMounted hook
+
+- **1.12.16**
+  - added: possibility to change a document type during the document processing
+
+- **1.12.15**
+  - fixed: capture mask console output
+  - improved back step filtering behaviour
+
+- **1.12.14**
+  - fixed: capture mask resize
+
+- **1.12.13**
+  - fixed: angular app resize and rotate image
+
+- **1.12.12**
+  - fixed: desktop type select styles
+  - fixed: fixFrontOrientAfterUpload
+
+- **1.12.11**
+  - changed capture frame
+  - changed success progress
+  - performance improvement
+  - changed hint behaviour
+  - added message box
+
+- **1.12.10**
+  - Some infrastructure improvements
+
+- **1.12.9**
+  - Some infrastructure improvements
+
+- **1.12.8**
+  - Added: type declaration
+
+- **1.12.7**
+  - Fixed: not disappeared loader on reset all steps by manual upload
+
+- **1.12.6**
+  - Added new modules available via CDN
+
+- **1.12.5**
+  - improved iOs camera start
+
+- **1.12.3**
+  - Fixed: automatic call of the submit callback if the submit button is disabled
+
+- **1.12.2**
+  - Fixed: no video output on Safari 15
+  - Fixed: global isShowManualSwitchButton
+  - improved speed of library initialization
+  - changed images
+  - added: strictAllowedTypes config option
+
+- **1.12.1**
+  - Fixed: neural networks path
+
+- **1.12.0**
+  - Added: the ability to use CDN
+  - BREAKING CHANGE: neural networks names are changed. Check out you don't forget to rebuild your app
+  - Added: config validation
+  - ALl colors are moved to CSS custom properties
+  - All colors are standardized
+
+- **1.11.12**
+  - Deprecated: enableMobileLimitation
+  - Added: check if a browser supports work with media devices
+
+- **1.11.11**
+  - Fixed: iPhone memory leak 
+  - Fixed: browser support 
+
+- **1.11.10**
+  - Fixed: Windows surface support
+  
+- **1.11.9**
+  - Fixed: On iOS devices was a black screen on the second step
+  
+- **1.11.8**
+  - Changed: On iOS devices version 12 and below, simplified face capture is now used  
+  
+- **1.11.7**
+  - Changed: isShowManualSwitchButton can be setted in a step 
+  
+- **1.11.6**
+  - Changed: new version of PDF reader
+  
+- **1.11.5**
+  - Added: onRetakeHook callback function
+  
+- **1.11.4**
+  - Changed: the tapOnVideo option is set to false as default value
+
+- **1.11.3**
+  - Changed: isShowManualSwitchButton can accept an object instead of a boolean
+  
+- **1.11.1**
+  - Added: barcode step
+  - Added: option display parsed data      
+
+- **1.10.4**
+  - Added: metadata field
+  - Added: get user location
+  - Added: send base64 encoded metadata
+
+- **1.10.3**
+  - Fixed: reload component method
+
+- **1.10.2**
+  - Fixed: 3D faces crashed on iPhone
+    
+- **1.10.1**
+  - Fixed: Models for 3D faces were loaded from tf hub and Google Storage. Now all models are stored inside the package
+    Note: you’ll need to rebuild your app
+  
+- **1.10.0**
+    - Added: Option "parseMRZ" - if it is enabled, the captured MRZ lines are converted into the parsed document fields. Thus on-server parsing won’t be necessary. MRZ is captured automatically, after which the parsedData object is available
+    - Added: Message "MRZ not recognized" during the "MRZ" step (or "Front" when the document requires presense of MRZ lines) the validity of MRZ is valid.
+    
+    Note: you’ll need to request a new license key since the new version will not work with the old one.
+
+- **1.9.18**
+  - Added: New method showSpinner. Accepts the boolean value "true" or "false" as input.
+  
+- **1.9.17**
+  - Fixed: 3D face capture mode was enabled in document face capture mode
+  
+- **1.9.16**
+  - Fixed: "capturing" step doesn't work
+  
+- **1.9.15**
+  - Fixed: "resetAllSteps" method doesn't work
+  
+- **1.9.14**
+  - Set default value for minPdfFrames to 2
+  
+- **1.9.13**
+  - Fixed: fixFrontOrientAfterUpload doesn't work
+  
+- **1.9.11**
+  - Added: During the manual upload PDF417 will be scanned automatically.
+  - Changed: The default value of ‘autoContinue’ is set to ‘true’.
+  - Changed: The default value of ‘capturingMode’ is set to 4. NOTE! If you got an error related to the neural network downloading, then you’ll need to copy the ‘networks’ folder once again.
+  
+- **1.9.10**
+  - Added: Orientation change support
+  
+- **1.9.9**
+  - Added: The option enableFlash, which turns on the flash while capturing an image
+  - Fixed: High load on CPU while stopping the mode of auto capturing 
+  
+- **1.9.8**
+  - Added "source" field to each element of the steps array
+  - Updated "captureMethod" field to contain a string value where each character is either a "0", "1" or a "2" (e.g. "102" or "111"). "0" indicates a step was completed by uploading a file, a "1" indicates a step was completed by the builtin autocapture functionality and a "2" indicates a user tapped the video area to capture an image manually
+  
+- **1.9.7**
+  - Fixed: Angles model is not loaded 
+    
+- **1.9.6**
+  - Fixed:  tfjs-converter is broken in version 1.7.4 
+  
+- **1.9.5**
+  - Fixed:  "fixFrontOrientAfterUpload" did not work if one step was specified
+  
+- **1.9.4**
+  - Fixed: Selecting a wide camera on Samsung devices 
+  
+- **1.9.3**
+  - Added "captureMethod" field in the payload of the submit function
+  
+- **1.9.2**
+  - Fixed: face image not showing 
+  
+- **1.9.1**
+  - Unless the browser supports the WebAssembly technology, the widget will show that the browser is not supported 
+  
+- **1.9.0**
+  - The new option fixFrontOrientAfterUpload has been added. When you switch it on, the document will be rotated into correct position in case of manual uploading 
+  
+- **1.8.27**
+  - Fixed: The widget broke down when using the camera during switching the page in SPA 
+  
+- **1.8.26**
+  - Fixed: autocapturing does not work if method 4 is selected and one document type is selected
+      
+- **1.8.25**
+  - We have added the option "minPDFframes" which determines the minimal number of frames for capturing the PDF417. Default: 1
+   
+- **1.8.24**
+  - In each step we have added the field which means whether the auto capturing has been used or not 
+  
+- **1.8.23**
+  - Fix blank image if capturinMethod is 'none'
+  
+- **1.8.22**
+  - Reduced minimum frames to capturing of PDF417 barcode from 4 to 1
+  
+- **1.8.21**
+  - Fix tapOnVideo in the new capturing mode
+
+- **1.8.20**
+  - A new method of the autocapturing has been added. To enable it  use option "capturingMode"
+
+- **1.8.14**
+  - Fixed the style of the select of types
+
+- **1.8.13**
+  - Changed text for the Driver's license label
+
+- **1.8.12**
+  - Fix the rotation for Samsung browser
+
+- **1.8.11**
+  - Disabled rotation after resizing
+
+- **1.8.10**
+  - Fixed bundle for webpack 3
+
+- **1.8.9**
+  - Fixed trim MRZ
+
+- **1.8.8**
+  - Added callback "onCameraError" for exceptions from a camera
+
+- **1.8.7**
+  - Added option "tapFace"
+
+- **1.8.6**
+  - Added full support of HEIC format
+
+- **1.8.2**
+  - Added support "Tap on video" on PC
+
+- **1.8.0**
+  - Added option "autoContinue" (Default: false) - enables automatic transition to the next step
+
+- **1.7.21**
+  - Fixed "Tap on video". Now all video area available for tap
+
+- **1.7.20**
+  - Fix getCapabilities in Firefox
+
+- **1.7.19**
+  - Now the file extension is checked by magic numbers
+
+- **1.7.18**
+  - Changed text in the uploader
+  - Changed text in the switch button
+  - Changed timings (needed 25 frames, 100 ms between frames) in front capturing proccesing
+
+- **1.7.17**
+  - Changed upload icon
+
+- **1.7.16**
+  - Fixed: Widget stuck in spinner when cancel uploading image on Mac OS
+
+- **1.7.15**
+  - Resize loss rate set to 1
+
+- **1.7.14**
+  - Fixed image distortion in the preview of the steps
+
+- **1.7.13**
+  - Updated mrz reader
+
+- **1.7.11**
+  - Added heic support
+
+- **1.7.10**
+  - Fix text when passport detected
+
+- **1.7.9**
+  - Fix "showForceCapturingBtn" option
+
+- **1.7.8**
+  - Added step - capturing
+
+- **1.7.7**
+  - Added index to step
+
+- **1.7.6**
+  - Fix real face for inverted camera
+
+- **1.7.5**
+  - Added showing of error for unsupported types of images
+
+- **1.7.4**
+  - Fix "reset all steps" when your document is passport
+
+- **1.7.3**
+  - Fix error in pipeline of passport capturing
+
+- **1.7.2**
+  - Added option tapBackSide (Default: false) - tap and hold the screen to capture the back side of the ID
+
+- **1.6.16**
+  - Fixed for back step (hidden if it is not necessary)
+
+- **1.6.15**
+  - Fonts are now included in the js file
+
+- **1.6.14**
+  - Reduced the number of frames needed to capture PDF417 from 10 to 4
+
+- **1.6.10**
+  - Changed text for barcode tips
+
+- **1.6.10**
+  - Changed text for barcode tips
+
+- **1.6.8**
+  - Added option: isShowVersion(boolean) - hide/show version of library in the bottom
+
+- **1.6.6**
+  - Added pdf progress
+
+- **1.6.0**
+  - Added option: **resizeUploadedImage** (integer) - sets the maximum size for manually loaded pictures