Skip to main content

Page Model | Cordova Document Scanner

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:

interface Page {    pageId: string;    polygon: Point[];    detectionResult: DetectionStatus;    filter: ImageFilter;    documentImageSizeLimit?: Size;    originalImageFileUri: string;    documentImageFileUri?: string;    originalPreviewImageFileUri: string;    documentPreviewImageFileUri?: string;    isCapturedAutomatically: boolean;}

The fields are:

  • pageId - a string 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
  • detectionResult - the detection result of the document detection operation that produced the page (either the document scanner or detectDocument())
  • filter - the image filter which was applied to 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
  • isCapturedAutomatically - a boolean to identify whether the image was captured automatically or manually triggered by the shutter button.

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.

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 to the new absolute paths, the API method refreshImageUris({pages: Page []}) has been introduced in the plugin version 4.4.0. Please use this method to refresh all image file URIs from affected pages:

const result = await this.SDK.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(successCallback, errorCallback, options)#

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

Callbacks:#
successCallback : function(result)
  • result.page - the created page object. As the page has not been cropped yet, the documentImageFileUri and documentPreviewImageFileUri properties will be empty.
errorCallback : function(error)
  • error.status - 'ERROR' in all error cases.
  • error.message - Contains the error message as a string.
Options:#
var options = {  originalImageFileUri: 'file:///...'};
  • options.originalImageFileUri - the file URI of the image to wrap in a page.

Set Document Image#

ScanbotSdk.setDocumentImage(successCallback, errorCallback, options)#

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

Callbacks:#
successCallback : function(result)
  • result.page is the page object with the replaced document image.
errorCallback : function(error)
  • error.status - 'ERROR' in all error cases.
  • error.message - Contains the error message as a string.
Options:#
var options = {  page: ...,  imageUri: 'file:///...',};
  • options.page - the page to modify.
  • options.imageUri - the URI of an image file with which to overwrite the page's document image.

Detect Document On Page#

ScanbotSdk.detectDocumentOnPage(successCallback, errorCallback, options)#

Runs document detection on the original image of the given page. The detection status, polygon and cropped document image are returned as a new page object in the success callback.

Callbacks:#
successCallback : function(result)
  • result.page is the page object with the detection result.
errorCallback : function(error)
  • error.status - 'ERROR' in all error cases.
  • error.message - Contains the error message as a string.
Options:#
var options = {  page: ...};
  • options.page - the page to crop.

Remove Page#

ScanbotSdk.removePage(successCallback, errorCallback, page)#

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.

Callbacks:#
successCallback : function(result)
  • result.status - 'OK' - page images successfully removed from the device.
errorCallback : function(error)
  • error.status - 'ERROR' in all error cases.
  • error.message - Contains the error message as a string.