Filters and Image Processing

See SBSDKImageProcessor.

Digital image processing is a core part of the Scanbot SDK. Basically, there are three operations on images:

• Rotation
• Image filtering
• Image warping (perspective correction and cropping) into a 4-sided polygon

Supported parametric image filters

• SBSDKColorDocumentFilter - Color document filter. This filter is a good starting point for most use cases.
• SBSDKScanbotBinarizationFilter - Automatic binarization filter. This filter is a good starting point for most use cases. It has SBSDKOutputMode parameter which can be set to binary or antialiased.
• SBSDKCustomBinarizationFilter - Customizable binarization filter. It has a few presets for specific use cases:
  • SBSDKBinarizationFilterPreset.preset1 - Usually performs well if there is no shadow.
  • SBSDKBinarizationFilterPreset.preset2, SBSDKBinarizationFilterPreset.preset3, SBSDKBinarizationFilterPreset.preset4 - Usually performs well even if there are shadows.
• SBSDKBrightnessFilter - Brightness adjustment filter.
• SBSDKContrastFilter - Contrast adjustment filter.
• SBSDKGrayscaleFilter - Converts color images to grayscale, optionally applying auto-contrast.
• SBSDKWhiteBlackPointFilter - Maps image value channel so that all the pixels darker than the black point are set to 0, all the pixels brighter than the white point are set to 255, and the pixels in between are linearly scaled.
• SBSDKLegacyFilter - A filter that applies a legacy filter to the image. This filter is used for compatibility with older versions of the Scanbot SDK. It takes one of the old filter types as a parameter:
  • SBSDKImageFilterType.none - Do not apply an image filter, keep the original colors.
  • SBSDKImageFilterType.color - Optimizes the colors, contrast and brightness.
  • SBSDKImageFilterType.gray - Grayscale filter.
  • SBSDKImageFilterType.binarized - Standard binarization filter with contrast optimization. Creates an 8-bit grayscale image with mostly black or white pixels.
  • SBSDKImageFilterType.colorDocument - MagicColor filter. Fixes the white-balance and cleans up the background.
  • SBSDKImageFilterType.pureBinarized - A filter for binarizing an image. Creates an image with pixel values set to either pure black or pure white.
  • SBSDKImageFilterType.blackAndWhite - Black and white filter with background cleaning. Creates an 8-bit grayscale image with mostly black or white pixels.
  • SBSDKImageFilterType.backgroundClean - Cleans up the background and tries to preserve photos within the image.
  • SBSDKImageFilterType.otsuBinarization - A filter for black and white conversion using OTSU binarization.
  • SBSDKImageFilterType.deepBinarization - A filter for black and white conversion primary used for low-contrast documents.
  • SBSDKImageFilterType.edgeHighlight - A filter that enhances edges in low-contrast documents.
  • SBSDKImageFilterType.lowLightBinarization - Binarization filter primarily intended to use on low-contrast documents with hard shadows.
  • SBSDKImageFilterType.lowLightBinarization2 - Binarization filter primarily intended to use on low-contrast documents with hard shadows.
  • SBSDKImageFilterType.sensitiveBinarization - Binarization filter for poor quality printed papers.

Example code for rotating, resizing and applying filters

Swift

// Create an instance of an input image.
guard let inputImage = UIImage(named: "documentImage") else { return }
        
// Create an instance of `SBSDKImageProcessor` passing the input image to the initializer.
let processor = SBSDKImageProcessor(image: inputImage)
        
// Perform operations like rotating, resizing and applying filters to the image.
// Rotate the image.
processor.rotate(.clockwise90)
        
// Resize the image.
processor.resize(size: 700)
        
// Create the instances of the filters you want to apply.
let filter1 = SBSDKScanbotBinarizationFilter(outputMode: .antialiased)
let filter2 = SBSDKBrightnessFilter(brightness: 0.4)
        
// Apply the filters.
processor.applyFilters([filter1, filter2])
        
// Retrieve the processed image.
let processedImage = processor.processedImage

Objective-C

// Create an instance of an input image.
UIImage *inputImage = [UIImage imageNamed:@"documentImage"];

// Create an instance of `SBSDKImageProcessor` passing the input image to the initializer.
SBSDKImageProcessor *processor = [[SBSDKImageProcessor alloc] initWithImage:inputImage];
    
// Perform operations like rotating, resizing and applying filters to the image.
// Rotate the image.
[processor rotate:SBSDKImageRotationClockwise90];
    
// Resize the image.
[processor resize:700];
    
// Create an instance of the filter you want to apply.
SBSDKScanbotBinarizationFilter *filter = [[SBSDKScanbotBinarizationFilter alloc]
                                          initWithOutputMode:SBSDKOutputModeAntialiased];
    
// Apply the filter.
[processor applyFilter:filter];
    
// Retrieve the processed image.
UIImage *processedImage = processor.processedImage;

Detecting and applying a polygon to an image

Swift

// Create an instance of an input image.
guard let inputImage = UIImage(named: "documentImage") else { return }

// Create a document detector.
let detector = SBSDKDocumentDetector()

// Let the document detector run on the input image.
let result = detector.detectDocumentPolygon(on: inputImage,
                                            visibleImageRect: .zero,
                                            smoothingEnabled: false,
                                            useLiveDetectionParameters: false)

// Check the result and retrieve the detected polygon.
if result?.status == .ok, let polygon = result?.polygon {

    // If the result is an acceptable polygon, we warp the image into the polygon.
    let processor = SBSDKImageProcessor(image: inputImage)
    
    // Crop the image using the polygon.
    processor.crop(polygon: polygon)
    
    // Retrieve the processed image.
    let processedImage = processor.processedImage
    
} else {
    
    // No acceptable polygon found.
}

Objective-C

// Create an instance of an input image.
UIImage *inputImage = [UIImage imageNamed:@"documentImage"];

// Create a document detector.
SBSDKDocumentDetector *detector = [[SBSDKDocumentDetector alloc] init];

// Let the document detector run on the input image.
SBSDKDocumentDetectorResult *result = [detector detectDocumentPolygonOnImage:inputImage
                                                            visibleImageRect:CGRectZero
                                                            smoothingEnabled:NO
                                                    useLiveDetectionParameters:NO];

// Check the result and retrieve the detected polygon.
if (result.status == SBSDKDocumentDetectionStatusOk && result.polygon != nil)  {
    
    // If the result is an acceptable polygon, we warp the image into the polygon.
    SBSDKImageProcessor *processor = [[SBSDKImageProcessor alloc] initWithImage:inputImage];
    
    // Crop the image using the polygon.
    [processor crop:result.polygon];
    
    // Retrieve the processed image.
    UIImage *processedImage = processor.processedImage;
    
} else {
    
    // No acceptable polygon found.
}

Page Processing

The Scanbot SDK provides two abstractions to incapsulate scanned documents.

SBSDKDocumentPage - This class represents a scanned document page. It contains all the needed information about the scanned page and gives you the ability to manage the scanned image in a variety of ways.

SBSDKDocument - This class represents a thread-safe container for SBSDKDocumentPage instances. It gives the ability to add, remove and replace pages in an array-like fashion.

Both these classes are widely used in all Ready-to-use UI components (more about RTU UI).

Examples of some basic operations on SBSDKDocumentPage and SBSDKDocument

Swift

// For this example we're going to create a mock scanned document image.
guard let documentImage = UIImage(named: "documentImage") else { return }

// Create a page with a UIImage instance.
let page = SBSDKDocumentPage(image: documentImage, polygon: nil, filter: .none)

// Return the result of the detected document on an image.
let result = page.detectDocument(applyPolygonIfOkay: true)

// Rotate the image 180 degrees clockwise. Negative values will rotate the image counter-clockwise.
page.rotateClockwise(2)

// Return the detected document preview image.
let previewImage = page.documentPreviewImage

// Return the url of the original image.
let originalImageURL = page.originalImageURL

// Create an empty document instance.
let document = SBSDKDocument()

// Add the page to the document.
document.add(page)

// Replace the first page of the document with the new page.
document.replacePage(at: 0, with: page)

// Remove the first page from the document.
document.removePage(at: 0)

// Find the index of the page by its identifier.
let index = document.indexOfPage(withPageFileID: page.pageFileUUID)

Objective-C

// For this example we're going to create a mock scanned document image.
UIImage *documentImage = [UIImage imageNamed:@"documentImage"];

// Create a page with a UIImage instance.
SBSDKDocumentPage *page = [[SBSDKDocumentPage alloc] initWithImage:documentImage
                                                            polygon:nil
                                                            filter:SBSDKImageFilterTypeNone];

// Return the result of the detected document on an image.
SBSDKDocumentDetectorResult *result = [page detectDocumentAndApplyPolygonIfOkay:TRUE];

// Rotate the image 180 degrees clockwise. Negative values will rotate the image counter-clockwise.
[page rotateClockwise:2];

// Return the detected document preview image.
UIImage *previewImage = [page documentPreviewImage];

// Return the url of the original image.
NSURL *originalImageURL = [page originalImageURL];

// Create an empty document instance.
SBSDKDocument *document = [[SBSDKDocument alloc] init];

// Add the page to the document.
[document addPage:page];

// Replace the first page of the document with the new page.
[document replacePageAtIndex:0 withPage:page];

// Remove the first page from the document.
[document removePageAtIndex:0];

// Find the index of the page by its identifier.
NSInteger index = [document indexOfPageWithPageFileID:page.pageFileUUID];

Want to scan longer than one minute?

Generate your free "no-strings-attached" Trial License and properly test the Scanbot SDK.

Get your free Trial License

What do you think of this documentation?

What can we do to improve it? Please be as detailed as you like.

---