SDK Features | MAUI Document Scanner
SDK Feature 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.
loading...
Batch Barcode Scanner
Launches the batch barcode scanner. The scanned codes will be returned asynchronously.
loading...
Barcode Detection on Image
The Scanbot SDK detects barcodes from an existing image:
loading...
Document Scanner
The main entry point of the ScanbotSDK MAUI wrapper is the ScanbotSDK.MAUI.ScanbotSDK class, which contains:
SDKService- functions for raw image processing as well as page processing.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.
loading...
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().
loading...
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 ScanbotSDK.MAUI.Services.IScannedPage.
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.
IScannedPage implements INotifyPropertyChanged and can be directly used as a BindingContext.
Creating PDF Documents
Task<Uri> CreatePdfAsync(IEnumerable<FileImageSource> files, PDFPageSize pageSize = PDFPageSize.Custom, PDFPageOrientation pdfPageOrientation = PDFPageOrientation.Auto, OcrConfig configuration = null);
Creates a PDF file out of one or more FileImageSource 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.
loading...
Input args:
files: Input images as a list ofFileImageSources in proper order (image element 1 => page 1, etc).configuration:PDFConfigurationobject which contains information about the PDF and its metadata. Please refer to the detailed points for this object below.
Result:
pdfFileUri: FileUriof the PDF result file ('file:///...').
Supported PDF Page Sizes
Letter: The page has US letter size: 8.5x11 inches. The image is fitted and centered within the page.Legal: The page has US legal size: 8.5x14 inches. The image is fitted and centered within the page.A3: The page has A3 size: 297x420 mm. The image is fitted and centered within the page.A4: The page has the aspect ratio of the image, but is fitted into A4 size. Whether portrait or landscape depends on the images aspect ratio.A5: The page has A5 size: 148x210 mm. The image is fitted and centered within the page.B4: The page has B4 size: 250x353 mm. The image is fitted and centered within the page.B5: The page has B5 size: 176x250 mm. The image is fitted and centered within the page.Executive: The page has US executive size: 7.25x10.5 inches. The image is fitted and centered within the page.US4x6: The page has US 4x6 size: 4x6 inches. The image is fitted and centered within the page.US4x8: The page has US 4x8 size: 4x8 inches. The image is fitted and centered within the page.US5x7: The page has US 5x7 size: 4x6 inches. The image is fitted and centered within the page.Comm10: The page has COMM10 size: 4.125x9.5 inches. The image is fitted and centered within the page.Custom: Each page is as large as its image at 72 dpi.
Supported Page Orientations
AutoPortraitLandscape
PdfAttributes
This objects allows the user to set the below metadata values for the PDF.
AuthorCreatorTitleSubjectKeywords
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<FileImageSource> files, 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.
loading...
Input args:
images: Input images as a list ofFileImageSources in proper order (image element 1 => page 1, etc).options: optionalTiffOptions:OneBitEncoded: Optional boolean flag. Iftrue, the input images will be binarized and the output TIFF file will be saved with one bit per pixel. Iffalse, the input images will be stored as-is. The default value is false.Dpi: Optional integer value for Dots Per Inches. The default value is200dpi.Compression: Optional TIFF compression type. The default value depends on theOneBitEncodedflag.CompressionCcittT6(CCITT Fax 4) is the default value for binarized (OneBitEncoded=true) images. For color images (OneBitEncoded=false) the default value isCompressionAdobeDeflate(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.CompressionCcittrleCompressionCcittfax3CompressionCcittT4CompressionCcittfax4CompressionCcittrlewCompressionLzwCompressionPackbitsCompressionDeflate
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.
loading...
EHIC Scanner
Launches the EHIC Scanner. The scanned EHIC card will be returned asynchronously.
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.
loading...
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
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.
loading...
Check Scanner
Launches the Check Recognizer UI. The scanned check will be returned asynchronously.
loading...
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 comes with two OCR engines: legacy and ML. The legacy engine is based on the Tesseract OCR engine with some modifications and enhancements. The ML (machine learning based) engine was added later. It is much faster and more accurate, but it only supports languages with latin letters. Our recommendation is to use the ML engine whenever possible and use the legacy engine only if you want to recognize text from non-latin languages like Arabian, Japanese, Chinese, Russian, Greek, Korean etc.
When using the legacy OCR engine for each desired OCR 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.
The newer ML engine does not require any language training data!
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:
- For the latest version of ScanbotSDK.MAUI OR ScanbotSDK.NET package -
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.
Folder path for Android:
$ProjectRootFolder/Platforms/Android/Assets/SBSDKLanguageData/eng.traineddata // english language file
$ProjectRootFolder/Platforms/Android/Assets/SBSDKLanguageData/deu.traineddata // german language file
$ProjectRootFolder/Platforms/Android/Assets/SBSDKLanguageData/osd.traineddata // required special data file
Folder path for iOS:
$ProjectRootFolder/Resources/ScanbotSDKOCRData.bundle/eng.traineddata // english language file
$ProjectRootFolder/Resources/ScanbotSDKOCRData.bundle/deu.traineddata // german language file
$ProjectRootFolder/Resources/ScanbotSDKOCRData.bundle/osd.traineddata // required special data file
OCR API
loading...
Creating Sandwich PDF Document
This functionality allows the user to create a Sandwich PDF document. It creates a PDF document along with performing Optical Character Recognition (OCR).
Please refer to the code sample below to create a Sandwich PDF.
loading...
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:
loading...
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, IScannedPage 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 IScannedPage 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<IScannedPage>) has been introduced in the ScanbotSDK.MAUI package. Please use this method to refresh all image file URIs from affected pages:
List<IScannedPage> 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?
What can we do to improve it? Please be as detailed as you like.