Skip to main content

Document Scanner | Web Document and Barcode Scanner

Document Scanner UI#

Configuration & Styling#

To start the document scanner, we must first create a DocumentScannerConfiguration object, or simply a dictionary in vanilla javascript, as follows.

const config = {    containerId: containerId,};

The only required property is the containerId, string, that should match the container where you want the document scanner to pop up.

DocumentScannerConfiguration inherits the base properties:

  • containerId โ€“ The id of the containing HTML element where the Document Scanner will be initialized. Required
  • videoConstraints โ€“ The desired video resolution. Optional, defaults to 3840x2160
  • mirrored - Whether the screen should be mirrored. Useful when using a user-facing camera. false by default
  • onError โ€“ Callback when something went wrong. Optional

The configuration object also accepts the following parameters (values displayed are defaults):

acceptedAngleScore: 75,acceptedSizeScore: 75,autoCaptureSensitivity: 0.66,autoCaptureEnabled: true,ignoreBadAspectRatio: true,

Additionally, you can also use the configuration object for react-like styling. It accepts the following parameters for document outline, hint text label and capture button color (values displayed are defaults):

style: {    outline: {        polygon: {            stroke: "yellow",            strokeWidth: "2px",            fill: "none"        },        label: {            position: "absolute",            top: "90%",            left: "50%",            transform: "translate(-50%, -50%)",            textAlign: "center",            backgroundColor: "rgba(0, 0, 0, 0.7)",            color: "white",            borderRadius: "0.25em",            padding: "0.5em",            fontFamily: "sans-serif",            fontSize: "1em"        },        captureButton: {            color: "white"        }    }};

Note that if you wish to do your styling in css, and not in a reactive design pattern, you are more than welcome to.

The defaults bundled with the SDK, that you are welcome to override, are as follows:

.scanbot-document-outline {    stroke: yellow !important;    stroke-width: 2px !important;    fill: none !important;}
.scanbot-document-outline-ok {    stroke: green !important;}
.scanbot-document-outline-visible {    opacity: 1 !important;    transition: opacity .3s ease-in-out !important;}
.scanbot-document-outline-hidden {    opacity: 0 !important;    transition: opacity .3s ease-in-out !important;}
.scanbot-document-hint-text {    position: absolute !important;    top: 90% !important;    left: 50% !important;    transform: translate(-50%, -50%) !important;    text-align: center !important;    background-color: rgba(0, 0, 0, 0.7) !important;    color: white !important;    border-radius: 0.25em !important;    padding: 0.5em !important;    font-family: sans-serif !important;    font-size: 1em !important;}

The capture/shutter button can be repositioned by overriding the following css class:

.scanbot-shutter-button {    /* ... */}

Moreover, the hint texts can also be configured via the same configuration object (values displayed are defaults):

text: {    hint: {        OK: 'Capturing your document... Please do not move the camera.',        OK_SmallSize: 'The document is too small. Try moving closer.',        OK_BadAngles: 'This is a bad camera angle. Hold the device straight over the document.',        OK_BadAspectRatio: 'Rotate the device sideways, so that the document fits better into the screen.',        OK_OffCenter: 'Try holding the device at the center of the document.',        Error_NothingDetected: 'Please hold the device over a document to start scanning.',        Error_Brightness: 'It is too dark. Try turning on a light.',        Error_Noise: 'Please move the document to a clear surface.'    }};

The document scanner works at the maximum available camera resolution for the highest quality scans by default. You can further configure the camera video stream by specifying the videoConstraints property of the document scanner configuration. Most video constraints are directly given to getUserMedia*

The default video constraints are as follows:

videoConstraints: MediaTrackConstraints = {    facingMode: "environment",    resizeMode: "none",    width: { ideal: 3840 },    height: { ideal: 2160 },    experimental: {        focusMode: "continous",        focusDistance: 0    },};

*Everything except experimental is passed directly to getUserMedia, because they are advanced constraints they will not work on all browsers and thus require special application. All advanced constraints, however, are passed to the video stream in the same fashion. You can add additional advanced constraints.

Callbacks#

To receive detection results define onDocumentDetected in the configuration:

onDocumentDetected: result => {    console.log("Detected Document:", result);}

The result object contains the following properties:

  • detectionStatus โ€“ contains the same keys as the hint texts mentioned earlier
  • success โ€“ boolean, whether detection was successful or not
  • original โ€“ If success, contains the cropped document ArrayBuffer (UInt8Array)
  • cropped โ€“ If success, contains the cropped document ArrayBuffer (UInt8Array)
  • polygon โ€“ The page's cropping polygon as calculated by a document detection operation

Note that this will be called every time a document is detected, until you stop detection or dispose of the camera.

Creating the Scanner#

After you are done configuring the scanner, simply refer back to your SDK object and create the scanner object as follows:

documentScanner = await scanbotSDK.createDocumentScanner(config);

An exception is thrown if camera streaming is not supported or the user blocks the camera.

Handling Automatic Capture#

If you wish to do image processing between document captures, or find the document scanner a wee bit too trigger-happy, (which is plausible on high-end devices) there is the option to disable automatic capture on the fly.

You can also use these calls to create your own custom auto-capture on/off switch.

Call to disable auto-capture:

documentScanner.disableAutoCapture();

And when processing is complete, or the switch is flicked, re-enable it with the following command:

documentScanner.enableAutoCapture();

To verify whether auto-capture is enabled or not, call:

documentScanner.isAutoCaptureEnabled();

Disposal#

Always dispose of the document scanner after it is no longer needed

await documentScanner.dispose();