DOT iOS Document 3.0.0

This guide describes how to migrate DOT iOS Document version 2.x to version 3.0.0. Only the most important changes are highlighted in this guide. For more details, see the iOS sample.

Migration Steps#

Update iOS Deployment Target#

Minimal deployment target was changed to iOS 11.0.

DocumentDetector component#

• Use DocumentDetector instance method instead of static method.
• Replace DetectionResult with DocumentDetector.Result.

Before#

let image = Image(cgImage: cgImage)
let result: DetectionResult = try? DocumentDetector.detect(image: image)

After#

let bgraRawImage = BgraRawImageFactory.create(cgImage: cgImage)
let documentDetector = DocumentDetector()
let detectionResult: DocumentDetector.Result =  try? documentDetector.detect(bgraRawImage: bgraRawImage)

ImageParametersAnalyzer component#

• Use ImageParametersAnalyzer instance method instead of static method.

Before#

let image = Image(cgImage: cgImage)
let result: ImageParameters = try? ImageParametersAnalyzer.analyze(image: image)

After#

let bgraRawImage = BgraRawImageFactory.create(cgImage: cgImage)
let imageParametersAnalyzer = ImageParametersAnalyzer()
let imageParameters: ImageParameters =  try? imageParametersAnalyzer.analyze(bgraRawImage: bgraRawImage)

ImagePerspectiveWarper component#

Before#

let image = Image(cgImage: cgImage)
let corners = detectionResult.corners
let warpedImage: Image = try? DocumentDetector.warpPerspective(image: image, corners: corners)

After#

let bgraRawImage = BgraRawImageFactory.create(cgImage: cgImage)
let outputImageSize = bgraRawImage.size
let imagePerspectiveWarper = ImagePerspectiveWarper()
let warpedBgraRawImage: BgraRawImage =  try? imagePerspectiveWarper.warp(bgraRawImage: bgraRawImage, corners: detectionResult.corners!, targetImageSize: outputImageSize)

DocumentAutoCaptureController component#

• Use DocumentAutoCaptureControllerConfiguration to create DocumentAutoCaptureController.
• Use process(bgraRawImage: BgraRawImage) instead of detect(imageBatch: ImageBatch)
• Update DocumentAutoCaptureControllerDelegate methods.

Before#

let documentAutoCaptureController = DocumentAutoCaptureController(autoCaptureType: .withSecondaryImage)
documentAutoCaptureController.delegate = self
documentAutoCaptureController.evaluator = evaluator
documentAutoCaptureController.detect(imageBatch: imageBatch)

After#

let configuration = DocumentAutoCaptureControllerConfiguration(validators: [DocumentNotDetectedValidator(confidenceThreshold: 0.2)],
                                                               candidateSelectionDurationMillis: 1000,
                                                               detectionNormalizedRectangle: nil,
                                                               imageParametersNormalizedRectangle: nil,
                                                               isMrzReadingEnabled: false)
let documentAutoCaptureController = DocumentAutoCaptureController(configuration: configuration)
documentAutoCaptureController.delegate = self
documentAutoCaptureController.process(bgraRawImage: bgraRawImage)

DocumentAutoCaptureViewController component#

• Update DocumentAutoCaptureConfiguration with new camera configuration options.

Before#

let source = CameraDocumentSource(preset: .fullHD)
let configuration = DocumentAutoCaptureViewControllerConfiguration(documentSource: source,
                                                                   confidenceThreshold: 0.2,
                                                                   sharpnessLowThreshold: 0.85,
                                                                   brightnessLowThreshold: 0.25,
                                                                   brightnessHighThreshold: 0.9,
                                                                   hotspotsScoreHighThreshold: 0.008)
let viewController = DocumentCapturePlaceholderViewController.create(configuration: configuration)
viewController.delegate = self

After#

let configuration = try! DocumentAutoCaptureConfiguration(confidenceThreshold: 0.2,
                                                          sharpnessLowThreshold: 0.85,
                                                          brightnessLowThreshold: 0.25,
                                                          brightnessHighThreshold: 0.9,
                                                          hotspotsScoreHighThreshold: 0.008,
                                                          cameraPreset: .fullHD)
let viewController = DocumentAutoCaptureViewController.create(configuration: configuration)
viewController.delegate = self

DocumentAutoCaptureViewControllerDelegate delegate#

• Update method signatures and new return types.

Before#

extension DemoViewController: DocumentCaptureViewControllerDelegate {

    func documentCaptured(_ controller: DocumentCaptureViewController, image: Image, frameParameters: DocumentAutoCaptureFrameParameters) {
        print("Captured Document:", frameParameters.detectionResult.confidence)
        print("Image:", image.width, image.height)

        if let annotatedImage = image.cgImageAnnotated(corners: frameParameters.detectionResult.corners) {
            photoImageView.image = UIImage(cgImage: annotatedImage)
        }
        navigationController?.popViewController(animated: true)
    }

    func documentDetected(_ controller: DocumentCaptureViewController, image: Image, frameParameters: DocumentAutoCaptureFrameParameters, documentAutoCaptureHints: [DocumentAutoCaptureHintWrapper]) {
        print("Detected Document - frameParameters: \(frameParameters)")
    }

    func documentSourceNotAuthorized(_ controller: DocumentCaptureViewController) {
        print(#function)
    }

    func documentCaptureWillAppear(_ controller: DocumentCaptureViewController) {
        controller.start()
    }
}

After#

extension DemoViewController: DocumentAutoCaptureViewControllerDelegate {

    func documentAutoCaptureViewController(_ viewController: DocumentAutoCaptureViewController, captured result: DocumentAutoCaptureResult) {
        print("Captured Document:", result.documentDetectorResult.confidence)
        print("Image:", result.bgraRawImage.size.width, result.bgraRawImage.size.height)

        resultTextLabel.text = result.machineReadableZone?.description ?? ""
        photoImageView.image = UIImage(cgImage: CGImageFactory.create(bgraRawImage: result.bgraRawImage))
        navigationController?.popViewController(animated: true)
    }

    func documentSourceNotAuthorized(_ controller: DocumentAutoCaptureViewController) {
        print(#function)
    }

    func documentAutoCaptureViewControllerViewWillAppear(_ viewController: DocumentAutoCaptureViewController) {
        viewController.start()
    }
}

Image Conversion#

New DOT Document API uses BgraRawImage class as an image representation.

Create BgraRawImage from CGImage:

let bgraRawImage = BgraRawImageFactory.create(cgImage: cgImage)

Create CGImage from BgraRawImage:

let cgImage = CGImageFactory.create(bgraRawImage: self)