Namespace: Capture

KfxWebSDK.Capture

Methods

(static) choosePictureAsBase64(successCallBack, errorCallBack)

Allows picture to be choosen from device photo library/gallery OR from device camera. This method returns selected Image as base64, hence best suited for the usecases where application picks images from gallery and send it for extraction.
Parameters:
Name Type Description
successCallBack function callback with Base64 data of captured or picked image
errorCallBack function callback with error message to be invoked when something goes wrong
See:
  • It is recommended to call/bind this method in some button click events instead of jquery page events or window load events to get full support from most of the browsers. This method works in manual mode i.e useVideoStream is 'false'.

(static) create(options, successCallBack, errorCallBack)

Creates capture control based on given options.
Parameters:
Name Type Description
options Object The options.
Properties
Name Type Attributes Default Description
containerId String ID of an empty element where the camera preview and capture guidance will be displayed. The element must exist, have no child elements, and be a div. Application developer has to properly set size & position of the container. ContainerId will not be required, if browser doesn't support MediaStreamAPI.
preference String String representing the source of the captured document. Acceptable values are 'camera' for capturing with the device's rear camera, or 'gallery' to select an image from the device's photo gallery. On Android devices, a value of 'camera' will require the user to take a photo. On Android and iOS devices, even if a value of 'gallery' is used the user may elect to take a photo instead.
useVideoStream Boolean Boolean value representing either capture with gallery/camera option or auto-capture with guidance messages. Check KfxWebSDK.Utilities.supportsAutoCapture API before enabling this option. If the API returns true then only we can enable this option otherwise we will get an error.
preview Boolean <optional>
 false Boolean value representing whether to review the captured image using the SDK review control.
resolution KfxWebSDK.resolution <optional>
 RES_FULL_HD This parameter is used to specify the resolution which user want to use in the Advance Capture. Advance capture supports Full HD and 4K resolutions based on the device capabilities. User need to pass RES_FULL_HD for Full HD and RES_4K for 4K resolutions. If user do not specify this parameter then it will use the Full HD resolution. If user pass other than RES_FULL_HD and RES_4K values then error will be thrown. If the device browser supports 4k resolution and user pass RES_4K then 4K resolution will be used in Advance capture. If the device browser does not support 4K resolution and user pass RES_4K then Full HD resolution will be used in Advance capture. If the device browser does not support both resolutions then error will be thrown.
downscaleSize Number <optional>
 2 This option will be considered in Mega Pixels. If the captured image size is more than this value then we will downscale the image to the specified size. The valid range is [1-50].
frameAspectRatio Number <optional>
 0.629 Aspect ratio of the frame.
Document TypeRecommended Value
Mobile ID0.629
Check0.460
Credit Card0.623
Passport0.703
framePadding Number <optional>
 5 Frame padding. The padding has priority over frame corners, i.e. if padding zero value is set, then there is no space for frame corners left and they will not be shown.
frameCornerHeight Number <optional>
 10 Frame corner height.
frameCornerWidth Number <optional>
 60 Frame corner width.
frameCornerColor String <optional>
 '#00FF00' Frame corner color.
outOfFrameTransparency Number <optional>
 0.5 Out of frame space transparency, 0 - transparent and visible, 1 - dark.
showEdges Boolean <optional>
 true Draws a border around the document during capture.
edgesColor String <optional>
 '#FFFF00' Bounding rectangle sides color.
edgesWidth Number <optional>
 4 Bounding rectangle sides width.
guidanceSize Number <optional>
 150 Size of guidance circle image.
useTargetFrameCrop Boolean <optional>
 false Enable target frame cropping.
enableFlashCapture Boolean <optional>
 false Used to enable the Flash Capture. When this option is enabled, user will get an additional image captured with Flash enabled. If the device browser doesn't support flash feature then user will not be returned any Flash Image. This option only works with the Android platform.
criteria Object The criteria options.
Properties
Name Type Attributes Default Description
captureTimeout Number <optional>
 1700 The amount of time the user must hold the device steady once the 'Hold Steady' guidance appears, after which point an image is captured. If any other guidance prompt appears during this time, no image is captured until the 'Hold Steady' guidance appears again and the device remains held steady. The duration value is in milliseconds.
centerToleranceFraction Number <optional>
 0.19 The maximum distance the document can be shifted from the target frame. The movement tolerance puts an upper bound on how far a document can be shifted from the target frame and still be considered acceptable. The tolerance is specified as a fraction of the target size, and the comparison is made between the center of the target frame and the center of the detected document bounds.
maxFillFraction Number <optional>
 1.8 The maximum fill area as a fraction of the target frame. The maximum fill fraction puts an upper bound on what is considered an acceptable zoom level. If the area of a detected document is greater then the area of the target frame multiplied by the maximum fill fraction, guidance will suggest zooming out from the document.
minFillFraction Number <optional>
 0.65 The minimum fill area as a fraction of the target frame. The minimum fill fraction puts a lower bound on what is considered an acceptable zoom level. If the area of a detected document is less then the area of the target frame multiplied by the minimum fill fraction, guidance will suggest zooming in on the document.
longAxisThreshold Number <optional>
 85 This property is a percent value. The valid range is [0 - 100]. When page detection is enabled, this property specifies the minimum size of the page that spans the long side of the frame. If the page is smaller than the threshold, it will not be captured. The value 0 will disable page long axis threshold check. The default value is 85. Because page detection requires some margin around a page to properly detect it, the useful upper limit of this property is around 90%.
shortAxisThreshold Number <optional>
 60 This property is a percent value. The valid range is [0 - 100]. When page detection is enabled, this property specifies the minimum size of the page that spans the short side of the frame. If the page is smaller than the threshold, it will not be captured. The value 0 will disable page short axis threshold check. The default value is 60. Because page detection requires some margin around a page to properly detect it, the useful upper limit of this property is around 90%. However to detect a document with a magnetic stripe (back side of driver licenses) the useful limit should not be higher 60%.
turnSkewAngleTolerance Number <optional>
 10 The maximum angle the document can be rotated off from the target frame. The skew angle tolerance puts an upper bound on how far a document can be rotated clockwise or counter-clockwise relative to the target frame and still be considered acceptable. Angles of rotation greater than the tolerance will result in guidance to turn the document. The default value is 10, specified in degrees. Valid values are in the range [0, 90]. A value of 90 disables rotation guidance.
pitchThreshold Number <optional>
 15 The pitch threshold value which needs to be met before taking a picture. Valid values are in the range [0, 45]. The default value is 15. A value of 45 disables level checking for pitch.
rollThreshold Number <optional>
 15 The roll threshold value which needs to be met before taking a picture. Valid values are in the range [0, 45]. The default value is 15. A value of 45 disables level checking for roll.
lookAndFeel Object The look and feel options.
Properties
Name Type Attributes Default Description
documentSample Boolean | String <optional>
 The url to the default document sample image The URL to an image of the document sample. If the given documentSample is false or an empty string, then the sample will not be shown.
showTapToDismissMessage Boolean <optional>
 true Used to show or hide the Tap To Dismiss Message. When this option is enabled, Tap To Dismiss message will be shown. When this option is disabled, Tap To Dismiss message will not be shown.
forceCapture Boolean | Number <optional>
 10 Boolean value specifies whether to show the force capture button. Number value in seconds specifies when to show the force capture button. If any number is set, then the button will be shown. If number value is negative or zero the button will be shown immediately. Setting boolean true is equivalent to setting number 0 value.
gallery Boolean <optional>
 true This value specifies whether to show the gallery button.
successCallBack function empty callback indicating API call is successful
errorCallBack function callback with error message to be invoked when something goes wrong
See:
Example
var options = {
    containerId: 'divId',
    preference: 'camera',
    useVideoStream: true,
    preview: false,
    frameAspectRatio: 0.629,
    framePadding: 5,
	   resolution: KfxWebSDK.resolution.RES_FULL_HD,
	   downscaleSize: 2,
    frameCornerHeight: 10,
    frameCornerWidth: 60,
    frameCornerColor: '#00FF00',
    outOfFrameTransparency: 0.5,
    showEdges: false,
    edgesColor: '#FFFF00',
    edgesWidth: 4,
    guidanceSize: 150,
    useTargetFrameCrop: false,
    enableFlashCapture: false,
    criteria: {
        minFillFraction: 0.65,
        maxFillFraction: 1.8,
        longAxisThreshold: 85,
        shortAxisThreshold: 60,
        centerToleranceFraction: 0.19,
        captureTimeout: 1700,
        turnSkewAngleTolerance: 10,
        pitchThreshold: 15,
        rollThreshold: 15
    },
    lookAndFeel: {
        documentSample: 'http://example.com/images/document_sample.jpg',
		   showTapToDismissMessage: true,
        forceCapture: 10,
        gallery: true
    }
};

(static) destroy(successCallBack, errorCallBack)

Releases internal allocated resources. The destroy method must be called prior to calling create multiple times.
Parameters:
Name Type Description
successCallBack function callback with no data
errorCallBack function callback with error message to be invoked when something goes wrong

(static) forceTakePicture(successCallBack, errorCallBack)

Captures document by ignoring capture criteria.
Parameters:
Name Type Description
successCallBack function callback contains captured image data as the first argument and flash image data as the second argument. If user enables enableFlashCapture option, flash image data will be returned. Otherwise only captured image data is returned.
errorCallBack function callback with error message to be invoked when something goes wrong

(static) getDefaultOptions(successCallBack, errorCallBack)

Returns default capture control options.
Parameters:
Name Type Description
successCallBack function callback with JSON object representing capture control options
errorCallBack function callback with error message to be invoked when something goes wrong

(static) getOptions(successCallBack, errorCallBack)

Returns current capture control options.
Parameters:
Name Type Description
successCallBack function callback with JSON object representing capture control options
errorCallBack function callback with error message to be invoked when something goes wrong

(static) setOptions(options, successCallBack, errorCallBack)

Sets capture control options.
Parameters:
Name Type Description
options Object The options.
Properties
Name Type Attributes Default Description
resolution KfxWebSDK.resolution <optional>
 RES_FULL_HD This parameter is used to specify the resolution which user want to use in the Advance Capture. Advance capture supports Full HD and 4K resolutions based on the device capabilities. User need to pass RES_FULL_HD for Full HD and RES_4K for 4K resolutions. If user do not specify this parameter then it will use the Full HD resolution. If user pass other than RES_FULL_HD and RES_4K values then error will be thrown. If the device browser supports 4k resolution and user pass RES_4K then 4K resolution will be used in Advance capture. If the device browser does not support 4K resolution and user pass RES_4K then Full HD resolution will be used in Advance capture. If the device browser does not support both resolutions then error will be thrown.
downscaleSize Number <optional>
 2 This option will be considered in Mega Pixels. If the captured image size is more than this value then we will downscale the image to the specified size. The valid range is [1-50].
frameAspectRatio Number <optional>
 0.629 Aspect ratio of the frame.
Document TypeRecommended Value
Mobile ID0.629
Check0.460
Credit Card0.623
Passport0.703
framePadding Number <optional>
 5 Frame padding. The padding has priority over frame corners, i.e. if padding zero value is set, then there is no space for frame corners left and they will not be shown.
frameCornerHeight Number <optional>
 10 Frame corner height.
frameCornerWidth Number <optional>
 60 Frame corner width.
frameCornerColor String <optional>
 '#00FF00' Frame corner color.
outOfFrameTransparency Number <optional>
 0.5 Out of frame space transparency, 0 - transparent and visible, 1 - dark.
showEdges Boolean <optional>
 true Draws a border around the document during capture.
edgesColor String <optional>
 '#FFFF00' Bounding rectangle sides color.
edgesWidth Number <optional>
 4 Bounding rectangle sides width.
guidanceSize Number <optional>
 150 Size of guidance circle image.
useTargetFrameCrop Boolean <optional>
 false Enable target frame cropping.
enableFlashCapture Boolean <optional>
 false Used to enable the Flash Capture. When this option is enabled, user will get an additional image captured with Flash enabled. If the device browser doesn't support flash feature then user will not be returned any Flash Image. This option only works with the Android platform.
criteria Object The criteria options.
Properties
Name Type Attributes Default Description
captureTimeout Number <optional>
 1700 The amount of time the user must hold the device steady once the 'Hold Steady' guidance appears, after which point an image is captured. If any other guidance prompt appears during this time, no image is captured until the 'Hold Steady' guidance appears again and the device remains held steady. The duration value is in milliseconds.
centerToleranceFraction Number <optional>
 0.19 The maximum distance the document can be shifted from the target frame. The movement tolerance puts an upper bound on how far a document can be shifted from the target frame and still be considered acceptable. The tolerance is specified as a fraction of the target size, and the comparison is made between the center of the target frame and the center of the detected document bounds.
maxFillFraction Number <optional>
 1.8 The maximum fill area as a fraction of the target frame. The maximum fill fraction puts an upper bound on what is considered an acceptable zoom level. If the area of a detected document is greater then the area of the target frame multiplied by the maximum fill fraction, guidance will suggest zooming out from the document.
minFillFraction Number <optional>
 0.65 The minimum fill area as a fraction of the target frame. The minimum fill fraction puts a lower bound on what is considered an acceptable zoom level. If the area of a detected document is less then the area of the target frame multiplied by the minimum fill fraction, guidance will suggest zooming in on the document.
longAxisThreshold Number <optional>
 85 This property is a percent value. The valid range is [0 - 100]. When page detection is enabled, this property specifies the minimum size of the page that spans the long side of the frame. If the page is smaller than the threshold, it will not be captured. The value 0 will disable page long axis threshold check. The default value is 85. Because page detection requires some margin around a page to properly detect it, the useful upper limit of this property is around 90%.
shortAxisThreshold Number <optional>
 60 This property is a percent value. The valid range is [0 - 100]. When page detection is enabled, this property specifies the minimum size of the page that spans the short side of the frame. If the page is smaller than the threshold, it will not be captured. The value 0 will disable page short axis threshold check. The default value is 60. Because page detection requires some margin around a page to properly detect it, the useful upper limit of this property is around 90%. However to detect a document with a magnetic stripe (back side of driver licenses) the useful limit should not be higher 60%.
turnSkewAngleTolerance Number <optional>
 10 The maximum angle the document can be rotated off from the target frame. The skew angle tolerance puts an upper bound on how far a document can be rotated clockwise or counter-clockwise relative to the target frame and still be considered acceptable. Angles of rotation greater than the tolerance will result in guidance to turn the document. The default value is 10, specified in degrees. Valid values are in the range [0, 90]. A value of 90 disables rotation guidance.
pitchThreshold Number <optional>
 15 The pitch threshold value which needs to be met before taking a picture. Valid values are in the range [0, 45]. The default value is 15. A value of 45 disables level checking for pitch.
rollThreshold Number <optional>
 15 The roll threshold value which needs to be met before taking a picture. Valid values are in the range [0, 45]. The default value is 15. A value of 45 disables level checking for roll.
lookAndFeel Object The look and feel options.
Properties
Name Type Attributes Default Description
documentSample Boolean | String <optional>
 The url to the default document sample image The URL to an image of the document sample. If the given documentSample is false or an empty string, then the sample will not be shown.
showTapToDismissMessage Boolean <optional>
 true Used to show or hide the Tap To Dismiss Message. When this option is enabled, Tap To Dismiss message will be shown. When this option is disabled, Tap To Dismiss message will not be shown.
forceCapture Boolean | Number <optional>
 10 Boolean value specifies whether to show the force capture button. Number value in seconds specifies when to show the force capture button. If any number is set, then the button will be shown. If number value is negative or zero the button will be shown immediately. Setting boolean true is equivalent to setting number 0 value.
gallery Boolean <optional>
 true This value specifies whether to show the gallery button.
successCallBack function empty callback indicating API call is successful
errorCallBack function callback with error message to be invoked when something goes wrong
See:
Example
var options = {
    frameAspectRatio: 0.629,
    framePadding: 5,
    frameCornerHeight: 10,
	   resolution: KfxWebSDK.resolution.RES_FULL_HD,
	   downscaleSize: 2,
    frameCornerWidth: 60,
    frameCornerColor: '#00FF00',
    outOfFrameTransparency: 0.5,
    showEdges: false,
    edgesColor: '#FFFF00',
    edgesWidth: 4,
    guidanceSize: 150,
    useTargetFrameCrop: false,
    enableFlashCapture: false,
    criteria: {
        minFillFraction: 0.65,
        maxFillFraction: 1.8,
        longAxisThreshold: 85,
        shortAxisThreshold: 60,
        centerToleranceFraction: 0.19,
        captureTimeout: 1700,
        turnSkewAngleTolerance: 10,
        pitchThreshold: 15,
        rollThreshold: 15
    },
    lookAndFeel: {
        documentSample: 'http://example.com/images/document_sample.jpg',
		   showTapToDismissMessage: true,
        forceCapture: 10,
        gallery: true
    }
};

(static) stopCapture(successCallBack, errorCallBack)

Stops Auto capture.
Parameters:
Name Type Description
successCallBack function callback with no data
errorCallBack function callback with error message to be invoked when something goes wrong

(static) takePicture(successCallBack, errorCallBack)

Starts Auto capture process.
Parameters:
Name Type Description
successCallBack function callback contains captured image data as the first argument and flash image data as the second argument. If user enables enableFlashCapture option, flash image data will be returned. Otherwise only captured image data is returned.
errorCallBack function callback with error message to be invoked when something goes wrong
See:
  • It is recommended to call/bind this method in some button click events instead of jquery page events or window load events to get full support from most of the browsers.

(static) takePictureContinually(successCallBack, errorCallBack)

Starts Continuous Auto capture process.
Parameters:
Name Type Description
successCallBack function callback contains captured image data as the first argument and flash image data as the second argument. If user enables enableFlashCapture option, flash image data will be returned. Otherwise only captured image data is returned.
errorCallBack function callback with error message to be invoked when something goes wrong