How to detect blurry scans and evaluate the readability of a document with the Genius Scan SDK

The Genius Scan SDK helps acquire high-quality documents from mobile devices. Alongside its advanced image processing filters, the SDK includes a readability detection feature that evaluates the clarity of a document.

This feature can detect various types of blur:

• Focus blur: when the camera fails to focus properly, or part of the document is out of focus.
• Motion blur: when the photo is taken while the device is moving.

Readability detection is simple to integrate, and we strongly recommend enabling it in your project. It outperforms traditional blur detection techniques because it’s able to detect various types of blur or partially blurry documents. The detection has been specifically tuned for textual documents, and will not work optimally for documents with little text. It may work less effectively for text on textured background.

You can use it in two main ways:

• Simple Integration (with the Scan Flow): Define a required readability level. If the scanned document doesn’t meet this level, the user is prompted to retry.
• Custom Integration: Request the readability score of any scan yourself. Based on the result, you can notify the user, or enforce rescanning if the document quality is insufficient.

This guide focuses on the Simple Integration method.

Getting started

Add the Genius Scan SDK as a dependency to your project by following the section Integrating the framework from the Getting Started guide.

Scan Flow

To enable readability detection in the scan flow, set configuration.requiredReadabilityLevel to a value above .lowest. For example, .medium ensures documents below this quality trigger a prompt.

Note: Don’t set configuration.skipPostProcessingScreen = true, because the prompt is displayed on the post-processing screen.

let configuration = GSKScanFlowConfiguration()
configuration.requiredReadabilityLevel = .highest

Readability levels

Readability isn’t binary. Documents can fall anywhere on a quality spectrum. The Genius Scan SDK defines five readability levels which corresponds to the likelihood for a scan to be legible:

• lowest: Scan with almost no chance of being readable
• low: Scan with very little chance of being readable, even though it’s not impossible
• medium: Scan with little chance of being entirely readable, even though it’s possible
• high: Scan with high chance of being readable, even though it’s not guaranteed
• highest: Scan with very high chance of being readable

Since the Scan Flow shows a warning in case the required readability isn’t met, this will never be blocking for the user. It’s up to you if you want to be more conservative or aggressive in showing this warning.

Start the scan flow with the above configuration

You can now start the scan flow.

Note: The Genius Scan SDK offers multiple convenient ways of starting the scan flow, in particular from UIKit view controllers or from SwiftUI views.

// Keep a strong reference on ScanFlow
let scanFlow = GSKScanFlow(configuration: configuration)

do {
    let result = try await scanFlow.resultByStarting(fromViewController: viewController)
    handleResult(result)
} catch {
    handleError()
}

Handle the success

We can now write the handleResult method.

func handleResult(_ result: GSKScanFlowResult) {
    // We only consider the first scan since we are in single-page mode
    guard let scan = result.scans.first else {
        print("Unexpected error")
        return
    }

    let imagePath = results.scans.first.enhancedFilePath
    // Do something with this image…
}

Error handling

It’s important to handle the error as well, there are two important cases:

• The scan flow is cancelled by the user. A special error is raised so that you can choose how to handle such situations. Maybe you don’t want to perform any action, but you can also show a message to the user.
• The Genius Scan SDK license is expired. This could happen if your license isn’t renewed or if you don’t activate auto-refreshing of the license key. In this case, you may want to show a message or fall back to the regular camera depending on your needs.

func handleError(_ error: Error) {
    if (error as NSError).domain == GSKScanFlowErrorDomain && (error as NSError).code == GSKScanFlowError.userCancellation.rawValue {
        // Do nothing
    } else {
        // Show a UIAlertController with error.localizedDescription
    }
}

Launching the app

Run your application on a physical device (the iOS Simulator doesn’t support camera access). To test readability detection, try scanning:

• in low-light conditions
• while shaking the device

This will help you observe how the SDK reacts to blur and low readability.