Introduction

The goal of this framework is to capture four document images guiding the user in a self-contained and accessible system.

This SDK captures the document images with the device rear camera.

This SDK retrieves this information:

• Document type.
• Document obverse (front side) image without flash.
• Document obverse image with flash.
• Document reverse (back side) image without flash.

Some permissions are needed and have to be written in the info.plist of the app using the framework:

• Camera.

In order to improve the user experience, the camera takes the document photo automatically (without touching the screen), this is done due to its automatic document recognition.

The SDK can be configured using a dictionary. All possible keys and values can be checked in Configuration. See integration example below.

Specifications

• iOS (iPhone only) minimum operating system version: 11.0.
• Flash camera and torch mode can be required for several functionalities.
• Additionally, some dependencies are needed.
  • Internal dependencies.
    • VDLibrary
    • ImageProcessing

• Full SDK implementation sizes in MB:

  Architecture	VDLibrary	ImageProcessing	SDK	Total
  arm64 (device)	2.67	10.40	3.57	16.64
  arm64 (simulator)	2.65	10.37	3.57	16.59
  x86_64 (simulator)	2.62	16.07	3.56	22.25
  TOTAL	5.65	36.81	7.41	49.87

  These sizes have been calculated using lipo -detailed_info for fat libraries and gdu or du for the rest of files. No dSYMs folders are included in these sizes. The final AppStore and installed sizes may differ.

  If more than one architecture is supported the total size is the sum of each one of them, e.g. if all architectures are supported the combined size of this SDK and its dependencies will be a total of 49.87MB.

  The final user is not affected by this total size because the store only distributes the specific architecture of the user's device once the app is downloaded and installed.

• Image is resized to 8MPx and file size is normally smaller than 1.5MB.

Integration

• Create a new Xcode project.
• Add permissions required into Info.plist:
  • Camera Usage.
• Drag and drop all .xcframework into Xcode and copy inside project.
• Add all .xcframework into the targets general tab, inside Embedded Binaries and Linked Frameworks and Libraries (if they do not appear yet), they should appear in mode "Embed & Sign".
• Import VDDocumentCapture/VDDocumentCapture.h (Objective-C) or VDDocumentCapture (Swift) and implement VDDocumentCaptureProtocol in the class that uses it.
• Write down all the required delegated methods into the class that uses the framework. Call the methods of the SDK as needed.

SDK update

Once a new SDK is released the following steps have to be followed to properly update the SDK.

• Remove all updating .framework located in the project. Do not remove only the reference; remove the actual file if the deletion is done with the help of Xcode. Just in case, empty the bin too.
• Compile and/or run to force errors. If no error occurs then a cached framework is in memory. Clean cache and project.
• Add all new .xcframework and implement new interfaces if necessary.
• Compile and run.

In case of doubt, also the following can be done.

• Check the installed version by calling the getVersion() method.

Example of use

Objective-c

#import "VDDocumentCapture/VDDocumentCapture.h"
@‌interface ViewController () <VDDocumentCaptureProtocol>

- (void) viewDidAppear:(BOOL)animated {
  ////////////// Veridas' recommended configuration //////////////
  NSMutableDictionary<NSString*, id>* configuration = [NSMutableDictionary dictionary];
  configuration[@"capturebackgroundcolor"] = @{@"alpha": @"0.502", @"red": @"0", @"green": @"13", @"blue": @"68"};
  configuration[@"continuebuttonbackgroundcolor"] = @{@"alpha": @"1", @"red": @"0", @"green": @"13", @"blue": @"68"};
  configuration[@"popupvalidationbackgroundcolor"] = @{@"alpha": @"1", @"red": @"0", @"green": @"13", @"blue": @"68"};
  configuration[@"flashwaitingalertbgcolor"] = @{@"alpha": @"1", @"red": @"0", @"green": @"13", @"blue": @"68"};
  configuration[@"documentdetectedoklevel1color"] = @{@"alpha": @"1", @"red": @"83", @"green": @"163", @"blue": @"53"};
  configuration[@"documentdetectedoklevel2color"] = @{@"alpha": @"1", @"red": @"135", @"green": @"191", @"blue": @"114"};
  configuration[@"documentdetectedoklevel3color"] = @{@"alpha": @"1", @"red": @"186", @"green": @"218", @"blue": @"174"};
  configuration[@"documentdetectedveryclosecolor"] = @{@"alpha": @"1", @"red": @"235", @"green": @"141", @"blue": @"0"};
  configuration[@"documentdetectedveryfarcolor"] = @{@"alpha": @"1", @"red": @"235", @"green": @"141", @"blue": @"0"};
  configuration[@"backgroundcolor"] = @{@"alpha": @"1", @"red": @"0", @"green": @"13", @"blue": @"68"};
  configuration[@"repeatbuttonbackgroundcolor"] = @{@"alpha": @"1", @"red": @"255", @"green": @"255", @"blue": @"255"};
  configuration[@"repeatbuttontextcolor"] = @{@"alpha": @"1", @"red": @"0", @"green": @"13", @"blue": @"68"};
  configuration[@"validationbackgroundcolor"] = @{@"alpha": @"1", @"red": @"172", @"green": @"176", @"blue": @"195"};
  configuration[@"checkdocumenttextcolor"] = @{@"alpha": @"1", @"red": @"0", @"green": @"13", @"blue": @"68"};
  configuration[@"shutterbuttonmessagebackgroundcolor"] = @{@"alpha": @"1", @"red": @"0", @"green": @"13", @"blue": @"68"};
  configuration[@"tickcirclecolor"] = @{@"alpha": @"1", @"red": @"220", @"green": @"239", @"blue": @"212"};
  configuration[@"tickcolor"] = @{@"alpha": @"1", @"red": @"83", @"green": @"163", @"blue": @"53"};
  configuration[@"tutorialbackgroundcolor"] = @{@"alpha": @"1", @"red": @"255", @"green": @"255", @"blue": @"255"};
  configuration[@"tutorialtextcolor"] = @{@"alpha": @"1", @"red": @"0", @"green": @"13", @"blue": @"68"};
  configuration[@"tutorialcontinuebuttoncolor"] = @{@"alpha": @"1", @"red": @"0", @"green": @"13", @"blue": @"68"};
  configuration[@"tutorialtitlecolor"] = @{@"alpha": @"1", @"red": @"0", @"green": @"13", @"blue": @"68"};

  // The recommended work mode is with document ids, which can be found in the Description section.
  NSMutableArray<NSString *> * documents = [NSMutableArray new];
  [documents addObject:@"ES_IDCard_2006"]; or [documents addObject:VDDOCUMENT_ID_ES_IDCard_2006];
  [documents addObject:@"ES_IDCard_2015"]; or [documents addObject:VDDOCUMENT_ID_ES_IDCard_2015];
  if (![VDDocumentCapture isStarted]) {
      // Here a call with options can be made, if no configuration is set the default values are used. 
      // See below for configuration example.
      [VDDocumentCapture startWithDelegate:self andDocumentIds: documents andConfiguration: configuration];
  }
}

// In another place you can stop the process (not recommended).
- (void) stopFramework {
  // Stop it whenever you want.
  [VDDocumentCapture stop];
}

// Protocol methods.
// Called when a document image has been captured
- (void) VDDocumentCaptured:(NSData *) imageData withCaptureType:(VDCaptureType) captureType andDocument:(NSArray<VDDocument *> *) document {
  // Do with image as needed.
}

// Called when the framework has finished.
// processFinished (Boolean) Indicates if the process has finished (true) or has been interrupted (false)
- (void) VDDocumentAllFinished:(Boolean)processFinished {
    // When the framework ends, proceed as needed.
}

// Called when the number of seconds passed without taking the photo.
- (void) VDTimeWithoutPhotoTaken:(int)seconds withCaptureType:(VDCaptureType)capture {
  // Action may be needed.
}

Swift

import VDDocumentCapture
class MyClass: VDDocumentCaptureProtocol {
    // PROTOCOL IMPLEMENTATION.
    // Called when a document image has been captured
    func vdDocumentCaptured(_ imageData: Data!, with captureType: VDCaptureType, andDocument document: [VDDocument]!)  {
        // Do with image as needed.
    }
    // Called when the framework has finished.
    // processFinished (Boolean) Indicates if the process has finished (true) or has been interrupted (false)
    func vdDocumentAllFinished(_ processFinished: Bool) {
        // When the framework ends, proceed as needed
    }
    // Called when the number of seconds passed without taking the photo.
    func vdTimeWithoutPhotoTaken(_ seconds: Int32, with capture: VDCaptureType) {
        // Action may be needed.
    }

    ....

  // Call something like this to start the document capture
    let configuration : [String : Any] = [:]

    ////////////// Veridas' recommended configuration //////////////
    configuration["capturebackgroundcolor"] = ["alpha": "0.502", "red": "0", "green": "13", "blue": "68"] 
    configuration["continuebuttonbackgroundcolor"] = ["alpha": "1", "red": "0", "green": "13", "blue": "68"] 
    configuration["popupvalidationbackgroundcolor"] = ["alpha": "1", "red": "0", "green": "13", "blue": "68"] 
    configuration["flashwaitingalertbgcolor"] = ["alpha": "1", "red": "0", "green": "13", "blue": "68"] 
    configuration["documentdetectedoklevel1color"] = ["alpha": "1", "red": "83", "green": "163", "blue": "53"] 
    configuration["documentdetectedoklevel2color"] = ["alpha": "1", "red": "135", "green": "191", "blue": "114"] 
    configuration["documentdetectedoklevel3color"] = ["alpha": "1", "red": "186", "green": "218", "blue": "174"] 
    configuration["documentdetectedveryclosecolor"] = ["alpha": "1", "red": "235", "green": "141", "blue": "0"] 
    configuration["documentdetectedveryfarcolor"] = ["alpha": "1", "red": "235", "green": "141", "blue": "0"] 
    configuration["backgroundcolor"] = ["alpha": "1", "red": "0", "green": "13", "blue": "68"] 
    configuration["repeatbuttonbackgroundcolor"] = ["alpha": "1", "red": "255", "green": "255", "blue": "255"] 
    configuration["repeatbuttontextcolor"] = ["alpha": "1", "red": "0", "green": "13", "blue": "68"] 
    configuration["validationbackgroundcolor"] = ["alpha": "1", "red": "172", "green": "176", "blue": "195"] 
    configuration["checkdocumenttextcolor"] = ["alpha": "1", "red": "0", "green": "13", "blue": "68"] 
    configuration["shutterbuttonmessagebackgroundcolor"] = ["alpha": "1", "red": "0", "green": "13", "blue": "68"] 
    configuration["tickcirclecolor"] = ["alpha": "1", "red": "220", "green": "239", "blue": "212"] 
    configuration["tickcolor"] = ["alpha": "1", "red": "83", "green": "163", "blue": "53"] 
    configuration["tutorialbackgroundcolor"] = ["alpha": "1", "red": "255", "green": "255", "blue": "255"] 
    configuration["tutorialtextcolor"] = ["alpha": "1", "red": "0", "green": "13", "blue": "68"] 
    configuration["tutorialcontinuebuttoncolor"] = ["alpha": "1", "red": "0", "green": "13", "blue": "68"] 
    configuration["tutorialtitlecolor"] = ["alpha": "1", "red": "0", "green": "13", "blue": "68"] 

    configuration["closebutton"] = "YES"
    let documents : [String] = ["ES_IDCard_2006", "ES_IDCard_2015"]
    if !VDDocumentCapture.isStarted() {
        VDDocumentCapture.start(withDelegate: self, andDocumentIds: documents, andConfiguration: configuration)
    }
}

Workflow

The next diagram represents de current workflow of the framework. Some method's names may de shortened due to legibility issues.

Third party libraries

• OpenCV 4.5.2 (main page. documentation). Used for image manipulation.