Skip to main content

Generic Document Recognizer | iOS Document Scanner

The Scanbot SDK provides the ability to detect various types of documents on the image, crop them and recognize the fields' data via the Generic Document Recognizer.

Currently, the Generic Document Recognizer supports the following types of documents:

  • German ID Card
  • German Passport
  • German Driver's License

As a result of scanning, the user gets the SBSDKGenericDocument object, if the result of the scanning was successful. SBSDKGenericDocument is a hierarchically structured type that contains the document's type, eventually a list of child documents, a total recognition confidence and a list of the document's fields. Each field is represented by the SBSDKGenericDocumentField class, holding the field's type, a cropped image of the field, the recognized text and the field's recognition confidence.

For convenience and user interface related tasks, the SBSDKGenericDocument can either be flattened using the functions -[SBSDKGenericDocument flatDocumentIncludingEmptyChildren:includingEmptyFields:] and -[SBSDKGenericDocument allFieldsIncludingEmptyFields:] or wrapped into a document's type specific subclass of SBSDKGenericDocumentWrapper using the function -[SBSDKGenericDocument wrap].

Currently, the following document wrappers exist:

  • SBSDKGenericDocumentDeIdCardFront - German ID card front side
  • SBSDKGenericDocumentDeIdCardBack - German ID card back side
  • SBSDKGenericDocumentDePassport - German passport
  • SBSDKGenericDocumentDeDriverLicenseFront - German driver's license front side
  • SBSDKGenericDocumentDeDriverLicenseBack - German driver's license back side

The Generic Document Recognizer is based on the OCR feature and thus requires the proper installation of the corresponding OCR language files (e.g. for English please add the file eng.traineddata). For more details on how to set up the OCR language files please refer to the OCR section.

Generic Document Recognizer UI#

There are two ways to integrate the component into the application:

Classical UI Component#

The main class of the Classical UI component is SBSDKGenericDocumentRecognizerViewController.

Usually this view controller is embedded as a child view controller into another view controller, the parent view controller. The parent view controller usually acts as the delegate and processes the recognition results. You still have full control over the UI elements and can add additional views and buttons to your view controller. The classical component does not display results, instead it just forwards them to the delegate.

import UIKitimport ScanbotSDK
// This is a simple, empty view controller which acts as a container and delegate for the SBSDKGenericDocumentRecognizerViewController.class GenericDocumentViewController: UIViewController, SBSDKGenericDocumentRecognizerViewControllerDelegate {
    // The instance of the recognition view controller.    var recognizerController: SBSDKGenericDocumentRecognizerViewController!
    override func viewDidLoad() {        super.viewDidLoad()
        // Define the types of documents that should be recognized.        // Recognize all supported document types.        let allTypes: [SBSDKGenericDocumentRootType] = SBSDKGenericDocumentRootType.allDocumentTypes()
        // Recognize German ID cards only. Front and/or back side.        let idCardTypes: [SBSDKGenericDocumentRootType] = [            SBSDKGenericDocumentRootType.deIdCardFront(),            SBSDKGenericDocumentRootType.deIdCardBack()        ]
        // Recognize German passports only. Front side only.        let passportTypes: [SBSDKGenericDocumentRootType] = [            SBSDKGenericDocumentRootType.dePassport()        ]
        // Recognize German driver's licenses only. Front and/or back side.        let driverLicenseTypes: [SBSDKGenericDocumentRootType] = [            SBSDKGenericDocumentRootType.deDriverLicenseFront(),            SBSDKGenericDocumentRootType.deDriverLicenseBack()        ];
        // Create the SBSDKGenericDocumentRecognizerViewController instance        // and let it embed into this view controller's view.        self.recognizerController            = SBSDKGenericDocumentRecognizerViewController(parentViewController: self,                                                           //Embed the recognizer in this view controller's view.                                                           parentView: self.view,                                                           // Pass the above types here as required.                                                           acceptedDocumentTypes: allTypes,                                                           // Set the delegate to this view controller.                                                           delegate: self)

        // Define additional configuration of the the recognizer view controller.
        // E.g. turn the flashlight on/off.        self.recognizerController.flashLightEnabled = false
        // Turn the viewfinder on/off.        self.recognizerController.showViewFinder = true
        // Configure the view finder colors.        self.recognizerController.viewFinderLineColor = UIColor.red        self.recognizerController.viewFinderBackgroundColor = UIColor.red.withAlphaComponent(0.1)    }
    // The delegate implementation of SBSDKGenericDocumentViewController.    func documentRecognizerViewController(_ controller: SBSDKGenericDocumentRecognizerViewController,                                          didRecognizeResult result: SBSDKGenericDocumentRecognitionResult,                                          on image: UIImage) {        // Access the document's fields directly by iterating over the document's fields.        result.document?.fields.forEach { field in            // Print field type name, field text and field confidence to the console.            print("\(field.type.name) = \(field.value?.text ?? "") (Confidence: \(field.value?.confidence ?? 0.0)")        }
        // Or get a field by its name.        if let nameField = result.document?.field(byTypeName: "Surname") {            // Access various properties of the field.            let fieldTypeName = nameField.type.name            let fieldValue = nameField.value?.text            let confidence = nameField.value?.confidence        }
        // Or create a wrapper for the document if needed.        // You must cast it to the specific wrapper subclass.        if let wrapper = result.document?.wrap() as? SBSDKGenericDocumentDeIdCardFront {            // Access the document's fields easily through the wrapper.            let fieldTypeName = wrapper.surname.type.name            let fieldValue = wrapper.surname.value?.text            let confidence = wrapper.surname.value?.confidence        }    }}

Ready-To-Use UI Component#

The main class of the Ready-To-Use UI (RTU UI) component is SBSDKUIGenericDocumentRecognizerViewController.

Usually this view controller is used as a separate screen for recognizing generic documents. It displays the recognition results in an expandable tableview while the recognizer continues to recognize the document to further improve the result. SBSDKUIGenericDocumentRecognizerViewController even allows you to scan two sides of a document, e.g. an ID card with front and back sides, in a single screen. Once happy with the results, press the submit button and the recognizer view controller is dismissed and passes the results to its delegate.

While you don't have direct control of the actual recognition view controller you can use the SBSDKUIGenericDocumentRecognizerConfiguration to customize it in a variety of ways, such as colors, texts and behavior.

import UIKitimport ScanbotSDK
// This is a simple, empty view controller which acts as a container and delegate for the SBSDKGenericDocumentRecognizerViewController.class GenericDocumentViewController: UIViewController, SBSDKGenericDocumentRecognizerViewControllerDelegate {
    // The instance of the recognition view controller.    var recognizerController: SBSDKGenericDocumentRecognizerViewController!
    override func viewDidLoad() {        super.viewDidLoad()
        // Define the types of documents that should be recognized.        // Recognize all supported document types.        let allTypes: [SBSDKGenericDocumentRootType] = SBSDKGenericDocumentRootType.allDocumentTypes()
        // Recognize German ID cards only. Front and/or back side.        let idCardTypes: [SBSDKGenericDocumentRootType] = [            SBSDKGenericDocumentRootType.deIdCardFront(),            SBSDKGenericDocumentRootType.deIdCardBack()        ]
        // Recognize German passports only. Front side only.        let passportTypes: [SBSDKGenericDocumentRootType] = [            SBSDKGenericDocumentRootType.dePassport()        ]
        // Recognize German driver's licenses only. Front and/or back side.        let driverLicenseTypes: [SBSDKGenericDocumentRootType] = [            SBSDKGenericDocumentRootType.deDriverLicenseFront(),            SBSDKGenericDocumentRootType.deDriverLicenseBack()        ];
        // Create the SBSDKGenericDocumentRecognizerViewController instance        // and let it embed into this view controller's view.        self.recognizerController            = SBSDKGenericDocumentRecognizerViewController(parentViewController: self,                                                           //Embed the recognizer in this view controller's view.                                                           parentView: self.view,                                                           // Pass the above types here as required.                                                           acceptedDocumentTypes: allTypes,                                                           // Set the delegate to this view controller.                                                           delegate: self)

        // Define additional configuration of the the recognizer view controller.
        // E.g. turn the flashlight on/off.        self.recognizerController.flashLightEnabled = false
        // Turn the viewfinder on/off.        self.recognizerController.showViewFinder = true
        // Configure the view finder colors.        self.recognizerController.viewFinderLineColor = UIColor.red        self.recognizerController.viewFinderBackgroundColor = UIColor.red.withAlphaComponent(0.1)    }
    // The delegate implementation of SBSDKGenericDocumentViewController.    func documentRecognizerViewController(_ controller: SBSDKGenericDocumentRecognizerViewController,                                          didRecognizeResult result: SBSDKGenericDocumentRecognitionResult,                                          on image: UIImage) {        // Access the document's fields directly by iterating over the document's fields.        result.document?.fields.forEach { field in            // Print field type name, field text and field confidence to the console.            print("\(field.type.name) = \(field.value?.text ?? "") (Confidence: \(field.value?.confidence ?? 0.0)")        }

        // Or get a field by its name.        if let nameField = result.document?.field(byTypeName: "Surname") {            // Access various properties of the field.            let fieldTypeName = nameField.type.name            let fieldValue = nameField.value?.text            let confidence = nameField.value?.confidence        }

        // Or create a wrapper for the document if needed.        // You must cast it to the specific wrapper subclass.        if let wrapper = result.document?.wrap() as? SBSDKGenericDocumentDeIdCardFront {            // Access the document's fields easily through the wrapper.            let fieldTypeName = wrapper.surname.type.name            let fieldValue = wrapper.surname.value?.text            let confidence = wrapper.surname.value?.confidence        }    }}