No image scanned. Please try again.
"; } ``` ## Custom Usage This section builds on the Hello World sample to demonstrate how to configure **MDS**, typically by adjusting the `DocumentScannerConfig` object. ### `DocumentScannerConfig` Overview [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscannerconfig) is the primary configuration object for customizing **MDS**. It includes the following properties: 1. `license` - the license key. 2. `container` - the HTML container for the entire workflow. If not specified (like in the Hello World Sample), one is created automatically. 3. `showCorrectionView` - toggle `DocumentCorrectionView` in the scanning workflow. 4. `showResultView` - toggle `DocumentResultView` in the scanning workflow. 5. `enableFrameVerification` - toggle selecting the clearest of multiple video frames upon scanning (on by default). 6. `enableContinuousScanning` - toggle continuous scanning mode to make multiple scans on a single `launch()` (`false` by default). 7. `onDocumentScanned` - handler to get single scan results in continuous scanning mode (if `enableContinuousScanning` is `true`). 8. `stopContinuousScanning` - programmatically stop the scanning loop when continuous scanning mode is enabled. 9. `scannerViewConfig` - configure the main scanner view with the following properties: 1. `container` - the HTML container for the `DocumentScannerView`. 2. `cameraEnhancerUIPath` - path to the UI definition file (.html) for the `DocumentScannerView`. 3. `enableAutoCropMode` - set the default value of Auto-Crop upon entering the `DocumentScannerView`. 4. `enableSmartCaptureMode` - set the default state of Smart Capture upon entering the `DocumentScannerView`. 5. `enableBoundsDetectionMode` - set the default state of bounds detection mode upon entering the `DocumentScannerView`. 6. `scanRegion` - set the scan region within the document scanning viewfinder. 7. `minVerifiedFramesForSmartCapture` - set the minimum number of video frames to verify detected document boundaries on Smart Capture mode. Higher frame counts lead to higher confidence at the cost of discarding results. 8. `showSubfooter` - toggle the visibility of the mode selector menu. 9. `showPoweredByDynamsoft` - set the visibility of the Dynamsoft branding message. 10. `correctionViewConfig` - configure the `DocumentCorrectionView`. 1. `container` - the HTML container for the `DocumentCorrectionView`. 2. `toolbarButtonsConfig` - configure the appearance and labels of the buttons for the `DocumentCorrectionView` UI. 3. `onFinish` - handler called when the user clicks the "Apply" button. 11. `resultViewConfig` - configure the result view with the following properties: 1. `container` - the HTML container for the `DocumentResultView`. 2. `toolbarButtonsConfig` - configure the appearance and labels of the buttons for the `DocumentResultView` UI. 3. `onDone` - handler called when the user clicks the "Done" button. 4. `onUpload` - handler called when the user clicks the "Upload" button. 12. `templateFilePath` - path to a Capture Vision template for scanning configuration; typically not needed as the default template is used. 13. `utilizedTemplateNames`- template names for detection and correction. Typically not needed as the default template is used. 14. `engineResourcePaths` - paths to extra resources such as `.wasm` engine files. Furthermore, we explore three main (non-mutually-exclusive) avenues of customization with `DocumentScannerConfig`: 1. [**Multi-Page Scanning**](#multi-page-scanning): through configuration objects and container definitions. 2. [**Workflow Customization**](#workflow-customization): through container definitions. 3. [**View-Based Customization**](#view-based-customization): through configuration objects. The customization examples below build on the Hello World code from the [previous section](#use-precompiled-script). The only change required is adjusting the constructor argument. ```javascript const documentScanner = new Dynamsoft.DocumentScanner({ license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key // Add more arguments }); ``` ### Multi-Page Scanning Mobile Document Scanner can scan multi-page documents when configured to use the continuous scanning mode. Unlike the default behavior of returning a single scan on calling `launch()`, continuous scanning outputs a scan result on every successful scan, which you can further process by providing a handler. The workflow repeats to let the user scan through large documents efficiently. See [**Workflow Customization**](#workflow-customization) and [**View-Based Customization**](#view-based-customization) for a more thorough explanation of the customization syntax. #### Basic Multi-Page Scanning [**Full Sample Source Code**](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/samples/scenarios/multi-page-scanning.html) The most straightforward way to implement multi-page scanning is to enable continuous scanning mode and provide a callback handler to process each scanned document via [`onDocumentScanned`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#ondocumentscanned). The scanner loops after each successful scan, allowing users to capture multiple pages in succession. The user can manually stop scanning by clicking the "Done" or close buttons from the Document Scanner View. Consider the relevant sections from the source code below: ```html ``` ```javascript const documentScanner = new Dynamsoft.DocumentScanner({ license: "YOUR_LICENSE_KEY_HERE", enableContinuousScanning: true, onDocumentScanned: (result) => { // Process each scanned document const canvas = result.correctedImageResult.toCanvas(); document.getElementById("results").appendChild(canvas); }, }); await documentScanner.launch(); ``` API Reference: - [`DocumentScannerConfig.enableContinuousScanning`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#enableContinuousScanning) - [`DocumentScannerConfig.onDocumentScanned`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#ondocumentscanned) ##### Explanation There are two essential components to multi-page scanning - enabling continuous scanning mode, and providing your handler to process the scanned pages. 1. We enable continuous scanning with the [`enableContinuousScanning`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#enableContinuousScanning) property - this is responsible for changing the user workflow, automatically going back to the scanner view to take more scans after confirming each scan. 2. Provide a handler to [`onDocumentScanned`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#ondocumentscanned) to process each scanned page. This handler runs after each confirmed scan. In this example, we display the result image on the page. > Just as in single-scan mode, `launch()` returns a `DocumentResult` promise. In continuous scanning mode, `launch()` returns a **`DocumentResult` promise to the last page scanned**. ##### Optional Settings To enhance the scanning process, you may also choose to use the following settings: 1. Provide a handler to [`onThumbnailClicked`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#onthumbnailclicked), for example, to show a full preview of the last scanned page. 2. Stop the scanning loop programmatically by calling [`stopContinuousScanning()`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#stopcontinuousscanning) externally. This is particularly useful if scanning a pre-determined number of pages by counting the number of scans received by `onThumbnailClicked`. 3. For a faster scanning experience, enable both Smart Capture and Auto-Crop modes by default without requiring the user to re-enable them for each scan. See [Configure Scan Modes](#example-5-configure-scan-modes) for details. 4. Under certain use cases where the user does not need to manually edit or change the document boundaries, you can also skip the Document Correction and Document Result Views entirely. This allows the user to stay within the Document Scanner View to capture with the least number of manual interactions per scan. See [Only Show `DocumentScannerView`](#example-2-only-show-documentscannerview) for details. #### Multi-Page Scanning with DDV > You can find the full set of comprehensive documentation Dynamsoft Document Viewer [on our website](https://www.dynamsoft.com/document-viewer/docs/introduction/index.html). [**Full Sample Source Code**](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/samples/scenarios/scanning-to-pdf.html) For a more advanced multi-page scanning solution with document management, image editing, and comprehensive file support capabilities (including PDF), you can integrate **MDS** with **Dynamsoft Document Viewer (DDV)**. This combination provides: - Document editing and management - Thumbnail previews - Page reordering and deletion - PDF export functionality - A polished UI for both mobile and desktop Given the length of the sample, we only provide a snippet for creating the MDS instance here. See the full sample for more. Please see the [DDV documentation](https://www.dynamsoft.com/document-viewer/docs/introduction/index.html) for DDV-related APIs. ```javascript const documentScanner = new Dynamsoft.DocumentScanner({ // Public trial license which is valid for 24 hours // You can request a 30-day trial key from https://www.dynamsoft.com/customer/license/trialLicense/?product=mds license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key container: scannerContainer, scannerViewConfig: { enableAutoCropMode: true, enableSmartCaptureMode: true, }, enableContinuousScanning: true, onDocumentScanned: async (result) => { try { // Convert the scanned image to blob const canvas = result.correctedImageResult.toCanvas(); const blob = await new Promise((resolve) => { canvas.toBlob((b) => resolve(b), "image/jpeg", 0.9); }); // Add the scanned page to DDV document if (blob) { await doc.loadSource([ { convertMode: "cm/auto", fileData: blob, }, ]); } } catch (error) { console.error("Error adding scanned page to DDV:", error); } }, }); ``` API Reference: - [`DocumentScannerViewConfig`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscannerviewconfig) - [`enableAutoCropMode`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#enableautocropmode) - [`enableSmartCaptureMode`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#enablesmartcapturemode) - [`DocumentScannerConfig.enableContinuousScanning`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#enableContinuousScanning) - [`onDocumentScanned`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#ondocumentscanned) - [`loadSource()`](https://www.dynamsoft.com/document-viewer/docs/api/interface/idocument/index.html#loadsource) ##### Explanation For brevity, we outline the key steps in this sample implementation: 1. Initialize DDV 2. Customize the DDV edit viewer (notably by adding a scan button that launches MDS) 3. Instantiate the DDV edit viewer 4. Create a DDV document 5. Create a `DocumentScanner` instance 1. Enable continuous scanning 2. On confirming a scan, convert and send the image to the DDV document with [`loadSource()`](https://www.dynamsoft.com/document-viewer/docs/api/interface/idocument/index.html#loadsource) in the MDS event handler 6. Add an event to launch MDS when clicking the custom scan button added to DDV 7. Add an event to DDV that outputs a PDF of the scanned documents from DDV on close using [`saveToPdf()`](https://www.dynamsoft.com/document-viewer/docs/api/interface/idocument/#savetopdf) ### Workflow Customization In the Hello World sample, we use the complete workflow with minimum configuration: ```javascript const documentScanner = new Dynamsoft.DocumentScanner({ license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key }); // Launch the scanner and wait for the result const result = await documentScanner.launch(); ``` In this case, **MDS** automatically creates container elements for its **Views**. In this section we discuss a few ways to adjust the **MDS** workflow. #### Example 1: Confine DocumentScanner UI to a Specific Container As long as the `DocumentScanner` container is assigned, **MDS** confines its **Views** within that container. > Containers assigned to its constituent **Views** will be ignored. ```html ``` ```javascript const documentScanner = new Dynamsoft.DocumentScanner({ license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key container: document.getElementById("myDocumentScannerContainer"), // Use this container for the full workflow scannerViewConfig: { container: document.getElementById("myDocumentScannerViewContainer"), // This container is ignored }, }); ``` API Reference: - [`DocumentScanner()`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscanner) - [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscannerconfig) #### Example 2: Only Show `DocumentScannerView` If you do not need either the `DocumentResultView` or `DocumentCorrectionView` in your workflow (for example, if you do not want your user to manually alter the detected document boundaries), you can hide the views with the following configuration properties like so: ```javascript const documentScanner = new Dynamsoft.DocumentScanner({ license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key showResultView: false, showCorrectionView: false, }); ``` API Reference: - [`DocumentScanner()`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscanner) - [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscannerconfig) #### Example 3: Specify Individual View Containers If the configuration object provide containers for the `DocumentScannerView`, `DocumentResultView`, and `DocumentCorrectionView`, but **does not provide** the `DocumentScanner` container, then **MDS** renders the full workflow using these three containers. ```html ``` ```javascript const documentScanner = new Dynamsoft.DocumentScanner({ license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key scannerViewConfig: { container: document.getElementById("myDocumentScannerViewContainer"), }, correctionViewConfig: { container: document.getElementById("myDocumentCorrectionViewContainer"), }, resultViewConfig: { container: document.getElementById("myScanResultViewContainer"), }, }); ``` API Reference: - [`DocumentScanner()`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscanner) - [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscannerconfig) #### Example 4: Scan Static Image Directly To scan an image file directly without displaying the `DocumentScannerView` UI at all, you can pass a `File` object to `launch()`. As an example, select an image file from the local disk: ```html ``` Then get the input file as a `File` object, and pass that file object to `launch()` MDS with: ```javascript document.getElementById("initialFile").onchange = async function () { const files = Array.from(this.files || []); if (files.length) { const result = await documentScanner.launch(files[0]); console.log(result); // Clear the result container and display the scanned result as a canvas if (result?.correctedImageResult) { resultContainer.innerHTML = ""; // Clear placeholder content const canvas = result.correctedImageResult.toCanvas(); resultContainer.appendChild(canvas); } else { resultContainer.innerHTML = "No image scanned. Please try again.
"; } } }; ``` This hides the `DocumentScannerView` UI entirely and brings up the `DocumentCorrectionView` as the first view, after having detected document boundaries on the static image. The user can proceed through the rest of the workflow and further alter the document boundaries, re-take another image (to open up the `DocumentScannerView`), etc. > `launch()` can accept images or PDFs. If launching with a PDF, MDS will **only process the first page**. > You can disable all UI and run MDS headlessly by hiding both the `DocumentCorrectionView` and the `DocumentResultView` in [example 2](#example-2-only-show-documentscannerview). #### Example 5: Configure Scan Modes The Document Scanner View comes with three scan modes: 1. Border Detection 2. Auto-Crop 3. Smart Capture By default, Border Detection mode is enabled upon entering the Scanner View, while the other two are turned off by default. The user can then enable them by clicking their respective icons in the scanning mode sub-footer. From the `DocumentScannerViewConfig` interface, you can: 1. Set the default state of Auto-Crop mode with `enableAutoCropMode` 2. Set the default state of Smart Capture mode with `enableSmartCaptureMode` 3. Set the visibility of the scanning mode sub-footer with `showSubfooter` > Border Detection Mode is always enabled in the Scanner View, and the scanning sub-footer is visible by default. For example, the following config enables all three scanning modes and hides the scanning mode sub-footer to prevent the user from changing or viewing the scanning modes: ```javascript const documentScanner = new Dynamsoft.DocumentScanner({ license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key scannerViewConfig: { enableAutoCropMode: true, enableSmartCaptureMode: true, showSubfooter: false, }, }); ``` API Reference: - [`DocumentScanner()`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscanner) - [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscannerconfig) - [`DocumentScannerViewConfig`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscannerviewconfig) ### View-Based Customization In addition to modifying the workflow, you can customize individual Views with configuration options for UI styling, button settings, and event handling. #### `DocumentScannerView` Configuration ##### Customizing the `DocumentScannerView` UI You can extensively customize the `DocumentScannerView` by editing its HTML template. Consider the following properties of the `DocumentScannerViewConfig` used for customizing the `DocumentScannerView`: ```typescript interface DocumentScannerViewConfig { container?: HTMLElement; templateFilePath?: string; cameraEnhancerUIPath?: string; } ``` Of these three properties, we focus on `cameraEnhancerUIPath`. Here we omit `container`, as we cover it in [Workflow Customization](#workflow-customization), and we omit `templateFilePath`, as it refers to the DCV template file that configures document boundary detection algorithms. > If the performance of **MDS** does not meet your needs, you may require an algorithm template **customized for your usage scenario** for better results. Please contact our experienced [Technical Support Team](https://www.dynamsoft.com/company/contact/) to discuss your requirements. We can tailor a suitable template for you, which you can then apply by updating `templateFilePath`. `cameraEnhancerUIPath` points to a file hosted on the jsDelivr CDN by default (see [Self-Host Resources: Point to Resources](#point-to-resources)): [https://cdn.jsdelivr.net/npm/dynamsoft-document-scanner@1.4.2/dist/document-scanner.ui.xml](https://cdn.jsdelivr.net/npm/dynamsoft-document-scanner@1.4.2/dist/document-scanner.ui.xml). This file defines the UI for `DocumentScannerView`. Since files on the CDN **cannot be modified directly**, you must use a **local version** to customize the UI. `cameraEnhancerUIPath` specifies the file path to this local version of the UI. ##### Steps to Customize the UI for `DocumentScannerView` 1. Follow the instructions in [Build from Source](#build-from-source) to obtain the source files for **MDS**. 2. Edit the existing `/src/dcv-config/document-scanner.ui.xml` to apply your customizations. 3. Build the project to generate the updated file in `/dist/document-scanner.ui.xml`: ```shell npm run build ``` 4. Update the configuration to use the local file instead of the CDN version: ```javascript const documentScanner = new Dynamsoft.DocumentScanner({ license: "YOUR_LICENSE_KEY_HERE", // Replace with your actual license key scannerViewConfig: { cameraEnhancerUIPath: "../dist/document-scanner.ui.xml", // Use the local file }, }); ``` API Reference: - [`DocumentScanner()`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscanner) - [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscannerconfig) - [`DocumentScannerViewConfig`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#documentscannerviewconfig) ##### Customizing the Scanning Region We can customize the scanning region in the viewfinder with the `scanRegion` property in the configuration object. You may want to do this if you want to only scan your document in a specific sub-region in the viewfinder. ```typescript interface ScanRegion { ratio: { width: number; height: number; }; regionBottomMargin: number; // Bottom margin calculated in pixel style: { strokeWidth: number; strokeColor: string; }; } ``` API Reference: [`ScanRegion`](https://www.dynamsoft.com/mobile-document-scanner/docs/web/api/index.html#scanregion) Here is how `ScanRegion` applies its settings to the viewfinder: 1. Use the `ratio` property to set the height-to-width of the rectangular scanning region, then scale the rectangle up to fit within the viewfinder. 2. Translate the rectangular region up by the number of pixels specified by `regionBottomMargin`. 3. Create a visual border for the scanning region boundary on the viewfinder with a given stroke width in pixels, and a stroke color. For example: ```javascript const scanRegion = { ratio: { width: 2, height: 3, }, regionBottomMargin: 20, style: { strokeWidth: 3, strokeColor: "green", }, }; ``` This creates a scan region with a height-to-width ratio of 3:2, translated upwards by 20 pixels, with a green, 3 pixel-wide border in the viewfinder. #### `DocumentCorrectionView` Configuration The following configuration interface customizes the `DocumentCorrectionView`: ```typescript interface DocumentCorrectionViewConfig { container?: HTMLElement; toolbarButtonsConfig?: DocumentCorrectionViewToolbarButtonsConfig; onFinish?: (result: DocumentScanResult) => void; } ``` This section omits the `container` option, as we cover it in the [Workflow Customization](#workflow-customization) section. Below we discuss the other two properties. ##### Styling `DocumentCorrectionView` Buttons The `toolbarButtonsConfig` property (of type `DocumentCorrectionViewToolbarButtonsConfig`) customizes the **appearance and functionality** of the UI buttons. Here is its definition: ```typescript type ToolbarButtonConfig = Pick