DOT iOS Document library

v3.0.1

Introduction

DOT iOS Document provides components for document capture and related functionalities which are easy to integrate into an iOS application.

Requirements

  • Xcode 11.4+

  • iOS 11.0+

  • Swift or Objective-C

  • CocoaPods

Distribution

Cocoapods

DOT iOS Document is distributed as a XCFramework - DotDocument.xcframework using Cocoapods with its dependencies stored in our public github repository. It can be easily integrated into XCode with custom definition of podspecs. First step is to insert following line of code on top of you Podfile.

Podfile
source 'https://github.com/innovatrics/innovatrics-podspecs'

Then DOT iOS Document dependency must be specified in Podfile. Dependencies of DOT iOS Document will be downloaded alongside it.

Podfile
source 'https://github.com/innovatrics/innovatrics-podspecs'

use_frameworks!

target 'YOUR_TARGET' do

pod 'dot-document'

end

In case of CocoaPods problem with pod install, try to clone the private pod repository manually.

pod repo remove innovatrics
pod repo add innovatrics https://github.com/innovatrics/innovatrics-podspecs

Supported Architectures

DOT iOS Document provides all supported architectures in the distributed XCFramework package. Device binary contains: arm64. Simulator binary contains: x86_64, arm64.

Permissions

Set the following permission in Info.plist:

Info.plist
<key>NSCameraUsageDescription</key>
	<string>Your usage description</string>

Basic Setup

Logging

DOT iOS Document supports logging using a global Logger class. You can set the log level as follows:

import DotDocument

Logger.logLevel = .debug

Log levels:

  • info

  • debug

  • warning

  • error

  • none

Each log message contains dot-document tag. Keep in mind that logging should be used just for debugging purposes.

Components

Overview

DOT iOS Document provides both non-UI and UI components. Non-UI components are aimed to be used by developers who want to build their own UI using the DOT iOS Document functionality. UI components are build on top of non-UI components. Components having UI are available as UIViewController classes and can be embedded into the application’s existing UI or presented using the standard methods.

List of Non-UI Components

DOCUMENT DETECTOR

A component for performing document detection on an image.

IMAGE PARAMETERS ANALYZER

A component for computing image parameters such as sharpness, brightness or hotspots score.

IMAGE PERSPECTIVE WARPER

A component for warping the perspective of an image according to the detected document corners.

DOCUMENT AUTO CAPTURE CONTROLLER

A component for capturing good quality photos suitable for optical character recognition.

MACHINE READABLE ZONE READER

A component for reading Machine Readable Zone (MRZ).

List of UI Components

DOCUMENT AUTO CAPTURE

An visual component for capturing good quality photos suitable for optical character recognition.

Non-UI Components

Document Detector

The DocumentDetector class provides a document detection functionality.

Create a DocumentDetector:

let documentDetector = DocumentDetector()

To perform detection, call the following method on the background thread:

let result = try? documentDetector.detect(bgraRawImage: bgraRawImage)

Image Parameters Analyzer

The ImageParametersAnalyzer class provides an image parameters analysis functionality.

Create ImageParametersAnalyzer:

let imageParametersAnalyzer = ImageParametersAnalyzer()

To perform analysis, call the following method on the background thread:

let imageParameters = try? imageParametersAnalyzer.analyze(bgraRawImage: bgraRawImage)

Image Perspective Warper

The ImagePerspectiveWarper class provides perspective warping functionality.

Create ImagePerspectiveWarper:

let imagePerspectiveWarper = ImagePerspectiveWarper()

To perform perspective warping, call the following method on the background thread:

let warpedBgraRawImage = try? imagePerspectiveWarper.warp(bgraRawImage: bgraRawImage, corners: corners, targetImageSize: targetImageSize)

Document Auto Capture Controller

The DocumentAutoCaptureController class provides a stateful document auto capture functionality.

Create DocumentAutoCaptureController:

let configuration = DocumentAutoCaptureControllerConfiguration(
            validators: validators,
            minValidFramesInRowToStartCandidateSelection: 2
            candidateSelectionDurationMillis: 1000,
            detectionNormalizedRectangle: detectionNormalizedRectangle,
            imageParametersNormalizedRectangle: imageParametersNormalizedRectangle,
            isMrzReadingEnabled: false)
let controller = DocumentAutoCaptureController(configuration: configuration)
DocumentAutoCaptureControllerConfiguration
  • (Required) [-] validators: [DocumentAutoCaptureDetectionValidator] - Array of validators which will be used to validate input image.

  • (Optional) [2] minValidFramesInRowToStartCandidateSelection: Int - Minimum number of valid frames in a row to start candidate selection.

  • (Optional) [1000] candidateSelectionDurationMillis: Int - Duration of candidate selection phase.

  • (Optional) [-] detectionNormalizedRectangle: RectangleDouble - Crop an input image to normalized detection rectangle and use that for document detection.

  • (Optional) [-] imageParametersNormalizedRectangle: RectangleDouble - Crop an input image to normalized image parameters rectangle and use that to analyze image parameters.

  • (Optional) [false] isMrzReadingEnabled: Bool - Use this flag to enable MRZ reading during document auto capture process.

You can use detectionNormalizedRectangle to specify the region in the input image which will be used for document detection. For example, if you want to ignore top 30% and bottom 30% of the input image, you can do it as follows:

let detectionNormalizedRectangle = RectangleDouble(left: 0, top: 0.3, right: 1.0, bottom: 0.7)

If detectionNormalizedRectangle is set to nil(default) the full input image is used for document detection.

You can use imageParametersNormalizedRectangle to specify the region in the input image which will be used to analyze image parameters. For example, if you want to ignore top 35%, left 5%, right 5% and bottom 35% of the input image, you can do it as follows:

let imageParametersNormalizedRectangle = RectangleDouble(left: 0.05, top: 0.35, right: 0.95, bottom: 0.65)

If imageParametersNormalizedRectangle is set to nil(default) the full input image is used to analyze image parameters.

To capture a good quality document image, repeatedly call the process() method using the camera frames:

documentAutoCaptureController.process(bgraRawImage: bgraRawImage)

The controller evaluates the document image requirements for each frame. Once the controller detects enough (minValidFramesInRowToStartCandidateSelection) valid frames in a row, candidate selection is started with duration of candidateSelectionDurationMillis milliseconds. After the candidate selection is finished, the best document image candidate is returned by the delegate and the document auto capture process is over.

In case you want to force the capture event, call the requestCapture() method. After you call the next process() method, the input image will be returned as a result by the delegate and the document auto capture process will be finished.

documentAutoCaptureController.requestCapture();

In case you want to restart the document auto capture process, call the restart() method.

documentAutoCaptureController.restart();

Machine Readable Zone Reader

The MrzReader class provides a Machine Readable Zone (MRZ) reading functionality.

Create MrzReader:

let mrzReader = MrzReader()

To read a MRZ, call the following method on the background thread:

let result = mrzReader.read(bgraRawImage: bgraRawImage, documentDetectorResult: documentDetectorResult)

Or alternatively, if you know the travel document type, call this method to increase the precision of the reading process:

let result = mrzReader.read(bgraRawImage: bgraRawImage, documentDetectorResult: documentDetectorResult, travelDocumentType: travelDocumentType)

The documentDetectorResult argument is a product of either Document Detector component, Document Auto Capture Controller component or Document Auto Capture UI component.

The result of successful MRZ reading contains travel document type and machine readable zone. If MRZ reading was not successful, the result will contain an error and travelDocumentType and/or machineReadableZone may be nil.

UI Components

View Controller Configuration

Components containing UI are embedded into the application as view controllers. All view controllers can be embedded into your own view controller or presented directly. Each view controller can be configured using its *Configuration class and each view controller can have its appearance customized using its *Style class.

To present view controller:

let controller = DocumentAutoCaptureViewController.create(configuration: .init(), style: .init())
controller.delegate = self
navigationController?.pushViewController(controller, animated: true)

To embed view controller into your view controller:

override func viewDidLoad() {
    super.viewDidLoad()

    addChild(viewController)
    view.addSubview(viewController.view)
    viewController.view.translatesAutoresizingMaskIntoConstraints = false
    viewController.didMove(toParent: self)

    NSLayoutConstraint.activate([
        viewController.view.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
        viewController.view.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
        viewController.view.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor),
        viewController.view.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor)
    ])
}
Safe Area

DOT iOS Document view controllers ignore safe area layout guide when they layout their subviews. Therefore, for example if you push DOT iOS Document view controller using UINavigationController, you will get incorrect layout. If you want to respect safe area layout guide, you should embed DOT iOS Document view controller in a container view controller and setup the layout constraints accordingly.

Document Auto Capture

The view controller with document placeholder which is used for capturing document images.

The following properties are available in DocumentAutoCaptureConfiguration:

  • (Optional) [CameraFacing.back] cameraFacing: CameraFacing – Camera facing

    • CameraFacing.front

    • CameraFacing.back

  • (Optional) [CameraPreviewScaleType.fit] cameraPreviewScaleType: CameraPreviewScaleType – The camera preview scale type

    • CameraPreviewScaleType.fit

  • (Optional) [CameraPreset.fullHD] cameraPreset: CameraPreset – Camera preset

    • CameraPreset.photo

    • CameraPreset.hd

    • CameraPreset.fullHD

  • (Optional) [0.2] confidenceThreshold: Double - Document detection confidence threshold in range [0, 1.0].

  • (Optional) [0.85] sharpnessLowThreshold: Double - Minimal accepted sharpness threshold in range [0, 1.0].

  • (Optional) [0.25] brightnessLowThreshold: Double - Minimal accepted brightness threshold in range [0, 1.0].

  • (Optional) [0.9] brightnessHighThreshold: Double - Maximal accepted brightness threshold in range [0, 1.0].

  • (Optional) [0.008] hotspotsScoreHighThreshold: Double - Maximal accepted hotspots score threshold in range [0, 1.0].

  • (Optional) [false] isMrzReadingEnabled: Bool - Use this flag to enable MRZ reading during document auto capture process.

The following properties are available in DocumentAutoCaptureStyle:

  • (Optional) [UIFont.systemFont(ofSize: 17, weight: .bold)] instructionFont: UIFont - Instruction label font.

  • (Optional) [UIColor.black] instructionTextColor: UIColor - Instruction label text color.

  • (Optional) [UIColor.black] instructionCapturingTextColor: UIColor - Instruction label text color during capture.

  • (Optional) [UIColor.white] instructionBackgroundColor: UIColor - Instruction background color.

  • (Optional) [UIColor.white] instructionCapturingBackgroundColor: UIColor - Instruction background color during capture.

  • (Optional) [UIColor.black] placeholderColor: UIColor - Placeholder color.

  • (Optional) [UIColor.green] placeholderCapturingColor: UIColor - Placeholder color during capture.

You can handle the DocumentAutoCaptureViewController events using its delegate DocumentAutoCaptureViewControllerDelegate.

@objc(DOTDocumentAutoCaptureViewControllerDelegate) public protocol DocumentAutoCaptureViewControllerDelegate: AnyObject {

    /// Tells the delegate that the document was captured.
    @objc func documentAutoCaptureViewController(_ viewController: DocumentAutoCaptureViewController, captured result: DocumentAutoCaptureResult)

    /// Tells the delegate that you have no permission for camera usage.
    @objc optional func documentAutoCaptureViewControllerNoCameraPermission(_ viewController: DocumentAutoCaptureViewController)

    @objc optional func documentAutoCaptureViewControllerViewDidLoad(_ viewController: DocumentAutoCaptureViewController)
    @objc optional func documentAutoCaptureViewControllerViewDidLayoutSubviews(_ viewController: DocumentAutoCaptureViewController)
    @objc optional func documentAutoCaptureViewControllerViewWillAppear(_ viewController: DocumentAutoCaptureViewController)
    @objc optional func documentAutoCaptureViewControllerViewDidAppear(_ viewController: DocumentAutoCaptureViewController)
    @objc optional func documentAutoCaptureViewControllerViewWillDisappear(_ viewController: DocumentAutoCaptureViewController)
    @objc optional func documentAutoCaptureViewControllerViewDidDisappear(_ viewController: DocumentAutoCaptureViewController)
    @objc optional func documentAutoCaptureViewControllerViewWillTransition(_ viewController: DocumentAutoCaptureViewController)
}

In order to start the document auto capture process call the start() method.

In case you want to force the capture event, call the requestCapture() method.

In case you want to restart the document auto capture process (e.g. you want to capture both sides of the document, one after another), call the restart() method. The whole process will start from the beginning.

Customization of UI Components

Localization

String resources can be overridden in your application and alternative strings for supported languages can be provided following these two steps:

  1. Add your own Localizable.strings file to your project using standard iOS localization mechanism. To change a specific text override corresponding key in this Localizable.strings file.

  2. Set the localization bundle to the bundle of your application (preferably during the application launch in your AppDelegate).

Use this setup if you want to use standard iOS localization mechanism, which means your iOS application uses system defined locale.

import DotDocument

Localization.bundle = .main
Custom Localization

You can override standard iOS localization mechanism by providing your own translation dictionary and setting the Localization.useLocalizationDictionary flag to true. Use this setup if you do not want to use standard iOS localization mechanism, which means your iOS application ignores system defined locale and uses its own custom locale.

import DotDocument

guard let localizableUrl = Bundle.main.url(forResource: "Localizable", withExtension: "strings", subdirectory: nil, localization: "de"),
      let dictionary = NSDictionary(contentsOf: localizableUrl) as? [String: String]
else { return }

Localization.useLocalizationDictionary = true
Localization.localizationDictionary = dictionary
Localizable.strings
"dot.document_auto_capture.instruction.brightness_too_high" = "Less light needed";
"dot.document_auto_capture.instruction.brightness_too_low" = "More light needed";
"dot.document_auto_capture.instruction.candidate_selection" = "Hold still...";
"dot.document_auto_capture.instruction.document_centering" = "Center document";
"dot.document_auto_capture.instruction.document_not_present" = "Scan document";
"dot.document_auto_capture.instruction.document_too_close" = "Move back";
"dot.document_auto_capture.instruction.document_too_far" = "Move closer";
"dot.document_auto_capture.instruction.hotspots_present" = "Avoid reflections";
"dot.document_auto_capture.instruction.mrz_not_valid" = "Scan valid machine readable document";
"dot.document_auto_capture.instruction.sharpness_too_low" = "More light needed";

Common Classes

ImageSize

Class which represents a size of an image. To create an instance:

let imageSize = ImageSize(width: 100, height: 100)

BgraRawImage

Class which represents an image.

To create an instance from CGImage:

let bgraRawImage = BgraRawImageFactory.create(cgImage: cgImage)

To create CGImage from BgraRawImage:

let cgImage = CGImageFactory.create(bgraRawImage: bgraRawImage)

Corners

Class which represents a document card corners. To create an instance:

let corners = Corners(topLeft: topLeft, topRight: topRight, bottomRight: bottomRight, bottomLeft: bottomLeft)

Appendix

Changelog

3.0.1 - 2021-09-30

Added
  • DocumentAutoCaptureControllerConfiguration.minValidFramesInRowToStartCandidateSelection

3.0.0 - 2021-09-27

Added
  • Machine Readable Zone Reader component

  • MrzNotValidValidator

  • DocumentAutoCaptureFrameParameters.travelDocumentType and .machineReadableZone

  • DocumentAutoCaptureConfiguration.isMrzReadingEnabled, .cameraFacing, .cameraPreviewScaleType, .cameraPreset

  • BgraRawImage, BgraRawImageFactory, CGImageFactory

  • ImageSize

  • CameraPreset, CameraFacing, CameraPreviewScaleType

  • Corners

  • DocumentAutoCaptureControllerConfiguration

  • DocumentAutoCaptureDetection

  • DocumentAutoCaptureResult

  • ImagePerspectiveWarper

  • PointDouble, RectangleDouble, WrappedDouble

Changed
  • minimal required iOS version to iOS 11.0

  • improved performance of document detection algorithm

  • DocumentAutoCaptureFrameParametersValidator to DocumentAutocaptureDetectionValidator

  • DocumentAutocaptureDetectionValidator.validate()

  • DocumentAutoCaptureController.detect() to .process(bgraRawImage: BgraRawImage)

  • DetectionResult to DocumentDetector.Result

  • renamed DocumentCapturePlaceholderViewController to DocumentAutoCaptureViewController and all related API

  • renamed DotDocumentLocalization to Localization

  • changed localization keys

Removed
  • DocumentCaptureFreeViewController

  • DocumentAutoCaptureConfiguration.documentSource

  • CameraDocumentSource, ImageDocumentSource, VideoDocumentSource

  • Image, ImageBatch

  • DocumentAutoCaptureHint

  • DocumentAutoCaptureFrameParametersEvaluator

2.3.0 - 2021-05-14

Added
  • DocumentAutoCaptureViewControllerConfiguration to enable additional configuration of UI components

  • DocumentAutoCaptureViewControllerConfiguration property documentSource

  • DocumentAutoCaptureViewControllerConfiguration property confidenceThreshold

  • DocumentAutoCaptureViewControllerConfiguration property sharpnessLowThreshold

  • DocumentAutoCaptureViewControllerConfiguration property brightnessLowThreshold

  • DocumentAutoCaptureViewControllerConfiguration property brightnessHighThreshold

  • DocumentAutoCaptureViewControllerConfiguration property hotspotsScoreHighThreshold

  • DocumentDoesNotFitPlaceholderValidator

Changed
  • DocumentCapturePlaceholderViewController.create()

  • DocumentCaptureFreeViewController.create()

  • removed BorderMarginValidator

  • removed DocumentCenteredValidator

  • removed DocumentRotationValidator

  • removed SharpnessHighValidator

  • removed DocumentAutoCaptureHint.sharpnessHigh, .widthToHeightLow, .widthToHeightHigh, .documentNotCentered

  • BrightnessHighValidator.maxBrightness to .threshold

  • BrightnessLowValidator.minBrightness to .threshold

  • DocumentLargeValidator.maxSize to .documentWidthToImageWidthRatioThreshold

  • DocumentSmallValidator.minSize to .documentWidthToImageWidthRatioThreshold

  • DocumentNotDetectedValidator.minConfidence to .confidenceThreshold

  • SharpnessLowValidator.minSharpness to .threshold

  • localization keys

2.2.2 - 2021-05-03

Fixed
  • allow multiline hint label

2.2.1 - 2021-03-31

Fixed
  • performance issue in document autocapture process

Changed
  • renamed SingleImageBatch to SimpleImageBatch

  • PlaceholderImageBatch.init to init(image: Image, detectionFrame: CGRect, imageParametersFrame: CGRect)

2.2.0 - 2021-03-17

Added
  • DotDocumentLocalization.localizationDictionary and .useLocalizationDictionary to enable overriding of standard iOS localization mechanism

Changed
  • renamed Localization class to DotDocumentLocalization

2.1.0 - 2021-01-27

Changed
  • add DocumentCaptureViewController.start() to start capture process explicitly

  • capture process of DocumentCaptureViewController will no longer start implicitly

2.0.0 - 2021-01-13

Added
  • Localization class, to support localization in more complex projects

  • HotspotsScoreHighValidator

  • ImageParametersAnalyzer

  • ImageParameters

  • protocol ImageBatch

  • SingleImageBatch

  • PlaceholderImageBatch

  • DocumentAutoCaptureFrameParameters

  • DocumentAutoCaptureFrameParametersEvaluator

  • DocumentAutoCaptureType.simple and DocumentAutoCaptureType.secondaryImageParameters

  • DocumentSourceDelegate.sourceNotAuthorized() to allow handling of camera permission

  • DocumentCaptureViewControllerDelegate.documentSourceNotAuthorized() to allow handling of camera permission

Changed
  • renamed framework and module to DotDocument

  • changed localization keys

  • protocol DetectionValidatorProtocol renamed to DocumentAutoCaptureFrameParametersValidator

  • DocumentCaptureController renamed to DocumentAutoCaptureController

  • DocumentCaptureControllerDelegate renamed to DocumentAutoCaptureControllerDelegate

  • removed DocumentAutoCaptureController.detectionValidator added .evaluator of type DocumentAutoCaptureFrameParametersEvaluator instead

  • DocumentAutoCaptureController now detects from ImageBatch instead of Image, to allow more complex auto capture workflows

  • removed DocumentCaptureViewController.requestHighResolutionImage(), added .highResolutionCapture instead

  • removed DocumentCaptureViewController.startDocumentCapture(), .stopDocumentCapture(), added .restart() instead

  • removed DocumentCaptureController.startDetection(), .stopDetection() added DocumentAutoCaptureController.restart() instead

  • DocumentAutoCaptureFrameParametersValidator now requires DocumentAutoCaptureFrameParameters instead of DetectionResult

  • DocumentAutoCaptureControllerDelegate and DocumentCaptureViewControllerDelegate now provides DocumentAutoCaptureFrameParameters instead of DetectionResult

  • ImageParameters.brightness, .sharpness, .hotspotsScore and DetectionResult.confidence is now normalized to [0, 1.0]

  • confidence, brightness, sharpness, hotspotsScore validators take normalized input values

  • removed SequenceValidator use DocumentAutoCaptureFrameParametersEvaluator instead

  • removed SteadyValidator, hold still phase is always present in auto capture process and is handled by DocumentAutoCaptureController

1.2.2 - 2020-12-17

Added
  • support for iOS Simulator arm64 architecture

1.2.1 - 2020-11-04

Fixed
  • for CameraDocumentSource override NSObject.init() with convenience CameraDocumentSource.init() and with CameraDocumentSourcePreset.fullHD as default parameter.

1.2.0 - 2020-11-04

Added
  • CameraDocumentSourcePreset enum

Changed
  • CameraDocumentSource.init() has CameraDocumentSourcePreset parameter.

1.1.5 - 2020-10-23

Fixed
  • crop high resolution image from DocumentCapturePlaceholderViewController

  • clear preview layer when CameraDocumentSource.stopSession() is called

Changed
  • CameraDocumentSource.orientation type to AVCaptureVideoOrientation

Added
  • documentCaptureDidLayoutSubviews to DocumentCaptureViewControllerDelegate

1.1.4 - 2020-10-02

Fixed
  • orientation of high resolution image returned from DocumentCaptureViewController

1.1.3 - 2020-09-17

Changed
  • updated SAM to 2.0.0

1.1.2 - 2020-09-16

Fixed
  • SAM architecture selection when building for release

1.1.1 - 2020-08-28

Fixed
  • camera orientation wrong initial value when presenting DocumentCaptureViewController

1.1.0 - 2020-08-25

Changed
  • detect document from cropped image

  • DocumentCaptureController has startDetection(), stopDetection()

  • DocumentSourceProtocol has startSession(), stopSession()

  • DocumentCaptureViewController has startDocumentCapture(), stopDocumentCapture()

1.0.2 - 2020-08-04

Changed
  • use Operations in DocumentCaptureController

1.0.1 - 2020-08-04

Changed
  • removed type constraint from AnnotationLayerProtocol

1.0.0 - 2020-08-03

Fixed
  • fixed memory access issue when converting images to Image

Changed
  • CameraDocumentSource learned orientation support

  • rename DocumentCaptureSimpleViewController to DocumentCapturePlaceholderViewController

  • reworked validation process in DocumentCapturePlaceholderViewController

  • DocumentCaptureViewControllerDelegate is now shared between view controllers

  • removed DocumentDoesNotFitPlaceholderValidator

  • DocumentSmallValidator and DocumentLargeValidator now calculate using area instead of width

  • DocumentCaptureController.detectionWidth is now public

  • Image conversion to and from vImage_Buffer is now public

  • added Image transformation support

  • added transformation support to Camera and Video document source

Added
  • Added DocumentCaptureViewControllerStyle

  • Added DocumentCaptureFreeViewController

  • Landscape support in UI components

  • DocumentRotationValidator

  • DocumentCenterValidator

  • Logging support

0.2.0 - 2020-07-17

Changed
  • minimal supported iOS version to 10.0

0.1.1 - 2020-07-16

Changed
  • renamed module to DOTDocument

0.1.0 - 2020-07-13

  • First release