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. |
preview |
Boolean
|
<optional>
|
false
|
Boolean value representing whether to review the captured image using the SDK review control. |
frameAspectRatio |
Number
|
<optional>
|
0.629
|
Aspect ratio of the frame.
| Document Type | Recommended Value |
|---|
| Mobile ID | 0.629 |
| Check | 0.460 |
| Credit Card | 0.623 |
| Passport | 0.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. |
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. |
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:
-
- KfxWebSDK.Utilities.supportsAdvancedCapture
Example
var options = {
containerId: 'divId',
preference: 'camera',
useVideoStream: true,
preview: false
frameAspectRatio: 0.629,
framePadding: 5,
frameCornerHeight: 10,
frameCornerWidth: 60,
frameCornerColor: '#00FF00',
outOfFrameTransparency: 0.5,
showEdges: false,
edgesColor: '#FFFF00',
edgesWidth: 4,
guidanceSize: 150,
useTargetFrameCrop: 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',
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 with ImageData of captured image |
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 |
frameAspectRatio |
Number
|
<optional>
|
0.629
|
Aspect ratio of the frame.
| Document Type | Recommended Value |
|---|
| Mobile ID | 0.629 |
| Check | 0.460 |
| Credit Card | 0.623 |
| Passport | 0.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. |
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. |
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 |
Example
var options = {
frameAspectRatio: 0.629,
framePadding: 5,
frameCornerHeight: 10,
frameCornerWidth: 60,
frameCornerColor: '#00FF00',
outOfFrameTransparency: 0.5,
showEdges: false,
edgesColor: '#FFFF00',
edgesWidth: 4,
guidanceSize: 150,
useTargetFrameCrop: 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',
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 with ImageData of captured 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.
(static) takePictureContinually(successCallBack, errorCallBack)
Starts Continuous Auto capture process.
Parameters:
| Name |
Type |
Description |
successCallBack |
function
|
callback with ImageData of captured image |
errorCallBack |
function
|
callback with error message to be invoked when something goes wrong |