Class: OnDeviceExtraction

OnDeviceExtraction()

new OnDeviceExtraction()

An instance of this class contains methods to extract the images and gets the results. SDK shall integrate on-device classification and extraction models for IDs.currently it supports only IDs. On-device extraction will not be supported for all regions, it may vary based on ID Type(DL/Passport).

Methods

addBackProcessedImageListener(successCallback, errorCallback, processedImageCallback)

If image processing is disabled, the callback will contain the original image. Importantly user should take the ownership of the imageObject. If no back image was provided, no callback will be raised. If image processing failed or extraction was canceled before processing finished, no callback will be raised, and the appropriate errors will be returned from the kfxKOEIDExtractorDelegate. Note: In certain cases, if the provided unprocessed image is known to contain only a barcode and no other useful information, processing may be skipped, and the original image will be returned.
Parameters:
Name Type Description
successCallback function Default Success Call back function name
errorCallback function Default Error Call back function name
processedImageCallback function A JSON object containing the properties of the captured image object. Check the 'Image' object for its properties.
Returns:
The return value is captured in the 'successCallback' for a successful operation, and might return in 'errorCallback' for an incomplete/invalid operation. Returns the following values in the corresponding functions successCallback - KMC_SUCCESS success call back. errorCallback - error message would contain the appropriate error description.Possible error objects are Wrong Parameters, KmcRuntimeException & Exception. processedImageCallback - will have the JSON object of the captured KfxKEDImage properties. The captured Image is stored in ImageArray. The image can be retrieved using methods on ImageArray.
Example
function processedImageCallback(imageObject)
{
     alert(JSON.stringify(imageObject));
}
function successCallback(response){
      alert(JSON.stringify(response));
}
function errorCallback(error){
      alert(JSON.stringify(error));
}
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();
OnDeviceExtraction.addBackProcessedImageListener(successCallback, errorCallback, processedImageCallback);

addFrontProcessedImageListener(successCallback, errorCallback, processedImageCallback)

If image processing is disabled, the callback will contain the original image. Importantly user should take the ownership of the imageObject. If no front image was provided, no callback will be raised. If image processing failed or extraction was canceled before processing finished, no callback will be raised, and the appropriate errors will be returned from the kfxKOEIDExtractorDelegate.
Parameters:
Name Type Description
successCallback function Default Success Call back function name
errorCallback function Default Error Call back function name
processedImageCallback function A JSON object containing the properties of the captured image object. Check the 'Image' object for its properties.
Returns:
The return value is captured in the 'successCallback' for a successful operation, and might return in 'errorCallback' for an incomplete/invalid operation. Returns the following values in the corresponding functions successCallback - KMC_SUCCESS success call back. errorCallback - error message would contain the appropriate error description.Possible error objects are Wrong Parameters, KmcRuntimeException & Exception. processedImageCallback - will have the JSON object of the captured KfxKEDImage properties. The captured Image is stored in ImageArray. The image can be retrieved using methods on ImageArray.
Example
function processedImageCallback(imageObject)
{
     alert(JSON.stringify(imageObject));
}
function successCallback(response){
      alert(JSON.stringify(response));
}
function errorCallback(error){
      alert(JSON.stringify(error));
}
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();
OnDeviceExtraction.addFrontProcessedImageListener(successCallback, errorCallback, processedImageCallback);

addOnDeviceExtractionListener(successCallback, errorCallback, extractionResultsCallback)

This method would receive the on extracted results at the ondeviceExtraction. Importantly ownership of faceImage and signatureImage should be taken care by user
Parameters:
Name Type Description
successCallback function Default Success Call back function name
errorCallback function Default Error Call back function name
extractionResultsCallback function Extraction results are returned in this variable in the form a JSON object.
Returns:
successCallback - KMC_SUCCESS success call back. errorCallback - Error object would contain either JSON Object or error message string.if it has json object it contains front or back or both error messages.Check below example code for how to handle error object. extractionResultsCallback - Extraction results are returned in this variable in the form a JSON object.This json object contains data as mentioned below. -> If both images are sent and error occurred during the extraction of only one of them, the JSON object will contain array of extracted dataFields and error code for the failed side. -> If one or both Images are sent and get extraction success then json object contains only array of extracted dataFields. -> It would also contain Face Image and Signature Image based on the returned results
Example
dataField object is mentioned as below.
 ex:  var dataField ={
       fieldName:"name",
       fieldValue:"value",
       fieldConfidence:0.0,
       fieldLocation : {
                 x     : 0.0,
                 y     : 0.0,
                 width : 0.0,
                 height: 0.0
               }
     };



var extractionResultsCallback = function(result){
  var dataFields = result.extractionResults;
  var faceImageObject = result.faceImage;
  var signatureImageObject = result.signatureImage;
           if(result.hasOwnProperty('extractionFrontError')){
             alert("Front error:: " + result.extractionFrontError);
             }
             if(result.hasOwnProperty('extractionBackError')){
                     alert("Back error:: " + result.extractionBackError);
                 }

  console.log("Extraction Result: ");
  for(var i = 0; i < dataFields.length; i++){
     var name = dataFields[i].fieldName;
     var value = dataFields[i].fieldValue;
     var confidence = dataFields[i].fieldConfidence;
     var fieldLocation_x =  dataFields[i].fieldLocation.x;
     var fieldLocation_y =  dataFields[i].fieldLocation.y;
     var fieldLocation_width =  dataFields[i].fieldLocation.width;
     var fieldLocation_height =  dataFields[i].fieldLocation.height;
     console.log("Field Name:"+ name +" Field Value: "+value+" confidence:"+confidence+" fieldLocation_x:"+fieldLocation_x+" fieldLocation_y:"+fieldLocation_y+" fieldLocation_width:"+fieldLocation_width+" fieldLocation_height:"+fieldLocation_height);
  }

  var error = result.extractionError;
}

var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();

OnDeviceExtraction.addOnDeviceExtractionListener(function(success){
   alert(JSON.stringify(success));
},function(error){
   if(!error.hasOwnProperty('extractionFrontError') && !error.hasOwnProperty('extractionBackError')){
                   alert("error in addOnDeviceExtractionListener :" + JSON.stringify(error));
   }else{
           if(error.hasOwnProperty('extractionFrontError')){
             alert("Front error:: " + error.extractionFrontError);
             }
             if(error.hasOwnProperty('extractionBackError')){
                     alert("Back error:: " + error.extractionBackError);
                 }
   }
}, extractionResultsCallback);

cancelExtraction(successCallback, errorCallback)

Use the CancelExtraction method to cancel an extraction processing operation that is underway.
Parameters:
Name Type Description
successCallback function Default Success call back function name
errorCallback function Default Error call back function name
Returns:
successCallback - KMC_SUCCESS success call back errorCallback - error message would contain the appropriate error description.Possible error objects are KmcRuntimeException,Exception.
Example
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();

OnDeviceExtraction.cancelExtraction(function(success){
 alert(JSON.stringify(success));
}, function(error){
 alert(JSON.stringify(error));
});

extractFields(successCallback, errorCallback, parameters)

Use this method when you want to perform on-device classification and extraction models for IDs. SDK will allow On-Device Extraction process only if the SDK system license enabled.if device license count is zero then OndeviceExtraction callback will be called immediately with null results and errors for both sides. The region parameter is required; it is considered an error to pass null. Neither the front nor the back image are required and may be null. If both front- and back-side images are provided, the extraction for each image will be performed concurrently. The results for both images will be merged into a single result, the order of the elements is undefined. if the extraction completes without error then extractionResultsCallback(passed in addOnDeviceExtractionListener api) Callback will get the extraction results otherwise will get an errors.
Parameters:
Name Type Description
successCallback function Default Success call back function name
errorCallback function Default Error call back function name
parameters Object parameters which are used to extract the fields
Properties
Name Type Attributes Description
region String <optional>
 The region types will be determined by the classification/extraction models.
IDType String <optional>
 It will be determined the type of ID. Allowable values are Id,Passport.
frontImageId String <optional>
 front image object that you want to extract. An image id in the ImageArray is to be passes as argument.
frontBarcodeArray Array.<Object> <optional>
 Array of front-side barcode data which is coming from barcode capture experience that you want to extract. The barcode strings extracted from the Barcode detector is to be passes as argument.
backImageId String <optional>
 back image object that you want to extract. An image id in the ImageArray is to be passes as argument.
backBarcodeArray Array.<Object> <optional>
 Array of back-side barcode data which is coming from barcode capture experience that you want to extract. The barcode strings extracted from the Barcode detector is to be passes as argument.
isProcessed String <optional>
 Whether the images passed are pre-processed or not. If true, the SDK will not pre-process both images before extraction. Otherwise, any processing required will be handled internally by the SDK.
See:
  • Use - OnDeviceExtraction#cancelExctaction to cancel an extraction operation if necessary.
Returns:
The return value is captured in the 'successCallback' function. This method returns KMC_SUCCESS when the extraction was started up successfully. Several error codes are returned for this method when the extraction request could not be started. Extraction error is constructed using the following rules: - If only one image (either front or back) is sent for extraction and an error occurred at some step, the extractionResultsCallback will be called with null results and error code for the corresponding side and KMC_SUCCESS code for the other side. - If both images are sent and error occurred during the extraction of only one of them, the results of the successful extraction will get extractionResultsCallback. Error code for the failed side and KMC_SUCCESS code for the other side. - If both images are provided and both extraction fail, extraction results will be nil and will contain corresponding error codes. - If none image is provided, extractionResultsCallback will be called immediately with nil results and errors for both sides. The possible error codes are: KMC_UT_LICENSE_ID_EXTRACTION: Required ID extraction license not found.Please make sure the application is using the correct license string. KMC_UT_OUT_OF_VOLUME_LICENSE: Required license volume not available.Please make sure your license server is configured properly. KMC_EX_NOIMAGE: No bitmap image was specified for extraction.
Example
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();
  var region = OnDeviceExtraction.getRegions();
  var idType = OnDeviceExtraction.getIDTypes();
  var parameters = {
           region: region.US,    //region.ASIA,region.CANADA,etc.
           IDType: idType.ID,
           frontImageId: frontID,
           frontBarcode: [],
           backImageId: backID,
           backBarcode: [],
           isProcessed: false
  };

OnDeviceExtraction.extractFields(function(success){
   alert(JSON.stringify(success));
},function(error){
   alert(JSON.stringify(error));
}, parameters);

getIDTypes()

Get the OnDeviceExtraction supported ID types.
Example
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();
  var idTypes = OnDeviceExtraction.getIDTypes();
  alert(JSON.stringify(idTypes));

getProjectName(successCallback, errorCallback, parameters)

Get the Project name based on region and IDType.
Parameters:
Name Type Description
successCallback function Default Success call back function name
errorCallback function Default Error call back function name
parameters Object parameters which are used to get project name.
Properties
Name Type Attributes Description
region String <optional>
 Name of the region.
IDType String <optional>
 It will be determined the type of ID. Allowable values are Id,Passport.
Returns:
The return value is captured in the 'successCallback' for a successful operation, and might return in 'errorCallback' for an incomplete/invalid operation. Returns the following values in the corresponding functions successCallback - The successCallBack consists of Project Name. errorCallback - Error message would contain the appropriate error description.Possible error objects are Wrong Parameters & Exception.
Example
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();
  var region = OnDeviceExtraction.getRegions();
  var idType = OnDeviceExtraction.getIDTypes();
  var parameters = {
           region: region.US,    //region.ASIA,region.CANADA,etc.
           IDType: idType.ID
  };
  OnDeviceExtraction.getProjectName(function(projectName){
                                             alert("Name of the project:: "+projectName);
                                    },function(error){
                                      alert(JSON.stringify(error));
                                    }, parameters);

getProviders()

Get the OnDeviceExtraction supported cache providers
Example
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();
  var providers = OnDeviceExtraction.getProviders();//Supported cache providers are provider.LOCAL,provider.SERVER
  alert(JSON.stringify(providers));

getRegions()

Get the OnDeviceExtraction supported regions
Example
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();
  var regions = OnDeviceExtraction.getRegions();
 alert(JSON.stringify(regions));

removeBackProcessedImageListener(successCallback, errorCallback)

The method would remove the listener to the delegate call back of the backProcessedImage method. After removing the listener, there will not be any call backs from native from the Image Processing delegate methods even when it is being called in native.
Parameters:
Name Type Description
successCallback function Default Success Call back function name
errorCallback function Default Error Call back function name
Returns:
The return value is captured in the 'successCallback' for a successful operation, and might return in 'errorCallback' for an incomplete/invalid operation. Returns the following values in the corresponding functions successCallback - KMC_SUCCESS success call back errorCallback - error message would contain the appropriate error description.Possible error objects are KmcRuntimeException,Exception.
Example
function successCallback(response){
      alert(JSON.stringify(response));
}
function errorCallback(error){
      alert(JSON.stringify(error));
}
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();
OnDeviceExtraction.removeBackProcessedImageListener(successCallback, errorCallback);

removeFrontProcessedImageListener(successCallback, errorCallback)

The method would remove the listener to the delegate call back of the frontProcessedImage method. After removing the listener, there will not be any call backs from native from the Image Processing delegate methods even when it is being called in native.
Parameters:
Name Type Description
successCallback function Default Success Call back function name
errorCallback function Default Error Call back function name
Returns:
The return value is captured in the 'successCallback' for a successful operation, and might return in 'errorCallback' for an incomplete/invalid operation. Returns the following values in the corresponding functions successCallback - KMC_SUCCESS success call back errorCallback - error message would contain the appropriate error description.Possible error objects are KmcRuntimeException,Exception.
Example
function successCallback(response){
      alert(JSON.stringify(response));
}
function errorCallback(error){
      alert(JSON.stringify(error));
}
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();
OnDeviceExtraction.removeFrontProcessedImageListener(successCallback, errorCallback);

removeOnDeviceExtractionListener(successCallback, errorCallback)

The method would remove the listener and would not receive the extracted results events. After removing the listener, there will not be any call backs from native.
Parameters:
Name Type Description
successCallback function Default Success Call back function name
errorCallback function Default Error Call back function name
Returns:
successCallback - KMC_SUCCESS success call back errorCallback - error message would contain the appropriate error description.Possible error objects are KmcRuntimeException,Exception.
Example
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();

OnDeviceExtraction.removeOnDeviceExtractionListener(function(success){
 alert(JSON.stringify(success));
}, function(error){
 alert(JSON.stringify(error));
});

setProvider(successCallback, errorCallback, setProviderOptions)

This method sets provider to extractor.The provider may be Local cache provider or server cache provider.Setting provider is mandatory before performing extraction.
Parameters:
Name Type Description
successCallback function Default Success call back function name
errorCallback function Default Error call back function name
setProviderOptions Object A JSON object contains the options to be set to OnDeviceExtraction object.The options consists of which provider to be set to OnDeviceExtraction to perform extraction.
Properties
Name Type Attributes Description
provider Number <optional>
 Provider which is used for on device extraction.OnDeviceExtraction supports two providers.Local provider and server provider.Allowable values are Provider.LOCAL,Provider.SERVER.
Returns:
The return value is captured in the 'successCallback' for a successful operation, and might return in 'errorCallback' for an incomplete/invalid operation. Returns the following values in the corresponding functions successCallback - KMC_SUCCESS success call back.The successCallBack consists of path to specified project files errorCallback - error message would contain the appropriate error description.Possible error objects are Wrong Parameters, KmcRuntimeException & Exception.
Example
var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();
       var provider = OnDeviceExtraction.getProviders();
       var selectedProvider=provider.LOCAL;//Allowable values are provider.LOCAL, provider.SERVER

 var setProviderOptions={
    provider:selectedProvider
};

 var OnDeviceExtraction = kfxCordova.kfxEngine.createOnDeviceExtraction();
 OnDeviceExtraction.setProvider(function(success){
   alert(JSON.stringify(success));
},function(error){
     alert(JSON.stringify(error));
},setProviderOptions);