Classic UI

Configuration & Styling

To start the Document Scanner Classic UI, we must first create a DocumentScannerViewConfiguration 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.

DocumentScannerViewConfiguration 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
• preferredCamera - Camera label or camera device id. If not available, a default camera is used as fallback
• onError – Callback when something went wrong. Optional

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

autoCaptureSensitivity: 0.66,
autoCaptureEnabled: true,
ignoreBadAspectRatio: true,
useImageCaptureAPI: false,
detectionParameters: new DocumentScannerParameters()

See the API Docs for a description of all the fields of DocumentScannerParameters.

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: {
            strokeCapturing: "green",
            strokeSearching: "yellow",
            fillCapturing: "transparent",
            fillSearching: "transparent",
            strokeWidth: "2px"
        },
        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"
        },
        path: {
             stroke: "green";
             strokeWidth: 4;
        }
    },
    captureButton: {
        color: "white"
    }
};

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_SMALL_SIZE: "The document is too small. Try moving closer.",
        OK_BAD_ANGLES: "This is a bad camera angle. Hold the device straight over the document.",
        OK_BAD_ASPECT_RATIO: "Rotate the device sideways, so that the document fits better into the screen.",
        OK_OFF_CENTER: "Try holding the device at the center of the document.",
        ERROR_NOTHING_DETECTED: "Please hold the device over a document to start scanning.",
        ERROR_TOO_DARK: "It is too dark. Try turning on a light.",
        ERROR_NOISE: "Please move the document to a clear surface.",
        NOT_ACQUIRED: "Scanning failed."
    }
};

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);
}

See the API Docs for a description of all fields of the result object.

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

The Scanner Object

To open the Document Scanner, simply call the relevant SDK function with your configuration object:

scanner = await scanbotSDK.createDocumentScanner(config);

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

Handling Automatic Capture

There is the option to disable automatic capture on the fly (for example image processing between document captures). You can also use these calls to create your own custom auto-capture on/off switch.

Call to disable auto-capture:

scanner.disableAutoCapture();

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

scanner.enableAutoCapture();

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

scanner.isAutoCaptureEnabled();

Switching to a specific available camera

scanner.fetchAvailableCameras(): Promise<CameraInfo[]>;
scanner.switchCamera(deviceId: string, mirrored?: boolean): void;
scanner.getActiveCameraInfo(): CameraInfo | undefined;

interface CameraInfo {
    deviceId: string;
    label: string;
    facingMode?: CameraFacingMode;
    supportsTorchControl?: boolean;
}

type CameraFacingMode = 'front' | 'back' | 'unknown';

You can search for available cameras on the running browser by using fetchAvailableCameras method of a scanner. You can retrieve the label, device id and the camera facing mode information of the active camera of a scanner by using getActiveCameraInfo method. And, you can switch to another available camera by utilizing its device id, by using switchCamera method.

// There can be no cameras available, so check if cameras is not null
const cameras = await scanner.fetchAvailableCameras()
// Current camera info can be unavailable, so check if currentCameraInfo is not null
const currentCameraInfo = scanner.getActiveCameraInfo();
const cameraIndex = cameras.findIndex((cameraInfo) => {
    return cameraInfo.deviceId == currentCameraInfo.deviceId;
});
const newCameraIndex = (cameraIndex + 1) % (cameras.length);
scanner.switchCamera(cameras[newCameraIndex].deviceId);

Controlling the torch (flashlight)

On some mobile devices, the browser can control the torch (flashlight). Check scanner.getActiveCameraInfo().supportsTorchControl to see if the browser can control the torch for the currently active camera. If true, you can control the torch by using the setTorchState method of the scanner.

scanner.setTorchState(state: boolean): Promise<void>;

info

On Android devices, only Chrome supports torch control. Starting with iOS 17.4, all supported browsers on iOS offer torch control functionality.

Disposal

As with the other scanners of Scanbot SDK, this one should also be properly disposed of when you have detected and processed the relevant data. This is to ensure the camera instance as well as lingering SDK functions are properly disposed to prevent memory leaks.

await scanner.dispose();

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.

---