Scan Single-Page Documents with Dynamsoft Document Scanner
Prerequisite: Read the Introduction before proceeding.
Dynamsoft Document Scanner (DDS) is an SDK designed for scanning single-page documents. It not only captures images of the documents but also enhances their quality to professional standards, making it an ideal tool for mobile document scanning.
See it in action with the Dynamsoft Document Scanner Demo.
This guide walks you through building a web application that scans single-page documents using DDS, with pre-defined configurations.
License
Get a Trial License
If you haven’t got a trial license for DDS, you can request one here:
The trial license can be renewed twice, offering a total of two months of free access.
DDS and MWC share the same s. If you already have a DDS license, you can use it for MWC, and vice versa.
Get a Full License
To purchase a full license, contact us.
Quick Start
The first step in using DDS is to obtain its library files. You can acquire them from one of the following sources:
- – Contains the source files for the DDS SDK, which can be compiled into library files.
- npm – Provides precompiled library files via npm for easier installation.
- CDN – Delivers precompiled library files through a CDN for quick and seamless integration.
You can choose one of the following methods to set up a Hello World page:
- Build from Source – Download the source files from and compile the resource script yourself.
- Using Precompiled Script – Use the precompiled resource scripts from npm or the CDN for a quicker setup.
Option 1: Build from Source
This method retrieves all DDS source files from its Repository, compiles them into a distributable package, and then runs a ready-made Hello World sample page included in the repository:
- Download DDS from as a compressed folder.
- Extract the contents of the archive, and open the extracted directory in a code editor.
- Set your in the Hello World sample:
- Open the Hello World sample at (
/samples/hello-world.html
). - Search for
"YOUR_LICENSE_KEY_HERE"
, then replace it with your actual .
- Open the Hello World sample at (
- Install project dependencies In the terminal, navigate to the project root directory and run:
npm install
- Build the project After installing dependencies, build the project by running:
npm run build
- Serve the project locally Start the local server by running:
npm run serve
Once the server is running, open the application in a browser using the address provided in the terminal output after running
npm run serve
.
See the server configuration details in /dev-server/index.js
.
Option 2: Use Precompiled Script
Since the DDS library files are published on npm, it’s easy to reference them from a CDN.
To use the precompiled script, simply include the following URL in a <script>
tag:
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/dds.bundle.js"></script>
Below is the complete Hello World sample page that uses this precompiled script from a CDN.
The code is identical to the /samples/hello-world.html
file mentioned in the Build from Source section, except for the script source.
Don’t forget to replace "YOUR_LICENSE_KEY_HERE"
with your actual .
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Dynamsoft Document Scanner - Hello World</title>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/dds.bundle.js"></script>
</head>
<body>
<h1 style="font-size: large">Dynamsoft Document Scanner</h1>
<div id="results"></div>
<script>
const resultContainer = document.querySelector("#results");
// Instantiate a Dynamsoft Document Scanner Object
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
});
(async () => {
// Launch the scanner and wait for the result
const result = await documentScanner.launch();
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 = "<p>No image scanned. Please try again.</p>";
}
})();
</script>
</body>
</html>
To run the sample, create a new file called hello-world.html
, then copy and paste the code above into the file. Next, serve the page directly by deploying it to a server.
If you are using VS Code, a quick and easy way to serve the project is using the Live Server (Five Server) VSCode extension. Simply install the extension, open the hello-world.html
file in the editor, and click “Go Live” in the bottom right corner of the editor. This will serve the application at http://127.0.0.1:5500/hello-world.html
.
Alternatively, you can use other methods like IIS
or Apache
to serve the project, though we won’t cover those here for brevity.
Hello World Sample Explained
Let’s walk through the code in the Hello World Sample to understand how it works.
You can also view the full code by visiting the Dynamsoft Document Scanner Hello World Sample on .
Reference DDS
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Dynamsoft Document Scanner - Hello World</title>
<script src="../dist/dds.bundle.js"></script>
<!--Alternatively, reference the script from CDN
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/dds.bundle.js"></script>
-->
</head>
In this step, DDS is referenced using a relative local path in the <head>
section of the HTML.
<script src="../dist/dds.bundle.js"></script>
Alternatively, the script can be referenced from a CDN:
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/dds.bundle.js"></script>
DDS wraps all its dependency scripts, so a DDS project only needs to include DDS itself as a single script. No additional dependency scripts are required.
Even if you reference the script locally, supporting resources like .wasm
engine files are still loaded from the CDN at runtime. If you require a fully offline setup, follow the instructions in Self-Hosting Resource File.
Instantiate DDS
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
});
API Reference:
This step creates the DDS UI, which occupies the entire visible area of the browser window by default when launched. If needed, you can specify a container to restrict the UI’s size. For more details, refer to Confine DocumentScanner UI to a Specific Container.
A is required for instantiation.
Launch DDS
const result = await documentScanner.launch();
API Reference:
This step launches the user into the document scanning workflow, beginning in the DocumentScannerView
, where they can scan a document using one of three methods:
- Option 1: Manually scan by pressing the shutter button.
- Option 2: Enable “Smart Capture” - the scanner will automatically capture an image once a document is detected.
- Option 3: Enable “Auto Crop” - the scanner will automatically capture an image, detect the document, and crop it out of the video frame.
For Options 1 & 2: The user is directed toDocumentCorrectionView
to review detected document boundaries and make any necessary adjustments before applying corrections. Afterward, they proceed toDocumentResultView
.For Option 3: The
DocumentCorrectionView
step is skipped. Image correction is applied automatically, and the user is taken directly toDocumentResultView
.
In DocumentResultView
, if needed, the user can return to DocumentCorrectionView
to make additional adjustments or press “Re-take” to restart the scanning process.
Display the Result
The workflow returns a scanned image object of type CorrectedImageResult
. To display the scanned result
image, we use a <div>
in the <body>
:
<body>
<h1 style="font-size: large">Dynamsoft Document Scanner</h1>
<div id="results"></div>
API Reference:
The following code clears the result container and displays the scanned result as a canvas:
if (result?.correctedImageResult) {
resultContainer.innerHTML = "";
const canvas = result.correctedImageResult.toCanvas();
resultContainer.appendChild(canvas);
} else {
resultContainer.innerHTML = "<p>No image scanned. Please try again.</p>";
}
Custom Usage
This section builds on the Hello World sample to demonstrate how to configure DDS, typically by adjusting the DocumentScannerConfig
object.
DocumentScannerConfig
Overview
DocumentScannerConfig
is the primary configuration object for customizing DDS. It includes the following properties:
license
: The .container
: The HTML container for the entire workflow. If not specified (like in the Hello World Sample), one is created automatically.showCorrectionView
: Configures whether or not to showDocumentCorrectionView
.showResultView
: Configures whether or not to showDocumentResultView
.scannerViewConfig
: Configures the main scanner view with the following properties:container
: The HTML container for theDocumentScannerView
.cameraEnhancerUIPath
: Path to the UI definition file (.html) for theDocumentScannerView
.enableAutoCropMode
: sets the default Auto-Crop mode.enableSmartCaptureMode
: sets the default Smart Capture mode.scanRegion
: sets the scan region within the viewfinder for document scanning.minVerifiedFramesForSmartCapture
: sets minimum number of camera frames to detect document boundaries on Smart Capture mode.showSubfooter
: sets the visibility of the mode selector menu.showPoweredByDynamsoft
: sets the visibility of the Dynamsoft branding message.
correctionViewConfig
: Configures the document correction view.container
: The HTML container for theDocumentCorrectionView
.toolbarButtonsConfig
: Configures the appearance and labels of the buttons for theDocumentCorrectionView
UI.onFinish
: Handler called when the user clicks the “Apply” button.
resultViewConfig
: Configures the result view with the following properties:container
: The HTML container for theDocumentResultView
.toolbarButtonsConfig
: Configures the appearance and labels of the buttons for theDocumentResultView
UI.onDone
: Handler called when the user clicks the “Done” button.onUpload
: Handler called when the user clicks the “Upload” button.
templateFilePath
: Path to a Capture Vision template for scanning configuration. Typically not needed as the default template is used.utilizedTemplateNames
: Template names for detection and correction. Typically not needed as the default template is used.engineResourcePaths
: Paths to extra resources such as.wasm
engine files.
We will discuss two main methods of customizing DDS with DocumentScannerConfig
:
- Workflow Customization: Through container definitions.
- View-Based Customization: Through configuration objects.
The customization examples below will build on the Hello World code from the previous section. The only change required is adjusting the constructor argument.
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
// Add more arguments
});
Workflow Customization
In the Hello World sample, we use the complete workflow with minimum configuration:
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
});
// Launch the scanner and wait for the result
const result = await documentScanner.launch();
In this case, DDS automatically creates “containers” for its Views. In this section, we’ll discuss a few examples to adjust the DDS workflow.
Example 1: Confine DocumentScanner UI to a Specific Container
As long as the DocumentScanner
container is assigned, DDS will confine its Views within that container.
Containers assigned to its constituent Views will be ignored.
<div id="myDocumentScannerContainer" style="width: 80vw; height: 80vh;"></div>
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
container: document.getElementById("myDocumentScannerContainer") , // Use this container for the full workflow
scannerViewConfig: {
container: document.getElementById("myDocumentScannerViewContainer") // This container is ignored
}
});
API Reference:
Example 2: Only Show DocumentScannerView
In some cases, DocumentResultView
and DocumentCorrectionView
may not be needed, so they can be hidden:
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
showResultView: false,
showCorrectionView: false
});
API Reference:
Example 3: Specify Individual View Containers
If only the DocumentScannerView
, DocumentResultView
, and DocumentCorrectionView
containers are provided without the DocumentScanner
container, DDS will render the full workflow using these three containers.
<div id="myDocumentScannerViewContainer" style="width: 80vw; height: 80vh"></div>
<div id="myDocumentCorrectionViewContainer" style="width: 80vw; height: 80vh"></div>
<div id="myScanResultViewContainer" style="width: 80vw; height: 80vh"></div>
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
scannerViewConfig: {
container: document.getElementById("myDocumentScannerViewContainer")
},
correctionViewConfig: {
container: document.getElementById("myDocumentCorrectionViewContainer")
},
resultViewConfig: {
container: document.getElementById("myScanResultViewContainer")
}
});
API Reference:
Example 4: Scan Static Image Directly
To scan an image file directly without opening the Scanner View at all, you can pass a File
object to launch()
. As an example, select an image file from the local disk:
<input type="file" id="initialFile" accept="image/png,image/jpeg" />
Then get the input file as a File
object, and pass that file object to launch()
DDS with:
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 = "<p>No image scanned. Please try again.</p>";
}
}
};
This bypasses the Scanner View entirely and brings up the Correction View 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 Scanner View), etc.
launch()
can accept images or PDFs. If launching with a PDF, DDS will only process the first page.
Example 5: Configure Scan Modes
The Document Scanner View comes with three scan modes:
- Border Detection
- Auto-Crop
- 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:
- Set the default state of Auto-Crop mode with
enableAutoCropMode
- Set the default state of Smart Capture mode with
enableSmartCaptureMode
- Set the visibility of the scanning mode sub-footer with
showSubfooter
Border Detection Mode is always enabled upon 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 viewer from changing or viewing the scanning modes:
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
scannerViewConfig: {
enableAutoCropMode: true,
enableSmartCaptureMode: true,
false,
}});
API Reference:
View-Based Customization
In addition to modifying the workflow, individual Views can be customized with configuration options for UI styling, button settings, and event handling.
DocumentScannerView
Configuration
Customizing the DocumentScannerView
UI
Consider the following configuration interface used for customizing the DocumentScannerView
:
interface DocumentScannerViewConfig {
container?: HTMLElement;
templateFilePath?: string;
cameraEnhancerUIPath?: string;
}
We previously covered container
in Workflow Customization, and changing templateFilePath
is usually not required. Now, let’s focus on cameraEnhancerUIPath
.
If DDS performance does not meet your needs in your usage scenario, you may require a customized algorithm template for better results. In this case, please contact our experienced Technical Support Team to discuss your requirements. They will help tailor a suitable template for you, which you can then apply by updating templateFilePath
.
By default, cameraEnhancerUIPath
points to a file hosted on the jsDelivr CDN:
https://cdn.jsdelivr.net/npm/[email protected]/dist/document-scanner.ui.html.
This file defines the UI for DocumentScannerView
. However, since files on the CDN cannot be modified directly, you need to use a local version to customize the UI. cameraEnhancerUIPath
is used to specify the local version.
Steps to Customize the UI for DocumentScannerView
- Follow the instructions in Build from Source to obtain the source files for DDS.
- Edit
/src/document-scanner.ui.html
to apply your customizations. Build the project to generate the updated file in
/dist/document-scanner.ui.html
:npm run build
Update the configuration to use the local file instead of the CDN version:
const documentScanner = new Dynamsoft.DocumentScanner({ license: "YOUR_LICENSE_KEY_HERE", // Replace with your actual scannerViewConfig: { cameraEnhancerUIPath: "../dist/document-scanner.ui.html", // Use the local file }, });
API Reference:
Customizing the Scanning Region
We can customize the scanning region in the viewfinder with the scanRegion
property in the configuration object:
interface ScanRegion {
ratio: {
width: number;
height: number;
};
regionBottomMargin: number; // Bottom margin calculated in pixel
style: {
strokeWidth: number;
strokeColor: string;
};
}
API Reference:
Here is how the scanning region is set:
- 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. - Translate the rectangular up by the number of pixels specified by
regionBottomMargin
. - 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:
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
Consider the following configuration interface used for customizing the DocumentCorrectionView
:
interface DocumentCorrectionViewConfig {
container?: HTMLElement;
toolbarButtonsConfig?: DocumentCorrectionViewToolbarButtonsConfig;
onFinish?: (result: DocumentScanResult) => void;
}
container
is covered in Workflow Customization, we’ll look at the other two properties below.
Styling Buttons
The toolbarButtonsConfig
property, of type DocumentCorrectionViewToolbarButtonsConfig
, customizes the appearance and functionality of the UI buttons. Here is its definition:
type ToolbarButtonConfig = Pick<ToolbarButton, "icon" | "label" | "isHidden">;
interface DocumentCorrectionViewToolbarButtonsConfig {
fullImage?: ToolbarButtonConfig;
detectBorders?: ToolbarButtonConfig;
apply?: ToolbarButtonConfig;
}
We can use it to change the icon and label of each of the three UI buttons individually or even hide them. Below is an example that sets a custom label and image icon for the “Detect Borders” button and hides the “fullImage” button:
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
correctionViewConfig: {
toolbarButtonsConfig: {
fullImage: {
isHidden: true
},
detectBorders: {
icon: "path/to/new_icon.png", // Change to the actual path of the new icon
label: "Custom Label"
}
}
}
});
API Reference:
Customizing Apply Button Callback
The onFinish
callback is triggered after the user’s corrections have been applied. For example, the code below displays the corrected image in a resultContainer
after the user clicks “Apply”:
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
correctionViewConfig: {
onFinish: (result) => {
const canvas = result.correctedImageResult.toCanvas();
resultContainer.appendChild(canvas);
}
}
});
API Reference:
DocumentResultView
Configuration
Consider the following configuration interface used for customizing the DocumentResultView
:
interface DocumentResultViewConfig {
container?: HTMLElement;
toolbarButtonsConfig?: DocumentResultViewToolbarButtonsConfig;
onDone?: (result: DocumentResult) => Promise<void>;
onUpload?: (result: DocumentResult) => Promise<void>;
}
Like with DocumentCorrectionView
, we’ll look at toolbarButtonsConfig
, onDone
and onUpload
.
Styling Buttons
The toolbarButtonsConfig
property, of type DocumentResultViewToolbarButtonsConfig
, customizes the appearance and functionality of the UI buttons. Here is its definition:
type ToolbarButtonConfig = Pick<ToolbarButton, "icon" | "label" | "isHidden">;
interface interface DocumentResultViewToolbarButtonsConfig {
retake?: ToolbarButtonConfig;
correct?: ToolbarButtonConfig;
share?: ToolbarButtonConfig;
upload?: ToolbarButtonConfig;
done?: ToolbarButtonConfig;
}
We can use it to change the icon and label of each of the three UI buttons individually or even hide them. Below is an example that sets a custom label and image icon for the “retake” button and hides the “share” button:
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
resultViewConfig: {
toolbarButtonsConfig: {
retake: {
icon: "path/to/new_icon.png", // Change to the actual path of the new icon
label: "Custom Label"
},
share: {
isHidden: true
}
}
}
});
API Reference:
Customizing the “Done” Button Callback
The onDone
callback is triggered when the “Done” button is pressed. For example, the code below displays the result image in a resultContainer
after the user clicks “Done”:
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
resultViewConfig: {
onDone: async (result) =>
{
const canvas = result.correctedImageResult.toCanvas();
resultContainer.appendChild(canvas);
}
}
});
API Reference:
Customizing the “Upload” Button
The onUpload
callback is triggered when the “Upload” button is pressed. Note that the Upload button only appears if a callback function is defined for onUpload
; otherwise, the button remains hidden.
The following example demonstrates how to upload the result image to a server:
If you followed the steps in Build from Source and are still using the predefined Express server setup, the following upload code will work correctly. The image will be uploaded directly to the dev server as “uploadedFile.png”. See the server configuration details in /dev-server/index.js
.
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual
resultViewConfig: {
onUpload: async (result) => {
const host = window.location.origin;
const blob = await result.correctedImageResult.toBlob();
// Create form data
const formData = new FormData();
formData.append("uploadFile", blob, "uploadedFile.png");
// Upload file
const response = await fetch(
`${host}/upload`, // Change this to your actual upload URL
{
method: "POST",
body: formData,
}
);
},
},
});
API Reference:
Self-Hosting Resource Files
By default, DDS relies on a CDN for resources such as .wasm
engine files. If you require a fully offline setup, follow these steps:
These steps are based on Build from Source, meaning that all DDS source files must be available on your local machine.
Update the Engine Resource Paths and the UI Path:
In this case, we reference local resource files that are copied during the build process. See Modify the Build Script for details. However, you can also reference your own copies, such as files hosted on your own server. If you need assistance, feel free to contact us.
const documentScanner = new Dynamsoft.DocumentScanner({
license: "YOUR_LICENSE_KEY_HERE",
scannerViewConfig: {
cameraEnhancerUIPath: "./dist/document-scanner.ui.html", // Use the local file
},
engineResourcePaths: {
std: "./dist/libs/dynamsoft-capture-vision-std/dist/",
dip: "./dist/libs/dynamsoft-image-processing/dist/",
core: "./dist/libs/dynamsoft-core/dist/",
license: "./dist/libs/dynamsoft-license/dist/",
cvr: "./dist/libs/dynamsoft-capture-vision-router/dist/",
ddn: "./dist/libs/dynamsoft-document-normalizer/dist/",
},
});
API Reference:
Modify the Build Script
Update the scripts
section in package.json
to automatically copy the libraries during the build process:
"scripts": {
"serve": "node dev-server/index.js",
"build": "rollup -c && npm run copy-libs",
"copy-libs": "npx mkdirp dist/libs && npx cpx \"node_modules/dynamsoft-*/**/*\" dist/libs/ --dereference",
"build:production": "rollup -c --environment BUILD:production"
},
Build the Project
Build the project by running:
npm run build
Serve the Project Locally
Start the local development server by running:
npm run serve
Once the server is running, open the application in a browser using the address provided in the terminal output.
Now, all required files will be served locally without relying on a CDN.
- Certain legacy web application servers may lack support for the
application/wasm
mimetype for .wasm files. To address this, you have two options:- To work properly, the SDK requires a few engine files, which are relatively large and may take quite a few seconds to download. We recommend that you set a longer cache time for these engine files, to maximize the performance of your web application.
Cache-Control: max-age=31536000
Reference: Cache-Control.
Next Step
DDS is a fully functional, ready-to-use document scanning SDK with built-in UI layouts. However, to extend its capabilities for multi-page and multi-document processing, as well as advanced editing features, we developed Mobile Web Capture (MWC).
Read on to learn how to use this web-based wrapper SDK in the MWC Getting Started Guide.