Filters and Image Processing | Capacitor Document Scanner

Apply Image Filter

applyImageFilter(args:{
  imageFileUri: string,
  filter: ImageFilterType,
}): Promise<ResultWrapper<ApplyImageFilterResult>>;

Applies an image filter to the given image and returns the filtered image uri. The original image will not be modified.

Returns:

• imageFileUri: The URI of the filtered image

import { ScanbotSDK } from 'capacitor-plugin-scanbot-sdk';

// Always make sure you have a valid license on runtime via ScanbotSDK.getLicenseInfo()
if (!licenseCheckMethod()) { return; }

const result = await ScanbotSDK.applyImageFilter({
  imageFileUri: 'file:///some/image-file.jpg',
  filter: 'PURE_BINARIZED' // See available filters below
});

const filteredImageUri: string = result.imageFileUri;

Apply Image Filter on Page

applyImageFilterOnPage({
  page: Page,
  filter: ImageFilterType,
}): Promise<ResultWrapper<ApplyImageFilterOnPageResult>>;

Applies an image filter to the hi-res document image of a Page (documentImageFileUri) and refreshes the corresponding preview image (documentPreviewImageFileUri). The original, uncropped image of a Page (originalImageFileUri) will not be modified.

import { ScanbotSDK, Page } from 'capacitor-plugin-scanbot-sdk';

// Always make sure you have a valid license on runtime via ScanbotSDK.getLicenseInfo()
if (!licenseCheckMethod()) { return; }

const result = await ScanbotSDK.applyImageFilterOnPage({
  page: this.page,
  filter: 'BINARIZED'
});

// Use the updated page from result
const filteredPage: Page = result;

// Reload the image preview, etc..

Supported Image Filters

Supported image filters:

• COLOR_ENHANCED - Optimizes colors, contrast and brightness.
• GRAYSCALE - Grayscale filter.
• BINARIZED - Standard binarization filter with contrast optimization. Creates an 8-bit grayscale image with mostly black or white pixels.
• COLOR_DOCUMENT - MagicColor filter. Fixes white balance and cleans up the background.
• PURE_BINARIZED - A filter for binarizing an image. Creates an image with pixel values set to either pure black or pure white.
• BACKGROUND_CLEAN - Cleans up the background and tries to preserve photos within the image.
• BLACK_AND_WHITE - Black and white filter with background cleaning. Creates an 8-bit grayscale image with mostly black or white pixels.
• OTSU_BINARIZATION - A filter for black and white conversion using OTSU binarization.
• DEEP_BINARIZATION - A filter for black and white conversion primary used for low-contrast documents.
• EDGE_HIGHLIGHT - A filter that enhances edges in low-contrast documents.
• LOW_LIGHT_BINARIZATION - Binarization filter primarily intended for use on low-contrast documents with heavy shadows.
• LOW_LIGHT_BINARIZATION_2 - Binarization filter primarily intended for use on low-contrast documents with heavy shadows.

Get Filtered Preview Image

getFilteredDocumentPreviewUri(args:{
  page: Page,
  filter: ImageFilterType,
}): Promise<ResultWrapper<GetFilteredDocumentPreviewUriResult>>;

This API method just creates a temporary preview image of the document image of a Page based on the given filter. It does not modify the document image of the Page.

For instance, you can use this method to create previews, so the user can test and see the image filter results without applying the filters to the hi-res document images. If the user has decided on a filter, you can apply it on the actual hi-res document image via applyImageFilterOnPage.

import { ScanbotSDK, Page } from 'capacitor-plugin-scanbot-sdk';

// Always make sure you have a valid license on runtime via ScanbotSDK.getLicenseInfo()
if (!licenseCheckMethod()) { return; }

public filteredPreviewImageUri: string;

const result = await ScanbotSDK.getFilteredDocumentPreviewUri({
    page: this.page,
    filter: 'LOW_LIGHT_BINARIZATION_2' // See available filters above
});

// use the filteredDocumentPreviewUri from result to show a preview image of an image filter
this.filteredPreviewImageUri = result.filteredDocumentPreviewUri;

<ion-img [src]="filteredPreviewImageUri" />

Page Processing

All SDK components (UI and non-UI) which generate or modify scanned documents use the notion of a Page as a data model.

A Page object represents a scanned or imported document page and has the following fields:

export interface Page {
  /** A string identifying the page in the internal page file storage */
  pageId: string;

  /*
   * The page's cropping polygon as calculated by a document detection operation or as set by the cropping UI.
   * Modifying the polygon will change the polygon as shown in the cropping UI but will not automatically
   * re-crop the original image
   */
  polygon: PolygonPoint[];

  /** The document detection result status for the operation that produced the page */
  detectionResult: DetectionStatus;

  /** The image source */
  pageImageSource: PageImageSource;

  /** The Image Filter that was applied on the page image */
  filter: ImageFilterType;

  /*
   * The value that was set for `documentImageSizeLimit`, which limits the
   * maximum size of the document image.
   */
  documentImageSizeLimit?: Size;

  /** File URI of the original image */
  originalImageFileUri: string;

  /** File URI of the cropped document image (if document detection was successful) */
  documentImageFileUri?: string;

  /** File URI of a screen-sized preview of the original image */
  originalPreviewImageFileUri: string;

  /*
   * File URI of a screen-sized preview of the document image (if document
   * detection was successful)
   */
  documentPreviewImageFileUri?: string;
}

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. All URI properties of a page have a ?minihash= query parameter appended to them with the hash of a portion of the image file. Different images will almost always have a different hash and therefore a different URI, which will force the WebView to reload the page's images when changed.

caution

Some file system operations require decoding of the URI before utilization. URI strings are ENCODED by default.

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:

{
  "pageId": "60426F47-4119-48F8-ADA9-F7E60D583CB4",
  "documentPreviewImageFileUri": "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?minihash=a236a8ba5510cd0f4e88bd2045f52c4e",
  "originalImageFileUri": "file:///var/mobile/Containers/Data/Application/54286F82-A8F7-4850-A684-8D3487726A4D/Library/Application%20Support/net.doo.ScanbotSDK/SBSDK_ImageStorage_Default/PageFileStorage/JPEG/originals/60426F47-4119-48F8-ADA9-F7E60D583CB4.jpg?minihash=4e9f0446421343eaaa1e415fdb446a12",
  "originalPreviewImageFileUri": "file:///var/mobile/Containers/Data/Application/54286F82-A8F7-4850-A684-8D3487726A4D/Library/Application%20Support/net.doo.ScanbotSDK/SBSDK_ImageStorage_Default/PageFileStorage/JPEG/originals/60426F47-4119-48F8-ADA9-F7E60D583CB4_preview.jpg?minihash=da888cd42db07e52b15a6ada29a37b63",
  "documentImageFileUri": "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?minihash=f9aab62cc37fec555abe94c83406a1b3",
  ...
}

The page image files are stored in corresponding storage locations - also see the Storage section. 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 the new absolute paths, please use API method refreshImageUris({pages: Page []}) to refresh all image file URIs from affected pages:

import { ScanbotSDK } from 'capacitor-plugin-scanbot-sdk';

// Always make sure you have a valid license on runtime via ScanbotSDK.getLicenseInfo()
if (!licenseCheckMethod()) { return; }

const result = await ScanbotSDK.refreshImageUris({pages: loadedPages});
const refreshedPages = result.pages;

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

Page Operations

Create Page

ScanbotSDK.createPage(args:{
  imageUri: string
}): Promise<ResultWrapper<CreatePageResult>>;

Creates a Page object from an image file (presumably the original image of an uncropped document).

Returns the created page object.

As the page has not been cropped yet, the documentImageFileUri and documentPreviewImageFileUri properties will be empty.

Set Document Image

ScanbotSDK.setDocumentImage(args:{
    // The page to modify
    page: Page,
    // The URI of an image file with which to overwrite the page's document image.
    imageFileUri: string,
}): Promise<ResultWrapper<SetDocumentImageResult>>;

Replaces the document image of a page. The passed image file will be copied into the internal page file storage.

Returns the updated page.

Remove Page

ScanbotSDK.removePage(args:{
  page: Page
}): Promise<ResultWrapper<RemovePageResult>>;

Removes a page with all its files (original image, document image, thumbnails, filtered images, etc) from the internal file storage.

This method does not remove any export files (PDF, TIFF) which were generated based on this page object.

Want to scan longer than one minute?

Generate a free trial license to test the Scanbot SDK thoroughly.

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.

---