Mobile Document Scanner API Reference / DocumentScanner
Class: DocumentScanner
Defined in: src/flow/document-scanner.ts:92
A document scanner. It loads both engines, and runs each session through its screens: capture, rectify, and edit.
Example
ts
const scanner = new DocumentScanner({ license: "YOUR_LICENSE_KEY_HERE" });
const result = await scanner.scan();
if (result.status === "success") {
// result.pages holds the scanned pages.
}Constructors
Constructor
new DocumentScanner(
settings):DocumentScanner
Defined in: src/flow/document-scanner.ts:119
Make a document scanner. The constructor loads nothing, and shows nothing.
Parameters
settings
The settings, each of them optional.
Returns
DocumentScanner
Throws
TypeError that names the setting, when settings is not an object, or holds an unknown key or a wrong value.
Methods
cancel()
cancel():
void
Defined in: src/flow/document-scanner.ts:320
Abandon the session, as the cancel button of the capture screen does. The document scanner drops every page in the document, including the pages from earlier sessions. The pending scan() resolves as cancelled, even while it waits for the engines. When no session runs, the call does nothing. To empty the document between sessions, call reset().
Returns
void
dispose()
dispose():
void
Defined in: src/flow/document-scanner.ts:349
Cancel any session, and release the engines and the pages. After this call, the document scanner cannot run another session.
Returns
void
finish()
finish():
Promise<boolean>
Defined in: src/flow/document-scanner.ts:308
Finish the session from code, as the done button of the edit screen does, or the thumbnail when the edit phase is off. The pending scan() resolves with the pages, and with the encoded document if output asks for one. The pages stay in the document for the next scan(), until reset(). If the session cannot finish, for example because the export fails, a notice tells the user. The session then stays open, so that the user can try again. If the document holds no pages, the session ends as cancelled.
Returns
Promise<boolean>
Whether the session ended. It is false when the session stays open, and when no session runs.
getDdvViewer()
getDdvViewer(
type):unknown
Defined in: src/flow/document-scanner.ts:411
Experimental
Return the live Document Viewer object of a screen. The object belongs to Document Viewer, so its interface follows the versions of Document Viewer. Thus a release of the document scanner can change it.
Parameters
type
"editViewer" | "perspectiveViewer"
"editViewer" for the edit screen, or "perspectiveViewer" for the rectify screen.
Returns
unknown
The viewer, or null when no session runs, or when the session has not built that screen yet.
getSettings()
getSettings():
ScannerSettings
Defined in: src/flow/document-scanner.ts:379
Return the settings in effect, in the shape that the host application writes them, with a value for every default. Objects that the host application gave, such as the resources.captureVision map or a container element, are the same objects in the result. The result leaves out engines.
Returns
The settings, frozen.
on()
on<
Name>(event,listener): () =>void
Defined in: src/flow/document-scanner.ts:393
Call listener with each payload of event. If a listener throws or rejects, the document scanner reports the error to the console, and the other listeners and the document scanner continue.
Type Parameters
Name
Name extends keyof ScannerEvents
Parameters
event
Name
The name of the event, from ScannerEvents.
listener
(payload) => void | Promise<void>
The function to call with each payload.
Returns
A function that removes the listener.
() => void
Throws
TypeError when event is not the name of an event.
preload()
preload():
Promise<void>
Defined in: src/flow/document-scanner.ts:143
Load the engines before the first scan(), and show nothing. The call is optional, because scan() also loads the engines. If the load fails, every later preload() and scan() fails in the same way. To try again, make a new document scanner after the cause is gone.
Returns
Promise<void>
A promise that resolves when the engines load, or when dispose() stops the load.
Throws
ScannerStateError (as a rejection) when the document scanner is disposed.
reset()
reset():
void
Defined in: src/flow/document-scanner.ts:333
Return the document scanner to its state just after preload(). It then has no pages, the camera that it opens first, auto-capture as the settings set it, and the torch off. A running session ends first, and its scan() resolves as cancelled. The loaded engines stay loaded.
Returns
void
Throws
ScannerStateError when the document scanner is disposed.
scan()
scan(
file?):Promise<ScanResult>
Defined in: src/flow/document-scanner.ts:230
Run a session, which lasts from this call until the promise resolves. Without file, the capture screen shows at once, and waits while the engines load. If the document is full, the edit screen shows instead.
With file, the session starts from that image. The document scanner handles the image as if the user imported it. When phases.rectify.modes.afterCapture is on, the rectify screen shows the page first. Then the edit screen opens, or the session finishes if the edit phase is off. No screen shows until the engines load. The camera opens only when the capture screen opens, for example after a retake. If the browser cannot open file as an image, a notice shows, and the capture screen opens as it does without a file. If the document already holds maxPages pages, a notice says so, and the document scanner does not add the file.
Parameters
file?
Blob
An image to start from, such as a File from a file input.
Returns
Promise<ScanResult>
The result of the session, with the status "success", "cancelled", or "failed".
Throws
ScannerStateError (as a rejection) when the document scanner is disposed, or when a session already runs.
Throws
TypeError (as a rejection) when file is not a Blob.