Skip to main content

SDK Features | MAUI Document Scanner

SDK Features Overview

Barcode Scanner

The Scanbot SDK comes with an essential camera view, additional views for extending the camera functionality and a detector classes that handle all the camera and detection implementation details for you.

It provides a UI for document scanning guidance as well as a UI and functionality for manual and automatic shutter release on barcode detection.

Scanning Single Barcodes

Launches the barcode scanner. The scanned code will be returned asynchronously.

Show in example app

alt

var config = new BarcodeScannerConfiguration();
var result = await ScanbotSDK.ReadyToUseUIService.LaunchBarcodeScannerAsync(config);
if (result.Status == OperationResult.Ok)
{
// result.Text contains the decoded value of the scanned barcode
}

Batch Barcode Scanner

Launches the batch barcode scanner. The scanned codes will be returned asynchronously.

Show in example app

var config = new BatchBarcodeScannerConfiguration();
var result = await ScanbotSDK.ReadyToUseUIService.LaunchBatchBarcodeScannerAsync(config);
if (result.Status == OperationResult.Ok)
{
// result.Barcodes contains the detected barcodes' information
}

Barcode Detection on Image

The Scanbot SDK detects barcodes from an existing image (ImageSource).

List<Barcode> result = await ScanbotSDK.SDKService.DetectBarcodesFrom(image);

Document Scanner

The main entry point of the ScanbotSDK MAUI wrapper is the DocumentSDK.MAUI.ScanbotSDK class:

  • ScanbotSDK.SDKService - functions for raw image processing as well as page processing.
  • ScanbotSDK.ReadyToUseUIService - functions that launch the Scanbot SDK ready-to-use UI screens for document scanning, cropping, MRZ scanning, barcode scanning, etc.

Document Scanner

Launches the Document Scanner. The scanned pages will be returned asynchronously.

Show in example app

alt

var config = new DocumentScannerConfiguration();
var result = await ScanbotSDK.SDKService.LaunchDocumentScannerAsync(config);
if (result.Status == OperationResult.Ok)
{
// result.Pages contains the scanned pages
}

Image Cropping

Launches the Cropping UI on the given page. A page object can be initially created using the Document Scanner or ScanbotSDK.SDKService.CreateScannedPageAsync().

Show in example app

alt


var page = ...
var config = new CroppingScreenConfiguration();
var result = await ScanbotSDK.ReadyToUseUIService.LaunchCroppingScreenAsync(page, config);
if (result.Status == OperationResult.Ok)
{
// `page` has been updated
}

Page Model

The Scanbot SDK provides a ready-to-use UI for document scanning and cropping. Both components use the notion of a 'page' as a data model for the scanning and cropping activities. A page is represented by DocumentSDK.MAUI.Services.IScannedPageService.

Pages are stored in an internal page file storage, where the pageId serves as a name prefix for the stored image files. Operations that modify pages work in-place. That is, for example, RotatePage() overwrites the page's image files with their rotated versions. This behavior differs from the behavior of raw image functions like RotateImage() which always create a new file.

IScannedPageService implements INotifyPropertyChanged and can be directly used as a BindingContext.

Blur Detection

Estimates image blurriness. Less is sharper, more is blurred.

var image = CurrentPage.Document;
var blur = await ScanbotSDK.SDKService.EstimateBlurriness(image);

In broad terms, consider blur values as follows:

  • 0.0-0.3: This image is not blurry at all
  • 0.3-0.6: Somewhat blurry, should be okay
  • 0.6-1.0: I am skeptical of the usefulness of the image

However, this is not as easy as it seems. If a scanned document has a predominantly white background, it will be considered a very blurred image.

Creating PDF Documents

Task<Uri> CreatePdfAsync(IEnumerable<ImageSource> images, PDFPageSize pageSize)

Creates a PDF file out of one or more ImageSource objects. All images must be instances of FileImageSource. These are images created with ImageSource.FromFile and images stored as files by the Scanbot MAUI SDK. If more than one image is given, the function creates a multi-page PDF. The generated PDF file will be deleted when calling CleanUp. If you want to keep the file, move it to a folder that you have control over.

Typically, the final hi-res document image files of the scanned Pages (Page.Document) are used to generate the PDF file.

// list of scanned pages
List<IScannedPageService> ScannedPages = ...

// collect the document images of scanned pages
List<ImageSource> DocumentImages = new List<ImageSource>();
foreach (var page in ScannedPages)
{
DocumentImages.Add(page.Document);
}

// and create the PDF file from the document images
var pdfFileUri = await ScanbotSDK.SDKService.CreatePdfAsync(DocumentImages, PDFPageSize.FixedA4);

Input args:

  • images: Input images as a list of ImageSources in proper order (image element 1 => page 1, etc).
  • pageSize: PDFPageSize enum value to specify the output page size. See below.

Result:

  • pdfFileUri: File URI of the PDF result file ('file:///...').

Supported PDF Page Sizes

  • A4: The page has the aspect ratio of the image, but is fitted into A4 size. Whether portrait or landscape depends on the image's aspect ratio.
  • FixedA4: The page has A4 size. The image is fitted and centered within the page. Whether portrait or landscape depends on the image's aspect ratio.
  • USLetter: The page has the aspect ratio of the image, but is fitted into US letter size. Whether portrait or landscape depends on the image's aspect ratio.
  • FixedUsLetter: The page has US letter size. The image is fitted and centered within the page. Whether portrait or landscape depends on the image's aspect ratio.
  • Auto: For each page the best matching format (A4 or US letter) is used. Whether portrait or landscape depends on the image's aspect ratio.
  • AutoLocale: Each page of the result PDF will be of US letter or A4 size depending on the current locale. Whether portrait or landscape depends on the image's aspect ratio.
  • FromImage: Each page is as large as its image at 72 dpi.
PDF with OCR

If you need to generate a searchable PDF file with a text layer, please refer to the "OCR" section.

Creating TIFF Documents

Task<Uri> WriteTiffAsync(IEnumerable<ImageSource> images, TiffOptions options = null)

Writes the given images into a TIFF file. All images must be instances of FileImageSource. These are images created with ImageSource.FromFile and images stored as files by the Scanbot MAUI SDK. If more than one image is given, the function creates a multi-page TIFF. The function can optionally create a 1-bit encoded (binarized) TIFF. The generated TIFF file will be deleted when calling CleanUp. If you want to keep the file, move it to a folder that you have control over.

Typically, the final hi-res document image files of the scanned Pages (Page.Document) are used to generate the TIFF file.

// list of scanned pages
List<IScannedPageService> ScannedPages = ...

// collect the document images of scanned pages
List<ImageSource> DocumentImages = new List<ImageSource>();
foreach (var page in ScannedPages)
{
DocumentImages.Add(page.Document);
}

// and create a binarized (1-bit encoded) TIFF from the document images
var tiffFileUri = await ScanbotSDK.SDKService.WriteTiffAsync(
DocumentImages,
new TiffOptions { OneBitEncoded = true, Dpi = 300, Compression = TiffCompressionOptions.CompressionCcittT6 }
);

Input args:

  • images: Input images as a list of ImageSources in proper order (image element 1 => page 1, etc).
  • options: optional TiffOptions:
    • OneBitEncoded : Optional boolean flag. If true, the input images will be binarized and the output TIFF file will be saved with one bit per pixel. If false, the input images will be stored as-is. The default value is false.
    • Dpi : Optional integer value for Dots Per Inches. The default value is 200 dpi.
    • Compression : Optional TIFF compression type. The default value depends on the OneBitEncoded flag. CompressionCcittT6 (CCITT Fax 4) is the default value for binarized (OneBitEncoded=true) images. For color images (OneBitEncoded=false) the default value is CompressionAdobeDeflate (ZIP).

Result:

  • tiffFileUri: File URI of the TIFF result file ('file:///...').

Supported TIFF Compression Types

  • CompressionNone : No compression.
  • CompressionCcittT6 : "CCITT Fax 4" compression type. Most common and recommended type for binarized (1-bit) black and white images to achieve a small TIFF file size.
  • CompressionAdobeDeflate : "ZIP" compression type. Most common type for color images.
  • CompressionCcittrle
  • CompressionCcittfax3
  • CompressionCcittT4
  • CompressionCcittfax4
  • CompressionCcittrlew
  • CompressionLzw
  • CompressionPackbits
  • CompressionDeflate
caution

Please note that the following compression types are only compatible for binarized images (1-bit encoded black & white images): CompressionCcittrle, CompressionCcittfax3, CompressionCcittT4, CompressionCcittfax4, CompressionCcittT6, CompressionCcittrlew.

MRZ Scanner

Launches the MRZ scanner. The scanned data will be returned asynchronously.

Show in example app

alt

var config = new MrzScannerConfiguration();
config.FinderWidthRelativeToDeviceWidth = 0.9;
config.FinderHeightRelativeToDeviceWidth = 0.18;
var result = await ScanbotSDK.ReadyToUseUIService.LaunchMrzScannerAsync(config);
if (result.Status == OperationResult.Ok)
{
// result.Fields contain the recognized MRZ fields
}

EHIC Scanner

Launches the EHIC Scanner. The scanned EHIC card will be returned asynchronously.

Show in example app

The European Health Insurance Card Scanner is based on the OCR feature and thus requires the proper installation of the OCR language files deu.traineddata and eng.traineddata (aka. blob files). For more details on how to set up OCR language files please refer to the OCR section.

var config = new HealthInsuranceCardConfiguration
{
FlashEnabled = true,
};
var result = await ScanbotSDK.ReadyToUseUIService.LaunchHealthInsuranceCardScannerAsync(config);
if (result.Status == OperationResult.Ok)
{
// result contains the EHIC card that has been recognized
}

Generic Document Scanner

The Scanbot SDK comes with an essential camera view, additional views for extending the camera functionality and a detector classes that handle all the camera and detection implementation details for you.

The Scanbot SDK provides the ability to detect various types of documents in an image, crop them and recognize data fields 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

Show in example app

The Generic Document Recognizer is based on the OCR feature and thus requires the proper installation of the OCR language files deu.traineddata and eng.traineddata (aka. blob files). For more details on how to set up OCR language files please refer to the OCR section.

var config = new GenericDocumentRecognizerConfiguration
{
DocumentType = GenericDocumentType.DeIdCard,
TopBarButtonsColor = Color.Green,
// Further customization parameters...
};
var result = await ScanbotSDK.ReadyToUseUIService.LaunchGenericDocumentRecognizerAsync(configuration);
if (result.Status == OperationResult.Ok)
{
// result contains the documents that have been recognized
}

Check Scanner

Launches the Check Recognizer UI. The scanned check will be returned asynchronously.

Show in example app

var configuration = new CheckRecognizerConfiguration
{
AcceptedCheckStandards = new List<CheckStandard>() {
CheckStandard.USA,
CheckStandard.AUS,
CheckStandard.IND,
CheckStandard.FRA,
CheckStandard.KWT,
}
};

var result = await ScanbotSDK.ReadyToUseUIService.LaunchCheckRecognizerAsync(configuration);
if (result.Status == OperationResult.Ok)
{
// String representation example
var message = result
.Join("\n", result.Document.Fields
.Where((f) => f != null && f.Type != null && f.Type.Name != null && f.Value != null && f.Value.Text != null)
.Select((f) => string.Format("{0}: {1}", f.Type.Name, f.Value.Text))

Console.WriteLine("Result: " + message);
}

Optical Character Recognition

The Scanbot SDK provides simple and convenient APIs to run Optical Character Recognition (OCR) on images.

As result you can get:

  • a searchable PDF document with the recognized text layer (aka. sandwiched PDF document)
  • recognized text as plain text
  • bounding boxes of all recognized paragraphs, lines and words
  • text results and confidence values for each bounding box

The Scanbot OCR feature is based on the Tesseract OCR engine with some modifications and enhancements. The OCR engine supports a wide variety of languages. For each desired language a corresponding OCR training data file (.traineddata) must be provided. Furthermore, the special data file osd.traineddata is required (used for orientation and script detection). The Scanbot SDK package contains no language data files to keep the SDK small in size. You have to download and include the desired language files in your app.

Preconditions to achieve a good OCR result

Conditions while scanning

A perfect document for OCR is flat, straight, in the highest possible resolution and does not contain large shadows, folds, or any other objects that could distract the recognizer. Our UI and algorithms do their best to help you meet these requirements. But as in photography, you can never fully get the image information back that was lost during the shot.

Languages

You can use multiple languages for OCR. But since the recognition of characters and words is a very complicated process, increasing the number of languages lowers the overall precision. With more languages, there are more results where the detected word could match. We suggest using as few languages as possible. Make sure that the language you are trying to detect is supported by the SDK and added to the project.

Size and position

Put the document on a flat surface. Take the photo from straight above in parallel to the document to make sure that the perspective correction does not need to be applied much. The document should fill most of the camera frame while still showing all of the text that needs to be recognized. This results in more pixels for each character that needs to be detected and hence, more detail. Skewed pages decrease the recognition quality.

Light and shadows

More ambient light is always better. The camera takes the shot at a lower ISO value, which results in less grainy photos. You should make sure that there are no visible shadows. If you have large shadows, it is better to take the shot at an angle instead. We also do not recommend using the flashlight - from this low distance it creates a light spot at the center of the document which decreases the recognition quality.

Focus

The document needs to be properly focused so that the characters are sharp and clear. The autofocus of the camera works well if you meet the minimum required distance for the lens to be able to focus. This usually starts at 5-10cm.

Typefaces

The OCR trained data is optimized for common serif and sans-serif font types. Decorative or script fonts drastically decrease the quality of recognition.

Download and Provide OCR Language Files

You can find a list of all supported OCR languages and download links on this Tesseract page.

⚠️️️ Please choose and download the proper version of the language data files:

Download the desired language files as well as the osd.traineddata file and place them in the Assets sub-folder SBSDKLanguageData/ of your Android app or in the Resources sub-folder ScanbotSDKOCRData.bundle/ of your iOS app.

Example for Android:

Droid/Assets/SBSDKLanguageData/eng.traineddata  // english language file
Droid/Assets/SBSDKLanguageData/deu.traineddata // german language file
Droid/Assets/SBSDKLanguageData/osd.traineddata // required special data file

Example for iOS:

iOS/Resources/ScanbotSDKOCRData.bundle/eng.traineddata  // english language file
iOS/Resources/ScanbotSDKOCRData.bundle/deu.traineddata // german language file
iOS/Resources/ScanbotSDKOCRData.bundle/osd.traineddata // required special data file

OCR API

IEnumerable<ImageSource> documentImageSources = ...

var languages = new[] { "en" }; // or specify more languages like { "en", "de", ... }
var result = await ScanbotSDK.SDKService.PerformOcrAsync(documentImageSources, languages);

// See the recognized plain text of all images/pages via result.Text,
// or get more details of each image/page via result.Pages:
foreach (var ocrPage in result.Pages)
{
//ocrPage.Paragraphs ...
//ocrPage.Lines ...
//ocrPage.Words ...
// example for words:
foreach (var wordBlock in ocrPage.Words)
{
//wordBlock.Text ...
//wordBlock.BoundingBox.X ...
//wordBlock.BoundingBox.Y ...
//wordBlock.BoundingBox.Width ...
//wordBlock.BoundingBox.Height ...
}
}

Storage and Encryption

Scanbot SDK provides the ability to store the generated image files (JPG, PNG) and PDF files encrypted. This feature provides an additional level of security to the default secure storage locations of the native SDKs.

By default the file encryption is disabled. If you wish to enable encryption, you have to pass the following config parameters on SDK initialization:

new SBSDKConfiguration
{
Encryption = new SBSDKEncryption
{
Mode = EncryptionMode.AES256,
Password = "SomeSecretPa$$w0rdForFileEncryption"
}
};

By activating the storage encryption the native Scanbot SDKs will use the built-in AES 128 or AES 256 encryption. All generated image files (JPG, PNG) including the preview image files, as well as the exported PDF files will be encrypted in memory and stored as encrypted data files on the flash storage of the device.

The Scanbot SDK derives the AES key from the given password, an internal salt value, and the internal number of iterations using the PBKDF2 function.

When applying image operations like cropping, rotation or image filters, Scanbot SDK will decrypt the image file in memory, apply the changes, encrypt and store it again.

If encryption is enabled, IScannedPageService properties Document, Original, DocumentPreview, OriginalPreview and AvailablePreview will be encrypted.

You should still pass these images to all ScanbotSDK functions, as they deal with encryption internally, and the paths to files are valid, however, you cannot display encrypted ImageSource objects.

You need to use the await DecryptedOriginal() or await DecryptedDocument() methods of IScannedPageService to display images in your app.

Persistence of Page Objects

Scanbot SDK does not persist page objects, only the image files (.jpg or .png). The management of page objects and the persistence of the page metadata is left to the app. Depending on the use case, it may be necessary to persist the data of the page objects in the app (e.g. as JSON in a local SQLite database). If this is the case, the following must be considered.

The Page objects contain absolute paths to the image files, i.e. the Document image of a ScannedPage might be located at:

file:///var/mobile/Containers/Data/Application/54286F82-A8F7-4850-A684-8D3487726A4D/Library/Application%20Support/net.doo.ScanbotSDK/SBSDK_ImageStorage_Default/PageFileStorage/JPEG/documents/60426F47-4119-48F8-ADA9-F7E60D583CB4_preview.jpg

The page image files are stored in corresponding storage locations. By default, the Scanbot SDK Android uses the internal files directory of the app, whereas the Scanbot SDK iOS uses the "Application Support" folder. Those storage folders are secure and are not affected by an app update.

However, on iOS, the absolute file path of the "Application Support" folder is not reliable. For each fresh install of an app, a new UUID is generated, in the following format: /var/mobile/Containers/Data/Application/{UUID}. That is where application data is stored. When updating the app, the uuid may change. For example:

Before an app update:

file:///var/mobile/Containers/Data/Application/54286F82-A8F7-4850-A684-8D3487726A4D/Library/Application%20Support/net.doo.ScanbotSDK/SBSDK_ImageStorage_Default/PageFileStorage/JPEG/documents/60426F47-4119-48F8-ADA9-F7E60D583CB4.jpg

After the app update:

file:///var/mobile/Containers/Data/Application/C9181555-252A-4665-892F-793008ED0EDD/Library/Application%20Support/net.doo.ScanbotSDK/SBSDK_ImageStorage_Default/PageFileStorage/JPEG/documents/60426F47-4119-48F8-ADA9-F7E60D583CB4.jpg

Please note that the actual image files are still there, only the absolute file paths change.

To get to the new absolute paths, the API method RefreshImageUris(IEnumerable<IScannedPageService>) has been introduced in the ScanbotSDK.MAUI package. Please use this method to refresh all image file URIs from affected pages:

List<IScannedPageService> loadedPages = // load pages from database
var refreshedPages = await ScanbotSDK.SDKService.RefreshImageUris(loadedPages);

It is highly recommended to use this method whenever you have to (re-)load Page objects from the database of your app, regardless of whether there was an app update or not.

What do you think of this documentation?