Skip to main content

Page Model | Flutter Document Scanner

Page Model​

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 document page and has the following fields:

Page(pageId,
    {detectionStatus,
      documentImageSizeLimit,
      filter,
      polygon,
      originalImageFileUri,
      documentImageFileUri,
      originalPreviewImageFileUri,
      documentPreviewImageFileUri});

The fields are:

  • pageId - a unique, random string (UUID) identifying the page in the internal page file storage.
  • polygon - 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.
  • detectionStatus - the detection status of the document detection operation that produced the page (either the document scanner or detectDocument()).
  • filter - the image filter type which was applied on the document image of this page.
  • documentImageSizeLimit - limits the maximum resolution (width, height) of the document image. If null is passed, this property is effectively ignored. If specified, width and height must be > 0.
  • originalImageFileUri - file URI of the original image.
  • documentImageFileUri - file URI of the cropped document image (if document detection was successful).
  • originalPreviewImageFileUri - file URI of a screen-sized preview of the original image.
  • documentPreviewImageFileUri - file URI of a screen-sized preview of the document image.

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, rotatePageClockwise() overwrites the page's image files with their rotated versions.

Polygon​

The Scanbot SDK polygon is a list with 4 float points (one for each corner). Each point has coordinates in the range [0..1], representing a position relative to the image size. For instance, if a point has the coordinates (0.5, 0.5), it means that it is located exactly in the center of the image.

Example code of a detected polygon as dart result:

var polygon = [
     PolygonPoint(0.046,0.1306),
     PolygonPoint(0.087,0.346),
     PolygonPoint(0.021,0.678),
     PolygonPoint(0.34,0.90),
];

Detection Status values​

ScanbotSdk.DetectionStatus​

  • DetectionStatus.OK - An acceptable polygon was detected.
  • DetectionStatus.OK_BUT_TOO_SMALL - A polygon was detected but was too small.
  • DetectionStatus.OK_BUT_BAD_ANGLES - A polygon was detected but it is distorted too much.
  • DetectionStatus.OK_BUT_BAD_ASPECT_RATIO - A polygon was detected but its aspect ratio is wrong.
  • DetectionStatus.OK_OFF_CENTER - A polygon was detected, but its center is too far away from the image center.
  • DetectionStatus.OK_BARCODE - A barcode was detected.
  • DetectionStatus.ERROR_TOO_DARK - No polygon detected, image too dark.
  • DetectionStatus.ERROR_TOO_NOISY - No polygon detected, image too noisy (background).
  • DetectionStatus.ERROR_NOTHING_DETECTED - No polygon detected.

Supported parametric image filters​

  • ColorDocumentFilter - Color document filter. This filter is a good starting point for most use cases.
  • ScanbotBinarizationFilter - Automatic binarization filter. This filter is a good starting point for most use cases. It has outputMode: OutputMode parameter which can be set to OutputMode.BINARY or OutputMode.ANTIALIASED.
  • CustomBinarizationFilter - Customizable binarization filter. It has a few presets for specific use cases:
    • BinarizationFilterPreset.PRESET_1 - Usually performs well if there is no shadow.
    • BinarizationFilterPreset.PRESET_2, BinarizationFilterPreset.PRESET_3, BinarizationFilterPreset.PRESET_4 - Usually performs well even if there are shadows.
  • BrightnessFilter - Brightness adjustment filter.
  • ContrastFilter - Contrast adjustment filter.
  • GrayscaleFilter - Converts color images to grayscale, optionally applying auto-contrast.
  • WhiteBlackPointFilter - 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.
  • LegacyFilter - 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:
    • ImageFilterType.NONE - Do not apply an image filter, keep the original colors.
    • ImageFilterType.COLOR - Optimizes the colors, contrast and brightness.
    • ImageFilterType.GRAYSCALE - Grayscale filter.
    • ImageFilterType.BINARIZED - Standard binarization filter with contrast optimization. Creates an 8-bit grayscale image with mostly black or white pixels.
    • ImageFilterType.COLOR_DOCUMENT - MagicColor filter. Fixes the white-balance and cleans up the background.
    • ImageFilterType.PURE_BINARIZED - A filter for binarizing an image. Creates an image with pixel values set to either pure black or pure white.
    • ImageFilterType.BLACK_AND_WHITE - Black and white filter with background cleaning. Creates an 8-bit grayscale image with mostly black or white pixels.
    • ImageFilterType.BACKGROUND_CLEAN - Cleans up the background and tries to preserve photos within the image.
    • ImageFilterType.OTSU_BINARIZATION - A filter for black and white conversion using OTSU binarization.
    • ImageFilterType.DEEP_BINARIZATION - A filter for black and white conversion primary used for low-contrast documents.
    • ImageFilterType.EDGE_HIGHLIGHT - A filter that enhances edges in low-contrast documents.
    • ImageFilterType.LOW_LIGHT_BINARIZATION - Binarization filter primarily intended to use on low-contrast documents with hard shadows.
    • ImageFilterType.LOW_LIGHT_BINARIZATION_2 - Binarization filter primarily intended to use on low-contrast documents with hard shadows.
    • ImageFilterType.SENSITIVE_BINARIZATION - Binarization filter for poor quality printed papers. See important info about this type below!

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",
  "filter": "NONE",
  "detectionResult": "OK",
  "polygon": [{"x":0.17427248677248677,"y":0.1212797619047619},{"x":0.8604497354497355,"y":0.13120039682539678},{"x":0.8349867724867724,"y":0.9729662698412699},{"x":0.12202380952380967,"y":0.9471726190476191}],
  "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, on the Android platform, the Scanbot SDK uses the app's internal files directory, whereas on iOS, the Scanbot SDK 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}. This 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 their absolute file paths have changed.

To obtain the new absolute paths, the API method refreshImageUris(pages) has been introduced in the plugin version 2.1.0. Please use this method to refresh all image file URIs for affected pages:

List<Page> loadedPages = ... // load page objects from DB
var refreshedPages = await ScanbotSdk.refreshImageUris(loadedPages);

It is highly recommended using 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.

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?

On this page

Scroll to top