From ec6438cce728d492c19a50e8bf49433a5e1a698a Mon Sep 17 00:00:00 2001 From: DMGithubPublisher Date: Tue, 6 May 2025 10:30:24 +0800 Subject: [PATCH] update to internal commit f13074fe --- _data/full_tree.yml | 5 +- _data/product_version.yml | 9 +- api/document-scanner-private-v3.0.md | 733 ++++++++++++++++++ api/document-scanner-v3.0.md | 342 ++++++++ api/document-scanner.md | 35 +- api/index-v3.0.md | 27 + api/index.md | 2 + api/mobile-web-capture-v3.0.md | 641 +++++++++++++++ api/mobile-web-capture.md | 50 +- api/relatedapi-v3.0.md | 17 + gettingstarted/adddependency.md | 3 +- gettingstarted/helloworld-v1.1.md | 7 +- guides/document-scanner-v3.0.md | 637 +++++++++++++++ guides/document-scanner.md | 293 +++++-- guides/index-v3.0.md | 19 + guides/index.md | 10 +- .../mobile-web-capture-customization-v3.0.md | 564 ++++++++++++++ guides/mobile-web-capture-customization.md | 50 +- guides/mobile-web-capture-v3.0.md | 239 ++++++ guides/mobile-web-capture.md | 89 ++- introduction/index-v3.0.md | 181 +++++ introduction/index.md | 13 +- 22 files changed, 3809 insertions(+), 157 deletions(-) create mode 100644 api/document-scanner-private-v3.0.md create mode 100644 api/document-scanner-v3.0.md create mode 100644 api/index-v3.0.md create mode 100644 api/mobile-web-capture-v3.0.md create mode 100644 api/relatedapi-v3.0.md create mode 100644 guides/document-scanner-v3.0.md create mode 100644 guides/index-v3.0.md create mode 100644 guides/mobile-web-capture-customization-v3.0.md create mode 100644 guides/mobile-web-capture-v3.0.md create mode 100644 introduction/index-v3.0.md diff --git a/_data/full_tree.yml b/_data/full_tree.yml index c4c97fc..c87f50e 100644 --- a/_data/full_tree.yml +++ b/_data/full_tree.yml @@ -4,5 +4,6 @@ tree_file_list: - sidelist-api.html - sidelist-releasenotes.html - sidelist-full-tree.html - - + - sidelist-apis-v2.0.html + - sidelist-full-tree.v2.0.html + - sidelist-introduction-v2.0.html \ No newline at end of file diff --git a/_data/product_version.yml b/_data/product_version.yml index d8bede5..0e57e44 100644 --- a/_data/product_version.yml +++ b/_data/product_version.yml @@ -1,12 +1,9 @@ useGroupedVersion: true version_info_list: - - value: latest version(3.0) + - value: latest version(3.1) + - value: 3.0 - value: 2.0 - value: 1.x child: - - 1.1 - - - - \ No newline at end of file + - 1.1 \ No newline at end of file diff --git a/api/document-scanner-private-v3.0.md b/api/document-scanner-private-v3.0.md new file mode 100644 index 0000000..8d28eba --- /dev/null +++ b/api/document-scanner-private-v3.0.md @@ -0,0 +1,733 @@ + + + + + + + + + \ No newline at end of file diff --git a/api/document-scanner-v3.0.md b/api/document-scanner-v3.0.md new file mode 100644 index 0000000..70c530c --- /dev/null +++ b/api/document-scanner-v3.0.md @@ -0,0 +1,342 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Dynamsoft Document Scanner - API Reference +keywords: Documentation, Mobile Web Capture, Dynamsoft Document Scanner, API, APIs +breadcrumbText: API References +description: Dynamsoft Document Scanner - API Reference +--- + +# Dynamsoft Document Scanner API Reference + +The `DocumentScanner` class handles the document scanning process, including image capture, correction, and result display. + + + +## Constructor +### DocumentScanner +#### Syntax +```typescript +new DocumentScanner(config: DocumentScannerConfig) +``` + +#### Parameters +- `config` *([DocumentScannerConfig](#documentscannerconfig))* : Configuration settings for the scanner, including license, container, view settings and more. + +#### Example + +```html +
+``` + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + scannerViewConfig: { + container: document.getElementById("myDocumentScannerViewContainer") // Use this container for the scanner view + } +}); +``` + +## Methods + +### launch() + +Starts the **document scanning workflow**. + +#### Syntax +```typescript +launch(): Promise +``` + +#### Returns +- A `Promise` resolving to a `DocumentResult` object. + +#### Example +```typescript +const result = await documentScanner.launch(); + +if (result?.correctedImageResult) { + resultContainer.innerHTML = ""; + const canvas = result.correctedImageResult.toCanvas(); + resultContainer.appendChild(canvas); +} else { + resultContainer.innerHTML = "

No image scanned. Please try again.

"; +} +``` + +### dispose() + +Cleans up resources and hides UI components. + +#### Syntax +```typescript +dispose(): void +``` + +#### Example +```typescript +documentScanner.dispose(); +console.log("Scanner resources released."); +``` + +## Configuration Interfaces +### DocumentScannerConfig + +#### Syntax +```typescript +interface DocumentScannerConfig { + license?: string; + container?: HTMLElement | string; + scannerViewConfig?: DocumentScannerViewConfig; + resultViewConfig?: DocumentResultViewConfig; + correctionViewConfig?: DocumentCorrectionViewConfig; + templateFilePath?: string; + utilizedTemplateNames?: UtilizedTemplateNames; + engineResourcePaths: EngineResourcePaths; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `license` | `string` | The license key for using the `DocumentScanner`. | +| `container` | `HTMLElement \| string` | The container element or selector for the `DocumentScanner` UI. | +| `scannerViewConfig` | `DocumentScannerViewConfig` | Configuration settings for the scanner view. | +| `resultViewConfig` | `DocumentResultViewConfig` | Configuration settings for the result view. | +| `correctionViewConfig` | `DocumentCorrectionViewConfig` | Configuration settings for the correction view. | +| `templateFilePath` | `string` | The file path to the document template used for scanning. | +| `utilizedTemplateNames` | `UtilizedTemplateNames` | Specifies detection and correction templates. | +| `engineResourcePaths` | `EngineResourcePaths` | Paths to the necessary resources for the scanning engine. | + +#### Example +```typescript +const config = { + 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/", + }, +}; +``` + +### DocumentScannerViewConfig + +Configures the scanner view for capturing documents. + +#### Syntax +```typescript +interface DocumentScannerViewConfig { + cameraEnhancerUIPath?: string; + container?: HTMLElement; +} +``` + +#### Properties + +| Property | Type | Description | +| ---------------------- | ------------- | ------------------------------------------------------------ | +| `cameraEnhancerUIPath` | `string` | Path to the UI (`.html` template file) for the scanner view. | +| `container` | `HTMLElement` | The container element for the scanner view. | + +#### Example + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace with your actual license key + scannerViewConfig: { + cameraEnhancerUIPath: "../dist/document-scanner.ui.html", // Use the local file + }, +}); +``` + +### DocumentCorrectionViewConfig + +Configures the correction view for adjusting scanned documents, including toolbar buttons and event handlers for completion. + +#### Syntax +```typescript +interface DocumentCorrectionViewConfig { + container?: HTMLElement; + toolbarButtonsConfig?: DocumentCorrectionViewToolbarButtonsConfig; + onFinish?: (result: DocumentResult) => void; +} +``` + +#### Properties + +| Property | Type | Description | +| ---------------------- | -------------------------------------------- | --------------------------------------------------------- | +| `container` | `HTMLElement` | The container element for the correction view. | +| `toolbarButtonsConfig` | `DocumentCorrectionViewToolbarButtonsConfig` | Configuration for toolbar buttons in the correction view. | +| `onFinish` | `(result: DocumentResult) => void` | Callback function triggered when correction is finished. | + +#### Example + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + correctionViewConfig: { + onFinish: (result) => { + const canvas = result.correctedImageResult.toCanvas(); + resultContainer.appendChild(canvas); + } + } +}); +``` + +### DocumentResultViewConfig + +Configures the result view for reviewing scanned documents, including toolbar buttons and event handlers for uploads and completion. + +#### Syntax +```typescript +interface DocumentResultViewConfig { + container?: HTMLElement; + toolbarButtonsConfig?: DocumentResultViewToolbarButtonsConfig; + onDone?: (result: DocumentResult) => Promise; + onUpload?: (result: DocumentResult) => Promise; +} +``` + +#### Properties + +| Property | Type | Description | +| ---------------------- | ------------------------------------------- | ----------------------------------------------------------- | +| `container` | `HTMLElement` | The container element for the result view. | +| `toolbarButtonsConfig` | `DocumentResultViewToolbarButtonsConfig` | Configuration for toolbar buttons in the result view. | +| `onDone` | `(result: DocumentResult) => Promise` | Callback function triggered when scanning is done. | +| `onUpload` | `(result: DocumentResult) => Promise` | Callback function triggered when uploading the scan result. | + +#### Example +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + resultViewConfig: { + onDone: async (result) => + { + const canvas = result.correctedImageResult.toCanvas(); + resultContainer.appendChild(canvas); + } + } +}); +``` + +### DocumentResult + +Represents the output of a scan, including the original and corrected images, detected boundaries, and scan status. + +#### Syntax +```typescript +interface DocumentResult { + status: ResultStatus; + correctedImageResult?: NormalizedImageResultItem | DSImageData; + originalImageResult?: OriginalImageResultItem["imageData"]; + detectedQuadrilateral?: Quadrilateral; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------------------ | ------------------------------------------------------------ | +| `status` | `ResultStatus` | The status of the document scan (success, failed, canceled). | +| `originalImageResult` | `OriginalImageResultItem["imageData"]` | The original captured image before correction. | +| `correctedImageResult` | `NormalizedImageResultItem \| DSImageData` | The processed (corrected) image. | +| `detectedQuadrilateral` | `Quadrilateral` | The detected document boundaries. | + +## Toolbar Button Configurations + +### ToolbarButtonConfig + +A simplified configuration type for toolbar buttons. + +#### Syntax +```typescript +export type ToolbarButtonConfig = Pick<"icon" | "label" | "isHidden">; +``` + +#### Properties + +| Property | Type | Description | +| ---------- | -------------------- | ----------------------------------- | +| `icon` | `string` | The icon displayed on the button. | +| `label` | `string` | The text label for the button. | +| `isHidden` | `boolean` (optional) | Determines if the button is hidden. | + +#### Example +```typescript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + correctionViewConfig: { + toolbarButtonsConfig: { + fullImage: { + isHidden: true + }, + detectBorders: { + icon: "path/to/new_icon.png", // Change to the actual path of the new icon + label: "Custom Label" + } + } + } +}); +``` + +### Configurable Buttons Per Each View + +#### DocumentCorrectionViewToolbarButtonsConfig +```typescript +interface DocumentCorrectionViewToolbarButtonsConfig { + fullImage?: ToolbarButtonConfig; + detectBorders?: ToolbarButtonConfig; + apply?: ToolbarButtonConfig; +} +``` + +#### DocumentCorrectionViewToolbarButtonsConfig + +```typescript +interface DocumentCorrectionViewToolbarButtonsConfig { + fullImage?: ToolbarButtonConfig; + detectBorders?: ToolbarButtonConfig; + apply?: ToolbarButtonConfig; +} +``` + +#### DocumentResultViewToolbarButtonsConfig + +```typescript +interface DocumentResultViewToolbarButtonsConfig { + retake?: ToolbarButtonConfig; + correct?: ToolbarButtonConfig; + share?: ToolbarButtonConfig; + upload?: ToolbarButtonConfig; + done?: ToolbarButtonConfig; +} +``` + diff --git a/api/document-scanner.md b/api/document-scanner.md index 70c530c..98ec472 100644 --- a/api/document-scanner.md +++ b/api/document-scanner.md @@ -31,14 +31,16 @@ The `DocumentScanner` class handles the document scanning process, including ima --> ## Constructor + ### DocumentScanner + #### Syntax ```typescript new DocumentScanner(config: DocumentScannerConfig) ``` #### Parameters -- `config` *([DocumentScannerConfig](#documentscannerconfig))* : Configuration settings for the scanner, including license, container, view settings and more. +- `config` ([`DocumentScannerConfig`](#documentscannerconfig)) : Configuration settings for the scanner, including license, container, view settings and more. #### Example @@ -57,7 +59,7 @@ const documentScanner = new Dynamsoft.DocumentScanner({ ## Methods -### launch() +### `launch()` Starts the **document scanning workflow**. @@ -82,7 +84,7 @@ if (result?.correctedImageResult) { } ``` -### dispose() +### `dispose()` Cleans up resources and hides UI components. @@ -98,7 +100,8 @@ console.log("Scanner resources released."); ``` ## Configuration Interfaces -### DocumentScannerConfig + +### `DocumentScannerConfig` #### Syntax ```typescript @@ -145,7 +148,7 @@ const config = { }; ``` -### DocumentScannerViewConfig +### `DocumentScannerViewConfig` Configures the scanner view for capturing documents. @@ -159,10 +162,16 @@ interface DocumentScannerViewConfig { #### Properties -| Property | Type | Description | -| ---------------------- | ------------- | ------------------------------------------------------------ | -| `cameraEnhancerUIPath` | `string` | Path to the UI (`.html` template file) for the scanner view. | -| `container` | `HTMLElement` | The container element for the scanner view. | +| Property | Type | Description | +| --------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------- | +| `templateFilePath` | `string` | Path to a Capture Vision template for scanning configuration. | +| `cameraEnhancerUIPath` | `string` | Path to the UI (`.html` template file) for the scanner view. | +| `container` | `HTMLElement` | The container element for the scanner view. | +| `utilizedTemplateNames` | `UtilizedTemplateNames` | Capture Vision template names for detection and correction. | +| `enableAutoCropMode` | `boolean` | The default auto-crop mode state. | +| `enableSmartCaptureMode` | `boolean` | The default smart capture mode state. | +| `scanRegion` | `ScanRegion` | Defines the region within the viewport to detect documents. | +| `minVerifiedFramesForAutoCapture` | `number` | The minimum number of camera frames to detect document boundaries on Smart Capture mode. | #### Example @@ -175,7 +184,7 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` -### DocumentCorrectionViewConfig +### `DocumentCorrectionViewConfig` Configures the correction view for adjusting scanned documents, including toolbar buttons and event handlers for completion. @@ -210,7 +219,7 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` -### DocumentResultViewConfig +### `DocumentResultViewConfig` Configures the result view for reviewing scanned documents, including toolbar buttons and event handlers for uploads and completion. @@ -247,7 +256,7 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` -### DocumentResult +### `DocumentResult` Represents the output of a scan, including the original and corrected images, detected boundaries, and scan status. @@ -272,7 +281,7 @@ interface DocumentResult { ## Toolbar Button Configurations -### ToolbarButtonConfig +### `ToolbarButtonConfig` A simplified configuration type for toolbar buttons. diff --git a/api/index-v3.0.md b/api/index-v3.0.md new file mode 100644 index 0000000..a45a99a --- /dev/null +++ b/api/index-v3.0.md @@ -0,0 +1,27 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: true +title: Mobile Web Capture - API Reference Index +keywords: Documentation, Mobile Web Capture, API Index +description: Mobile Web Capture Documentation API Reference Index +--- + +# API Reference Index + +## Scan Single-Page Documents + +If you need to scan single-page documents and do not require handling PDF files (import or export), you only need **Dynamsoft Document Scanner (DDS)**, a component of **Mobile Web Capture (MWC)**. You can find its API reference here: + +- [Dynamsoft Document Scanner API Reference]({{ site.api }}document-scanner.html) + +> See it in action with the [Dynamsoft Document Scanner Demo](https://demo.dynamsoft.com/document-scanner/). + +## Scan Multi-Page Documents + +If you need to handle multi-page documents, PDF files, annotations, and more, you will need the full-featured **Mobile Web Capture (MWC)**. You can find its API reference here: + +- [Mobile Web Capture API Reference]({{ site.api }}mobile-web-capture.html) + +> See it in action with the [Mobile Web Capture Demo](https://demo.dynamsoft.com/mobile-web-capture/). diff --git a/api/index.md b/api/index.md index a45a99a..b69240a 100644 --- a/api/index.md +++ b/api/index.md @@ -16,6 +16,7 @@ If you need to scan single-page documents and do not require handling PDF files - [Dynamsoft Document Scanner API Reference]({{ site.api }}document-scanner.html) +> [!TIP] > See it in action with the [Dynamsoft Document Scanner Demo](https://demo.dynamsoft.com/document-scanner/). ## Scan Multi-Page Documents @@ -24,4 +25,5 @@ If you need to handle multi-page documents, PDF files, annotations, and more, yo - [Mobile Web Capture API Reference]({{ site.api }}mobile-web-capture.html) +> [!TIP] > See it in action with the [Mobile Web Capture Demo](https://demo.dynamsoft.com/mobile-web-capture/). diff --git a/api/mobile-web-capture-v3.0.md b/api/mobile-web-capture-v3.0.md new file mode 100644 index 0000000..d72ff75 --- /dev/null +++ b/api/mobile-web-capture-v3.0.md @@ -0,0 +1,641 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Dynamsoft Mobile Web Capture - API Reference +keywords: Documentation, Mobile Web Capture, Dynamsoft Document Scanner, API, APIs +breadcrumbText: API Reference +description: Mobile Web Capture API Reference +--- + +# Mobile Web Capture API Reference + +The `MobileWebCapture` class manages document scanning, viewing, and management. + + + +## Constructor + +### MobileWebCapture + +#### Syntax +```typescript +constructor(config: MobileWebCaptureConfig) +``` + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------ | ---------------------------------------------------- | +| `config` | `MobileWebCaptureConfig` | The configuration settings for **MobileWebCapture**. | + +#### Example +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + documentScannerConfig: { + showResultView: false, + showCorrectionView: false, + }, +}); +(async () => { + // Launch the Mobile Web Capture Instance + const fileName = `New_Document_${Date.now().toString().slice(-5)}`; + await mobileWebCapture.launch(fileName); +})(); +``` + +## Methods + +### launch() + +Starts the **Mobile Web Capture** workflow. + +#### Syntax +```typescript +launch(file?: File | string): Promise +``` + +#### Parameters + +| Parameter | Type | Description | +| --------- | --------------------------- | ------------------------------------------ | +| `file` | `File \| string` (optional) | A file or document name to open at launch. | + +#### Throws +- An error if **MWC** is already running. + +#### Example +```typescript +await mobileWebCapture.launch(); +console.log("MWC launched successfully."); +``` + +**Launching with a File** + +```html + +``` + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key +}); +document.getElementById("initialFile").onchange = async function () { + const files = Array.from(this.files || []); + if (files.length) { + // Launch the Mobile Web Capture instance with an initial file + if (mobileWebCapture.hasLaunched) + await mobileWebCapture.dispose(); + await mobileWebCapture.launch(files[0]); + } +}; +``` + +### dispose() + +Cleans up resources and closes the `MobileWebCapture` instance. + +#### Syntax +```typescript +dispose(): Promise +``` + +#### Example +```typescript +await mobileWebCapture.dispose(); +console.log("MWC resources released."); +``` + +## Properties + +### hasLaunched + +Returns whether the `MobileWebCapture` instance is running. + +#### Syntax +```typescript +readonly hasLaunched: boolean; +``` + +```html + +``` + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key +}); +document.getElementById("initialFile").onchange = async function () { + const files = Array.from(this.files || []); + if (files.length) { + // Launch the Mobile Web Capture instance with an initial file + if (mobileWebCapture.hasLaunched) + await mobileWebCapture.dispose(); + await mobileWebCapture.launch(files[0]); + } +}; +``` + +## Configuration Interfaces + +### MobileWebCaptureConfig + +#### Syntax +```typescript +interface MobileWebCaptureConfig { + license?: string; + container?: HTMLElement | string; + exportConfig?: ExportConffig; + showLibraryView?: boolean; + onClose?: () => void; + + // View Configs + libraryViewConfig?: LibraryViewConfig; + documentViewConfig?: DocumentViewConfig; + pageViewConfig?: PageViewConfig; + transferViewConfig?: TransferViewConfig; + historyViewConfig?: HistoryViewConfig; + + // DDS Config + documentScannerConfig?:DocumentScannerConfig +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ----------------------- | -------------------------------------------------------------------------------- | +| `license` | `string` | The license key for using **Mobile Web Capture (MWC)**. | +| `container` | `HTMLElement \| string` | The container element or selector for rendering the `MobileWebCapture` instance. | +| `exportConfig` | `ExportConfig` | Configuration for exporting captured documents. | +| `showLibraryView` | `boolean` | Determines if the **LibraryView** is shown (default: `true`). | +| `onClose` | `() => void` | Callback function triggered when the `MobileWebCapture` instance is closed. | +| `libraryViewConfig` | `LibraryViewConfig` | Configuration for the **LibraryView**. | +| `documentViewConfig` | `DocumentViewConfig` | Configuration for the **DocumentView**. | +| `pageViewConfig` | `PageViewConfig` | Configuration for the **PageView**. | +| `transferViewConfig` | `TransferViewConfig` | Configuration for the **TransferView**. | +| `historyViewConfig` | `HistoryViewConfig` | Configuration for the **HistoryView**. | +| `documentScannerConfig` | `DocumentScannerConfig` | Configuration for the built-in **DocumentScanner**. | + +##### See Also + +- [DocumentScannerConfig](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) + +#### Example + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + ddvResourcePath: "./dist/libs/dynamsoft-document-viewer/dist/", + documentScannerConfig: { + 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/", + }, + }, +}); +``` + +### LibraryViewConfig + +#### Syntax +```typescript +interface LibraryViewConfig { + emptyContentConfig?: EmptyContentConfig; + toolbarButtonsConfig?: LibraryToolbarButtonsConfig; +} +``` + +#### Properties + +| Property | Type | Description | +| ---------------------- | ----------------------------- | ---------------------------------------------------------------------------- | +| `emptyContentConfig` | `EmptyContentConfig` | Configuration for the content displayed on the empty **LibraryView** screen. | +| `toolbarButtonsConfig` | `LibraryToolbarButtonsConfig` | Configuration for the toolbar buttons in **LibraryView**. | + +#### Example 1: Display A Message In An Empty Library + +By default, the `LibraryView` displays the following when empty: + +![Empty Library View](https://www.dynamsoft.com/mobile-web-capture/docs/assets/imgs/empty-library-view.png) + +You can customize its appearance using the `emptyContentConfig` property. + +```html +
Create Your First Document!
+``` + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + showLibraryView: true, // Enable LibraryView + libraryViewConfig: { + emptyContentConfig: document.getElementById("customizedLibraryViewContent"), + }, +}); +``` + +#### Example 2: Disable Upload in LibraryView + +When `exportConfig.uploadToServer` is defined and `showLibraryView` is `true`, an **Upload** button will appears in `LibraryView`. The following example demonstrates how to hide the button. + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + showLibraryView: true // Enable LibraryView + libraryViewConfig: { + toolbarButtonsConfig: { + upload: { + isHidden: true + } + } + } +}); +``` + +### DocumentViewConfig + +#### Syntax +```typescript +interface DocumentViewConfig { + emptyContentConfig?: EmptyContentConfig; + toolbarButtonsConfig?: DocumentToolbarButtonsConfig; +} +``` + +#### Properties + +| Property | Type | Description | +| ---------------------- | ------------------------------ | ----------------------------------------------------------------------------- | +| `emptyContentConfig` | `EmptyContentConfig` | Configuration for the content displayed on the empty **DocumentView** screen. | +| `toolbarButtonsConfig` | `DocumentToolbarButtonsConfig` | Configuration for the toolbar buttons in **DocumentView**. | + +#### Example 1: Display A Message In An Empty Document + +By default, the `DocumentView` displays the following when empty: + +![Empty Document View](https://www.dynamsoft.com/mobile-web-capture/docs/assets/imgs/empty-document-view.png) + +You can customize its appearance using the `emptyContentConfig` property. + +```html +
Start Your Document!
+``` + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + documentViewConfig: { + emptyContentConfig: document.getElementById("customizedDocViewContent"), + }, +}); +``` + +#### Example 2: Disable Upload in DocumentView + +When `exportConfig.uploadToServer` is defined, the **Upload** button appears in both `DocumentView` and `PageView`. The following example demonstrates how to disable this feature by hiding it in `DocumentView`, ensuring that the **Upload** button only appears in `PageView`. + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + documentViewConfig: { + toolbarButtonsConfig: { // Note that there are two upload buttons in DocumentView + uploadDocument: { + isHidden: true + }, + uploadImage: { + isHidden: true + } + } + } +}); +``` + +#### Example 3: Update the Button Icon + +If you don't like a button's icon, you can customize it. The following example shows how to change the icon of the **"Share Document"** button: + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + documentViewConfig: { + toolbarButtonsConfig: { // Note that there are two upload buttons in DocumentView + shareDocument: { + icon: "path/to/new_icon.png", // Change to the actual path of the new icon + label: "Custom Label" + } + } + } +}); +``` + +### PageViewConfig + +#### Syntax +```typescript +interface PageViewConfig { + toolbarButtonsConfig?: PageViewToolbarButtonsConfig; + annotationToolbarLabelConfig?: DDVAnnotationToolbarLabelConfig; +} +``` + +#### Properties + +| Property | Type | Description | +| ------------------------------ | --------------------------------- | -------------------------------------------------- | +| `toolbarButtonsConfig` | `PageViewToolbarButtonsConfig` | Configuration for toolbar buttons in **PageView**. | +| `annotationToolbarLabelConfig` | `DDVAnnotationToolbarLabelConfig` | Configuration for annotation toolbar labels. | + +#### Example 1: Disable Upload in PageView + +In this example, we'll demonstrate how to hide the **Upload** button in `PageView` even when `exportConfig.uploadToServer` is defined, ensuring that it only appears in `DocumentView`. + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + pageViewConfig: { + toolbarButtonsConfig: { + upload: { + isHidden: true + } + } + } +}); +``` + +#### Example 2: Change the Labels of the Annotation Toolbar Buttons + +You can customize the labels of the annotation toolbar buttons as follows: + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + pageViewConfig: { + annotationToolbarLabelConfig: { + TextBoxAnnotation: "Input Text", + }, + } +}); +``` + +### HistoryViewConfig + +#### Syntax +```typescript +interface HistoryViewConfig { + emptyContentConfig?: EmptyContentConfig; + toolbarButtonsConfig?: HistoryToolbarButtonsConfig; +} +``` + +#### Properties + +| Property | Type | Description | +| ---------------------- | ----------------------------- | ---------------------------------------------------------------------------- | +| `emptyContentConfig` | `EmptyContentConfig` | Configuration for the content displayed on the empty **HistoryView** screen. | +| `toolbarButtonsConfig` | `HistoryToolbarButtonsConfig` | Configuration for the toolbar buttons in **HistoryView**. | + +### TransferViewConfig + +#### Syntax +```typescript +interface TransferViewConfig { + toolbarButtonsConfig?: TransferToolbarButtonsConfig; +} +``` + +#### Properties + +| Property | Type | Description | +| ---------------------- | ------------------------------ | ---------------------------------------------------------- | +| `toolbarButtonsConfig` | `TransferToolbarButtonsConfig` | Configuration for the toolbar buttons in **TransferView**. | + +## Toolbar Button Configurations + +### ToolbarButtonConfig + +A simplified configuration type for toolbar buttons. + +#### Syntax +```typescript +export type ToolbarButtonConfig = Pick<"icon" | "label" | "isHidden">; +``` + +#### Properties + +| Property | Type | Description | +| ---------- | -------------------- | ----------------------------------- | +| `icon` | `string` | The icon displayed on the button. | +| `label` | `string` | The text label for the button. | +| `isHidden` | `boolean` (optional) | Determines if the button is hidden. | + +#### Example +```typescript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + documentViewConfig: { + toolbarButtonsConfig: { // Note that there are two upload buttons in DocumentView + uploadDocument: { + isHidden: true + }, + uploadImage: { + isHidden: true + } + } + } +}); +``` + +### Configurable Buttons Per Each View + +#### LibraryToolbarButtonsConfig +```typescript +interface LibraryToolbarButtonsConfig { + newDoc?: ToolbarButtonConfig; + capture?: ToolbarButtonConfig; + import?: ToolbarButtonConfig; + uploads?: ToolbarButtonConfig; + + // Selected Toolbar Options + delete?: ToolbarButtonConfig; + print?: ToolbarButtonConfig; + share?: ToolbarButtonConfig; + upload?: ToolbarButtonConfig; + back?: ToolbarButtonConfig; +} +``` + +#### DocumentToolbarButtonsConfig +```typescript +interface DocumentToolbarButtonsConfig { + backToLibrary?: ToolbarButtonConfig; + capture?: ToolbarButtonConfig; + import?: ToolbarButtonConfig; + shareDocument?: ToolbarButtonConfig; + uploadDocument?: ToolbarButtonConfig; + manage?: ToolbarButtonConfig; + + // Selected Toolbar Options + copyTo?: ToolbarButtonConfig; + moveTo?: ToolbarButtonConfig; + selectAll?: ToolbarButtonConfig; + deleteImage?: ToolbarButtonConfig; + shareImage?: ToolbarButtonConfig; + uploadImage?: ToolbarButtonConfig; + back?: ToolbarButtonConfig; +} +``` + +#### PageViewToolbarButtonsConfig +```typescript +interface PageViewToolbarButtonsConfig { + back?: ToolbarButtonConfig; + delete?: ToolbarButtonConfig; + addPage?: ToolbarButtonConfig; + upload?: ToolbarButtonConfig; + share?: ToolbarButtonConfig; + edit?: ToolbarButtonConfig; + + // Edit mode toolbar + crop?: ToolbarButtonConfig; + rotate?: ToolbarButtonConfig; + filter?: ToolbarButtonConfig; + annotate?: ToolbarButtonConfig; + done?: ToolbarButtonConfig; +} + +``` + +#### HistoryToolbarButtonsConfig +```typescript +interface HistoryToolbarButtonsConfig { + back?: ToolbarButtonConfig; +} +``` + +#### TransferToolbarButtonsConfig +```typescript +interface TransferToolbarButtonsConfig { + cancel?: ToolbarButtonConfig; + action?: ToolbarButtonConfig; +} +``` + +## Assisting Interfaces + +### ExportConfig + +The `ExportConfig` interface defines methods for handling document export functionality, such as uploading, downloading, deleting files from a server, and managing the upload success process. This allows full customization of how documents are exported and managed in your application. + +#### Properties + +##### uploadToServer + +Uploads a document to the server. The function receives the document's file name and its binary data (`Blob`). It returns a `Promise` that resolves with `void` or an `UploadedDocument` object. +> **Important:** Returning `{ status: "success" }` in this function is required to trigger [onUploadSuccess](#onuploadsuccess) + +###### **Type** +```typescript +(fileName: string, blob: Blob) => Promise +``` + +##### downloadFromServer + +Downloads a document from the server. The function receives an `UploadedDocument` object and returns a `Promise` that resolves once the download is complete. + +###### **Type** +```typescript +(doc: UploadedDocument) => Promise +``` + +##### deleteFromServer + +Deletes a document from the server. The function receives an `UploadedDocument` object and returns a `Promise` that resolves once the deletion is successful. + +###### **Type** +```typescript +(doc: UploadedDocument) => Promise +``` + +##### onUploadSuccess + +Called after a successful upload. It receives the file name, file type, the current view (`EnumMWCViews`), and the binary data (`Blob`). The function should return a `Promise` that resolves to `true` if the `MobileWebCapture` instance should close after uploading or `false` if it should remain open. +> **Important:** Returning `{ status: "success" }` in [uploadToServer](#uploadtoserver) is required to trigger this function. + +###### **Type** +```typescript +(fileName: string, fileType: string, view: EnumMWCViews, blob: Blob) => Promise +``` + +#### Example Usage + +```javascript +const uploadToServer = async (fileName, blob) => { + const host = window.location.origin; + // Create form data + const formData = new FormData(); + formData.append("uploadFile", blob, fileName); + // Upload file + const response = await fetch( + `${host}/upload`, // Change this to your actul upload URL + { + method: "POST", + body: formData, + } + ); + if (response.status === 200) { + // **IMPORTANT**: Returning { status: "success" } is required to trigger onUploadSuccess. + return { + status: "success", + }; + } else { + return { + status: "failed", + }; + } +}; +const onUploadSuccess = async (fileName) => { + console.log(`${fileName} uploaded successfully!`); + return true; // Exit the Mobile Web Capture Instance +}; +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + exportConfig: { + uploadToServer, + onUploadSuccess, + }, +}); +(async () => { + // Launch the Mobile Web Capture Instance + const fileName = `New_Document_${Date.now().toString().slice(-5)}`; + await mobileWebCapture.launch(fileName); +})(); +``` \ No newline at end of file diff --git a/api/mobile-web-capture.md b/api/mobile-web-capture.md index d72ff75..b233674 100644 --- a/api/mobile-web-capture.md +++ b/api/mobile-web-capture.md @@ -36,7 +36,7 @@ The `MobileWebCapture` class manages document scanning, viewing, and management. ## Constructor -### MobileWebCapture +### `MobileWebCapture` #### Syntax ```typescript @@ -67,7 +67,7 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ ## Methods -### launch() +### `launch()` Starts the **Mobile Web Capture** workflow. @@ -112,7 +112,7 @@ document.getElementById("initialFile").onchange = async function () { }; ``` -### dispose() +### `dispose()` Cleans up resources and closes the `MobileWebCapture` instance. @@ -129,7 +129,7 @@ console.log("MWC resources released."); ## Properties -### hasLaunched +### `hasLaunched` Returns whether the `MobileWebCapture` instance is running. @@ -159,7 +159,7 @@ document.getElementById("initialFile").onchange = async function () { ## Configuration Interfaces -### MobileWebCaptureConfig +### `MobileWebCaptureConfig` #### Syntax ```typescript @@ -224,7 +224,7 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ }); ``` -### LibraryViewConfig +### `LibraryViewConfig` #### Syntax ```typescript @@ -281,7 +281,7 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ }); ``` -### DocumentViewConfig +### `DocumentViewConfig` #### Syntax ```typescript @@ -357,7 +357,7 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ }); ``` -### PageViewConfig +### `PageViewConfig` #### Syntax ```typescript @@ -406,7 +406,7 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ }); ``` -### HistoryViewConfig +### `HistoryViewConfig` #### Syntax ```typescript @@ -423,7 +423,7 @@ interface HistoryViewConfig { | `emptyContentConfig` | `EmptyContentConfig` | Configuration for the content displayed on the empty **HistoryView** screen. | | `toolbarButtonsConfig` | `HistoryToolbarButtonsConfig` | Configuration for the toolbar buttons in **HistoryView**. | -### TransferViewConfig +### `TransferViewConfig` #### Syntax ```typescript @@ -440,7 +440,7 @@ interface TransferViewConfig { ## Toolbar Button Configurations -### ToolbarButtonConfig +### `ToolbarButtonConfig` A simplified configuration type for toolbar buttons. @@ -476,7 +476,7 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ ### Configurable Buttons Per Each View -#### LibraryToolbarButtonsConfig +#### `LibraryToolbarButtonsConfig` ```typescript interface LibraryToolbarButtonsConfig { newDoc?: ToolbarButtonConfig; @@ -493,7 +493,7 @@ interface LibraryToolbarButtonsConfig { } ``` -#### DocumentToolbarButtonsConfig +#### `DocumentToolbarButtonsConfig` ```typescript interface DocumentToolbarButtonsConfig { backToLibrary?: ToolbarButtonConfig; @@ -514,7 +514,7 @@ interface DocumentToolbarButtonsConfig { } ``` -#### PageViewToolbarButtonsConfig +#### `PageViewToolbarButtonsConfig` ```typescript interface PageViewToolbarButtonsConfig { back?: ToolbarButtonConfig; @@ -534,14 +534,14 @@ interface PageViewToolbarButtonsConfig { ``` -#### HistoryToolbarButtonsConfig +#### `HistoryToolbarButtonsConfig` ```typescript interface HistoryToolbarButtonsConfig { back?: ToolbarButtonConfig; } ``` -#### TransferToolbarButtonsConfig +#### `TransferToolbarButtonsConfig` ```typescript interface TransferToolbarButtonsConfig { cancel?: ToolbarButtonConfig; @@ -551,23 +551,25 @@ interface TransferToolbarButtonsConfig { ## Assisting Interfaces -### ExportConfig +### `ExportConfig` The `ExportConfig` interface defines methods for handling document export functionality, such as uploading, downloading, deleting files from a server, and managing the upload success process. This allows full customization of how documents are exported and managed in your application. #### Properties -##### uploadToServer +##### `uploadToServer` Uploads a document to the server. The function receives the document's file name and its binary data (`Blob`). It returns a `Promise` that resolves with `void` or an `UploadedDocument` object. -> **Important:** Returning `{ status: "success" }` in this function is required to trigger [onUploadSuccess](#onuploadsuccess) + +> [!IMPORTANT] +> Returning `{ status: "success" }` in this function is required to trigger [onUploadSuccess](#onuploadsuccess) ###### **Type** ```typescript (fileName: string, blob: Blob) => Promise ``` -##### downloadFromServer +##### `downloadFromServer` Downloads a document from the server. The function receives an `UploadedDocument` object and returns a `Promise` that resolves once the download is complete. @@ -576,7 +578,7 @@ Downloads a document from the server. The function receives an `UploadedDocument (doc: UploadedDocument) => Promise ``` -##### deleteFromServer +##### `deleteFromServer` Deletes a document from the server. The function receives an `UploadedDocument` object and returns a `Promise` that resolves once the deletion is successful. @@ -585,10 +587,12 @@ Deletes a document from the server. The function receives an `UploadedDocument` (doc: UploadedDocument) => Promise ``` -##### onUploadSuccess +##### `onUploadSuccess` Called after a successful upload. It receives the file name, file type, the current view (`EnumMWCViews`), and the binary data (`Blob`). The function should return a `Promise` that resolves to `true` if the `MobileWebCapture` instance should close after uploading or `false` if it should remain open. -> **Important:** Returning `{ status: "success" }` in [uploadToServer](#uploadtoserver) is required to trigger this function. + +> [!IMPORTANT] +> Returning `{ status: "success" }` in [uploadToServer](#uploadtoserver) is required to trigger this function. ###### **Type** ```typescript diff --git a/api/relatedapi-v3.0.md b/api/relatedapi-v3.0.md new file mode 100644 index 0000000..739aeb4 --- /dev/null +++ b/api/relatedapi-v3.0.md @@ -0,0 +1,17 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: true +title: Mobile Web Capture - Related API Reference +keywords: Documentation, Mobile Web Capture, Related API Reference +breadcrumbText: Related API Reference +description: Mobile Web Capture Documentation Related API Reference +permalink: /api/relatedapi.html +--- + +# Related API Reference + +## [Dynamsoft Document Viewer](https://www.dynamsoft.com/document-viewer/docs/api/index.html) + +## [Dynamsoft Document Normalizer](https://www.dynamsoft.com/document-normalizer/docs/web/programming/javascript/api-reference/index.html) \ No newline at end of file diff --git a/gettingstarted/adddependency.md b/gettingstarted/adddependency.md index e7d7383..30aa3af 100644 --- a/gettingstarted/adddependency.md +++ b/gettingstarted/adddependency.md @@ -130,7 +130,6 @@ This is usually only required with frameworks like Angular or React, etc. where Dynamsoft.Core.CoreModule.engineResourcePaths.dce = "https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@4.0.2/dist/"; ``` - + \ No newline at end of file diff --git a/gettingstarted/helloworld-v1.1.md b/gettingstarted/helloworld-v1.1.md index 305e9f6..b0c4c92 100644 --- a/gettingstarted/helloworld-v1.1.md +++ b/gettingstarted/helloworld-v1.1.md @@ -406,7 +406,12 @@ document.getElementById("restore").onclick = () => { ``` +## Download the whole project +- Hello World - [Github](https://github.com/Dynamsoft/mobile-web-capture/tree/master/samples/hello-world/hello-world) \| [Run](https://dynamsoft.github.io/mobile-web-capture/samples/hello-world/hello-world/) + - Angular App - [Github](https://github.com/Dynamsoft/mobile-web-capture/tree/master/samples/hello-world/hello-world-angular) + - React App - [Github](https://github.com/Dynamsoft/mobile-web-capture/tree/master/samples/hello-world/hello-world-react) + - Vue3 App - [Github](https://github.com/Dynamsoft/mobile-web-capture/tree/master/samples/hello-world/hello-world-vue3) ## More use cases @@ -414,4 +419,4 @@ We provide some samples which demonstrate the popular use cases, for example, re Please refer to the [Use Case]({{ site.codegallery }}usecases/index.html) section. -## [Demo](https://demo.dynamsoft.com/mobile-web-capture/) +## [Demo](https://demo.dynamsoft.com/mobile-web-capture/) \ No newline at end of file diff --git a/guides/document-scanner-v3.0.md b/guides/document-scanner-v3.0.md new file mode 100644 index 0000000..8578249 --- /dev/null +++ b/guides/document-scanner-v3.0.md @@ -0,0 +1,637 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Dynamsoft Document Scanner - Scan Single-Page Documents +keywords: Documentation, Mobile Web Capture, Dynamsoft Document Scanner, +description: Dynamsoft Document Scanner User Guide +--- + +# Scan Single-Page Documents with Dynamsoft Document Scanner + +> Prerequisite: Read the [Introduction](https://www.dynamsoft.com/mobile-web-capture/docs/introduction/index.html) 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](https://demo.dynamsoft.com/document-scanner/). + +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 through our [customer portal](https://www.dynamsoft.com/customer/license/trialLicense?product=mwc&source=guide). The trial license can be renewed twice, offering a total of two months of free access. + +> **DDS** and **MWC** share the same license keys. 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](https://www.dynamsoft.com/company/contact/). + +## Quick Start + +The first step in using **DDS** is to obtain its library files. You can acquire them from one of the following sources: + +1. [**GitHub**](https://github.com/Dynamsoft/document-scanner-javascript) – Contains the source files for the **DDS** SDK, which can be compiled into library files. +2. [**npm**](https://www.npmjs.com/package/dynamsoft-document-scanner) – Provides precompiled library files via npm for easier installation. +3. [**CDN**](https://cdn.jsdelivr.net/npm/dynamsoft-document-scanner) – 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: + +1. **Build from Source** – Download the source files from GitHub and compile the resource script yourself. +2. **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 [GitHub Repository](https://github.com/Dynamsoft/document-scanner-javascript), compiles them into a distributable package, and then runs a *ready-made* Hello World sample page included in the repository: + +1. Download **DDS** from [GitHub](https://github.com/Dynamsoft/document-scanner-javascript) as a compressed folder. +2. Extract the contents of the archive, and open the extracted directory in a code editor. +3. Set your [license key](#get-a-trial-license) in the Hello World sample: + 1. Open the Hello World sample at ([`/samples/hello-world.html`](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/samples/hello-world.html)). + 2. Search for `"YOUR_LICENSE_KEY_HERE"`, then replace it with your actual license key. +4. Install project dependencies + In the terminal, navigate to the project root directory and run: + ```bash + npm install + ``` +5. Build the project + After installing dependencies, build the project by running: + ```bash + npm run build + ``` +6. Serve the project locally + Start the local server by running: + ```bash + 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`](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/dev-server/index.js). + +### Option 2: Use Precompiled Script + +Since the **DDS** library files are published on [npm](https://www.npmjs.com/package/dynamsoft-document-scanner), it's easy to reference them from a CDN. + +To use the precompiled script, simply include the following URL in a ` +``` + +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`](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/samples/hello-world.html) file mentioned in the [Build from Source](#option-1-build-from-source) section, except for the script source. +> +> **Don't forget** to replace `"YOUR_LICENSE_KEY_HERE"` with your actual license key. + +```html + + + + + + Dynamsoft Document Scanner - Hello World + + + +

Dynamsoft Document Scanner

+
+ + + +``` + +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 VSCode extension](https://marketplace.visualstudio.com/items?itemName=yandeu.five-server). 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 Github](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/samples/hello-world.html). + +### Reference DDS + +```html + + + + + + Dynamsoft Document Scanner - Hello World + + + +``` + +In this step, DDS is referenced using a relative local path in the `` section of the HTML. + +```html + +``` + +Alternatively, the script can be referenced from a CDN: + +```html + +``` + +**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. + +> ⚠**IMPORTANT**: 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](#self-hosting-resource-files). + +### Instantiate DDS + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key +}); +``` + +API Reference: [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) + +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](#example-1-confine-documentscanner-ui-to-a-specific-container). + +> A license key is required for instantiation. + +### Launch DDS + +```javascript +const result = await documentScanner.launch(); +``` + +API Reference: [`launch()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#launch) + +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 to `DocumentCorrectionView` to review detected document boundaries and make any necessary adjustments before applying corrections. Afterward, they proceed to `DocumentResultView`. +> +> For Option 3: The `DocumentCorrectionView` step is skipped. Image correction is applied automatically, and the user is taken directly to `DocumentResultView`. + +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 `
` in the ``: + +```html + +

Dynamsoft Document Scanner

+
+``` + +API Reference: [`DocumentResult`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentresult) + +The following code clears the result container and displays the scanned result as a canvas: + +```javascript +if (result?.correctedImageResult) { + resultContainer.innerHTML = ""; + const canvas = result.correctedImageResult.toCanvas(); + resultContainer.appendChild(canvas); +} else { + resultContainer.innerHTML = "

No image scanned. Please try again.

"; +} +``` + +## 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: + +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`: Configures where or not to show `DocumentCorrectionView`. +4. `showResultView`: Configures where or not to show `DocumentResultView`. +5. `scannerViewConfig`: Configures 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`. +6. `correctionViewConfig`: Configures the document correction view. + 1. `container`: The HTML container for the `DocumentCorrectionView`. + 2. `toolbarButtonsConfig`: Configures the appearance and labels of the buttons for the `DocumentCorrectionView` UI. + 3. `onFinish`: Handler called when the user clicks the "Apply" button. +7. `resultViewConfig`: Configures the result view with the following properties: + 1. `container`: The HTML container for the `DocumentResultView`. + 2. `toolbarButtonsConfig`: Configures 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. +8. `templateFilePath`: Path to a Capture Vision template. Typically not needed as the default template is used. +9. `utilizedTemplateNames`: Template names for detection and correction. Typically not needed as the default template is used. +10. `engineResourcePaths`: Paths to extra resources such as `.wasm` engine files. + +We will discuss two main methods of customizing **DDS** with `DocumentScannerConfig`: + +1. **Workflow Customization**: Through container definitions. +2. **View-Based Customization**: Through configuration objects. + +The customization examples below will build on the Hello World code from the [previous section](#option-2-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 +}); +``` + +### 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, **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. +> Note that 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 + } +}); +``` + +#### Example 2: Show DocumentScannerView Only + +In some cases, `DocumentResultView` and `DocumentCorrectionView` may not be needed, so they can be hidden: + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + showResultView: false, + showCorrectionView: false +}); +``` + +#### 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. + +```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") + } +}); +``` + +### 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 + +Consider the following configuration interface used for customizing the `DocumentScannerView`: + +```javascript +interface DocumentScannerViewConfig { + container?: HTMLElement; + templateFilePath?: string; + cameraEnhancerUIPath?: string; +} +``` + +We previously covered `container` in [Workflow Customization](#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](https://www.dynamsoft.com/company/contact/) 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/dynamsoft-document-scanner@1.1.1/dist/document-scanner.ui.html](https://cdn.jsdelivr.net/npm/dynamsoft-document-scanner@1.1.1/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` +1. Follow the instructions in [Build from Source](#option-1-build-from-source) to obtain the source files for **DDS**. +2. Edit `/src/document-scanner.ui.html` to apply your customizations. +3. Build the project to generate the updated file in `/dist/document-scanner.ui.html`: + + ```bash + 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.html", // Use the local file + }, + }); + ``` + +#### `DocumentCorrectionView` Configuration + +Consider the following configuration interface used for customizing the `DocumentCorrectionView`: + +```javascript +interface DocumentCorrectionViewConfig { + container?: HTMLElement; + toolbarButtonsConfig?: DocumentCorrectionViewToolbarButtonsConfig; + onFinish?: (result: DocumentScanResult) => void; +} +``` + +`container` is covered in [Workflow Customization](#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: + +```javascript +type ToolbarButtonConfig = Pick; +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: + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + correctionViewConfig: { + toolbarButtonsConfig: { + fullImage: { + isHidden: true + }, + detectBorders: { + icon: "path/to/new_icon.png", // Change to the actual path of the new icon + label: "Custom Label" + } + } + } +}); +``` + +##### 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": + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + correctionViewConfig: { + onFinish: (result) => { + const canvas = result.correctedImageResult.toCanvas(); + resultContainer.appendChild(canvas); + } + } +}); +``` + +#### `DocumentResultView` Configuration + +Consider the following configuration interface used for customizing the `DocumentResultView`: + +```javascript +interface DocumentResultViewConfig { + container?: HTMLElement; + toolbarButtonsConfig?: DocumentResultViewToolbarButtonsConfig; + onDone?: (result: DocumentResult) => Promise; + onUpload?: (result: DocumentResult) => Promise; +} +``` + +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: + +```javascript +type ToolbarButtonConfig = Pick; +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: + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + resultViewConfig: { + toolbarButtonsConfig: { + retake: { + icon: "path/to/new_icon.png", // Change to the actual path of the new icon + label: "Custom Label" + }, + share: { + isHidden: true + } + } + } +}); +``` + +##### 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": + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + resultViewConfig: { + onDone: async (result) => + { + const canvas = result.correctedImageResult.toCanvas(); + resultContainer.appendChild(canvas); + } + } +}); +``` +##### 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](#option-1-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`](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/dev-server/index.js). + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + 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 actul upload URL + { + method: "POST", + body: formData, + } + ); + }, + }, +}); +``` + +### 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](#option-1-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](#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](https://www.dynamsoft.com/company/contact/). + +```javascript +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/", + }, +}); +``` + +#### Modify the Build Script + +Update the `scripts` section in `package.json` to automatically copy the libraries during the build process: + +```json +"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: + +```bash +npm run build +``` + +#### Serve the Project Locally + +Start the local development server by running: +```bash +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. + +⚠**IMPORTANT NOTE**: + +* Certain legacy web application servers may lack support for the `application/wasm` mimetype for .wasm files. To address this, you have two options: + 1. Upgrade your web application server to one that supports the `application/wasm` mimetype. + 2. Manually define the mimetype on your server. You can refer to the guides for [apache](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Apache_Configuration_htaccess#media_types_and_character_encodings) / [IIS](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/staticcontent/mimemap) / [nginx](https://www.nginx.com/resources/wiki/start/topics/examples/full/#mime-types). + +* 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/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](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture.html). diff --git a/guides/document-scanner.md b/guides/document-scanner.md index fba90ce..261826e 100644 --- a/guides/document-scanner.md +++ b/guides/document-scanner.md @@ -10,10 +10,12 @@ description: Dynamsoft Document Scanner User Guide # Scan Single-Page Documents with Dynamsoft Document Scanner +> [!TIP] > Prerequisite: Read the [Introduction](https://www.dynamsoft.com/mobile-web-capture/docs/introduction/index.html) 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. +> [!NOTE] > See it in action with the [Dynamsoft Document Scanner Demo](https://demo.dynamsoft.com/document-scanner/). This guide walks you through building a web application that scans single-page documents using **DDS**, with pre-defined configurations. @@ -42,8 +44,13 @@ This guide walks you through building a web application that scans single-page d ### Get a Trial License -If you haven't got a trial license for **DDS**, you can request one through our [customer portal](https://www.dynamsoft.com/customer/license/trialLicense?product=mwc&source=guide). The trial license can be renewed twice, offering a total of two months of free access. +If you haven't got a trial license for **DDS**, you can request one here: +{% include trialLicense.html %} + + The trial license can be renewed twice, offering a total of two months of free access. + +> [!IMPORTANT] > **DDS** and **MWC** share the same license keys. If you already have a **DDS** license, you can use it for **MWC**, and vice versa. ### Get a Full License @@ -65,21 +72,20 @@ You can choose one of the following methods to set up a Hello World page: ### Option 1: Build from Source -This method retrieves all **DDS** source files from its [GitHub Repository](https://github.com/Dynamsoft/document-scanner-javascript), compiles them into a distributable package, and then runs a *ready-made* Hello World sample page included in the repository. - -Follow these steps: +This method retrieves all **DDS** source files from its [GitHub Repository](https://github.com/Dynamsoft/document-scanner-javascript), compiles them into a distributable package, and then runs a *ready-made* Hello World sample page included in the repository: 1. Download **DDS** from [GitHub](https://github.com/Dynamsoft/document-scanner-javascript) as a compressed folder. -2. Extract the contents of the archive. -3. Enter the license key you received in [Get a Trial License](#get-a-trial-license) in the Hello World sample. - > In your code editor, open the Hello World sample located at [`/samples/hello-world.html`](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/samples/hello-world.html). Search for `"YOUR_LICENSE_KEY_HERE"` and replace it with your actual license key. +2. Extract the contents of the archive, and open the extracted directory in a code editor. +3. Set your [license key](#get-a-trial-license) in the Hello World sample: + 1. Open the Hello World sample at ([`/samples/hello-world.html`](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/samples/hello-world.html)). + 2. Search for `"YOUR_LICENSE_KEY_HERE"`, then replace it with your actual license key. 4. Install project dependencies In the terminal, navigate to the project root directory and run: ```bash npm install ``` 5. Build the project - After the dependencies are installed, build the project by running: + After installing dependencies, build the project by running: ```bash npm run build ``` @@ -89,6 +95,8 @@ Follow these steps: 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`. + +> [!TIP] > See the server configuration details in [`/dev-server/index.js`](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/dev-server/index.js). ### Option 2: Use Precompiled Script @@ -97,12 +105,15 @@ Since the **DDS** library files are published on [npm](https://www.npmjs.com/pac To use the precompiled script, simply include the following URL in a ` + ``` Below is the complete Hello World sample page that uses this precompiled script from a CDN. + +> [!TIP] > The code is identical to the [`/samples/hello-world.html`](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/samples/hello-world.html) file mentioned in the [Build from Source](#option-1-build-from-source) section, except for the script source. -> + +> [!WARNING] > **Don't forget** to replace `"YOUR_LICENSE_KEY_HERE"` with your actual license key. ```html @@ -112,7 +123,7 @@ Below is the complete Hello World sample page that uses this precompiled script Dynamsoft Document Scanner - Hello World - +

Dynamsoft Document Scanner

@@ -144,7 +155,7 @@ Below is the complete Hello World sample page that uses this precompiled script 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 [Five Server VSCode extension](https://marketplace.visualstudio.com/items?itemName=yandeu.five-server). 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`. +If you are using VS Code, a quick and easy way to serve the project is using the [Live Server (Five Server) VSCode extension](https://marketplace.visualstudio.com/items?itemName=yandeu.five-server). 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. @@ -152,7 +163,8 @@ Alternatively, you can use other methods like `IIS` or `Apache` to serve the pro Let’s walk through the code in the Hello World Sample to understand how it works. -> Instead of using the code above, an alternative way to view the full code is by visiting the [Dynamsoft Document Scanner Hello World Sample](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/samples/hello-world.html). +> [!TIP] +> You can also view the full code by visiting the [Dynamsoft Document Scanner Hello World Sample on Github](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/samples/hello-world.html). ### Reference DDS @@ -165,7 +177,7 @@ Let’s walk through the code in the Hello World Sample to understand how it wor Dynamsoft Document Scanner - Hello World ``` @@ -179,12 +191,13 @@ In this step, DDS is referenced using a relative local path in the `` sect Alternatively, the script can be referenced from a CDN: ```html - + ``` **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. -> ⚠**IMPORTANT**: 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](#self-hosting-resource-files). +> [!WARNING] +> 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](#self-hosting-resource-files). ### Instantiate DDS @@ -194,11 +207,14 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` -API Reference: [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) -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](#example-1-confine-documentscanner-ui-to-a-specific-container) +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](#example-1-confine-documentscanner-ui-to-a-specific-container). -> A license key is required for the instantiation. +> [!WARNING] +> A license key is required for instantiation. ### Launch DDS @@ -206,7 +222,9 @@ This step creates the **DDS** UI, which, occupies the entire visible area of the const result = await documentScanner.launch(); ``` -API Reference: [`launch()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#launch) +API Reference: + +- [`launch()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#launch) 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: @@ -214,6 +232,7 @@ This step launches the user into the document scanning workflow, beginning in th * 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. +> [!TIP] > For Options 1 & 2: The user is directed to `DocumentCorrectionView` to review detected document boundaries and make any necessary adjustments before applying corrections. Afterward, they proceed to `DocumentResultView`. > > For Option 3: The `DocumentCorrectionView` step is skipped. Image correction is applied automatically, and the user is taken directly to `DocumentResultView`. @@ -230,7 +249,9 @@ The workflow returns a scanned image object of type `CorrectedImageResult`. To d
``` -API Reference: [`DocumentResult`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentresult) +API Reference: + +- [`DocumentResult`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentresult) The following code clears the result container and displays the scanned result as a canvas: @@ -248,17 +269,23 @@ if (result?.correctedImageResult) { This section builds on the Hello World sample to demonstrate how to configure **DDS**, typically by adjusting the `DocumentScannerConfig` object. -### DocumentScannerConfig Overview +### `DocumentScannerConfig` Overview -`DocumentScannerConfig` is the primary configuration object for customizing **DDS**. It includes the following properties: +[`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) is the primary configuration object for customizing **DDS**. 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`: Configures where or not to show `DocumentCorrectionView`. -4. `showResultView`: Configures where or not to show `DocumentResultView`. +3. `showCorrectionView`: Configures whether or not to show `DocumentCorrectionView`. +4. `showResultView`: Configures whether or not to show `DocumentResultView`. 5. `scannerViewConfig`: Configures 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`: sets the default Auto-Crop mode. + 4. `enableSmartCaptureMode`: sets the default Smart Capture mode. + 5. `scanRegion`: sets the scan region within the viewfinder for document scanning. + 6. `minVerifiedFramesForSmartCapture`: sets minimum number of camera frames to detect document boundaries on Smart Capture mode. + 7. `showSubfooter`: sets the visibility of the mode selector menu. + 8. `showPoweredByDynamsoft`: sets the visibility of the Dynamsoft branding message. 6. `correctionViewConfig`: Configures the document correction view. 1. `container`: The HTML container for the `DocumentCorrectionView`. 2. `toolbarButtonsConfig`: Configures the appearance and labels of the buttons for the `DocumentCorrectionView` UI. @@ -268,14 +295,14 @@ This section builds on the Hello World sample to demonstrate how to configure ** 2. `toolbarButtonsConfig`: Configures 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. -8. `templateFilePath`: Path to a Capture Vision template. Typically not needed as the default template is used. +8. `templateFilePath`: Path to a Capture Vision template for scanning configuration. Typically not needed as the default template is used. 9. `utilizedTemplateNames`: Template names for detection and correction. Typically not needed as the default template is used. 10. `engineResourcePaths`: Paths to extra resources such as `.wasm` engine files. We will discuss two main methods of customizing **DDS** with `DocumentScannerConfig`: -1. **Workflow Customization**: Through container definitions. -2. **View-Based Customization**: Through configuration objects. +1. [**Workflow Customization**](#workflow-customization): Through container definitions. +2. [**View-Based Customization**](#view-based-customization): Through configuration objects. The customization examples below will build on the Hello World code from the [previous section](#option-2-use-precompiled-script). The only change required is adjusting the constructor argument. @@ -303,7 +330,9 @@ In this case, **DDS** automatically creates "containers" for its **Views**. In t #### 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. -> Note that containers assigned to its constituent **Views** will be ignored. + +> [!NOTE] +> Containers assigned to its constituent **Views** will be ignored. ```html
@@ -319,7 +348,12 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` -#### Example 2: Show DocumentScannerView Only +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +- [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) + +#### Example 2: Only Show `DocumentScannerView` In some cases, `DocumentResultView` and `DocumentCorrectionView` may not be needed, so they can be hidden: @@ -331,6 +365,11 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +- [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) + #### 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. @@ -356,12 +395,88 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +- [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) + +#### 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: + +```html + +``` + +Then get the input file as a `File` object, and pass that file object to `launch()` DDS with: + +```js +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 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. + +> [!IMPORTANT] +> `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: + +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` + +> [!NOTE] +> 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: + +```js +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + scannerViewConfig: { + enableAutoCropMode: true, + enableSmartCaptureMode: true, + false, +}}); +``` + +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +- [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) +- [`DocumentScannerViewConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerviewconfig) + ### 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`: ```javascript @@ -374,10 +489,11 @@ interface DocumentScannerViewConfig { We previously covered `container` in [Workflow Customization](#workflow-customization), and changing `templateFilePath` is usually not required. Now, let's focus on `cameraEnhancerUIPath`. +> [!TIP] > 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](https://www.dynamsoft.com/company/contact/) 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/dynamsoft-document-scanner@1.1.1/dist/document-scanner.ui.html](https://cdn.jsdelivr.net/npm/dynamsoft-document-scanner@1.1.1/dist/document-scanner.ui.html). +[https://cdn.jsdelivr.net/npm/dynamsoft-document-scanner@1.2/dist/document-scanner.ui.html](https://cdn.jsdelivr.net/npm/dynamsoft-document-scanner@1.2/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. @@ -400,6 +516,54 @@ This file defines the UI for `DocumentScannerView`. However, since files on the }); ``` +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +- [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) +- [`DocumentScannerViewConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerviewconfig) + +##### Customizing the Scanning Region + +We can customize the scanning region in the viewfinder with the `scanRegion` property in the configuration object: + +```js +interface ScanRegion { + ratio: { + width: number; + height: number; + }; + regionBottomMargin: number; // Bottom margin calculated in pixel + style: { + strokeWidth: number; + strokeColor: string; + }; +} +``` + +Here is how the scanning region is set: + +1. The `ratio` property sets the height-to-width of the scanning region rectangle, then scales the rectangle up to fit within the viewfinder. +2. Translate this rectangle 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: + +```js +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`: @@ -446,6 +610,12 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +- [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) +- [`DocumentCorrectionViewConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentcorrectionviewconfig) + ##### 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": @@ -462,6 +632,12 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +- [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) +- [`DocumentCorrectionViewConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentcorrectionviewconfig) + #### `DocumentResultView` Configuration Consider the following configuration interface used for customizing the `DocumentResultView`: @@ -512,6 +688,12 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +- [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) +- [`DocumentResultViewConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentresultviewconfig) + ##### 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": @@ -528,12 +710,20 @@ const documentScanner = new Dynamsoft.DocumentScanner({ } }); ``` + +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +- [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) +- [`DocumentResultViewConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentresultviewconfig) + ##### 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: +> [!TIP] > If you followed the steps in [Build from Source](#option-1-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`](https://github.com/Dynamsoft/document-scanner-javascript/blob/main/dev-server/index.js). ```javascript @@ -548,7 +738,7 @@ const documentScanner = new Dynamsoft.DocumentScanner({ formData.append("uploadFile", blob, "uploadedFile.png"); // Upload file const response = await fetch( - `${host}/upload`, // Change this to your actul upload URL + `${host}/upload`, // Change this to your actual upload URL { method: "POST", body: formData, @@ -559,13 +749,21 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +- [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) +- [`DocumentResultViewConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentresultviewconfig) + ### 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: +> [!TIP] > These steps are based on [Build from Source](#option-1-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: +> [!TIP] > In this case, we reference local resource files that are copied during the build process. See [Modify the Build Script](#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](https://www.dynamsoft.com/company/contact/). ```javascript @@ -585,6 +783,12 @@ const documentScanner = new Dynamsoft.DocumentScanner({ }); ``` +API Reference: + +- [`DocumentScanner()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscanner) +- [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerconfig) +- [`DocumentScannerViewConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/document-scanner.html#documentscannerviewconfig) + #### Modify the Build Script Update the `scripts` section in `package.json` to automatically copy the libraries during the build process: @@ -617,19 +821,18 @@ Once the server is running, open the application in a browser using the address Now, all required files will be **served locally** without relying on a CDN. -⚠**IMPORTANT NOTE**: - -* Certain legacy web application servers may lack support for the `application/wasm` mimetype for .wasm files. To address this, you have two options: - 1. Upgrade your web application server to one that supports the `application/wasm` mimetype. - 2. Manually define the mimetype on your server. You can refer to the guides for [apache](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Apache_Configuration_htaccess#media_types_and_character_encodings) / [IIS](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/staticcontent/mimemap) / [nginx](https://www.nginx.com/resources/wiki/start/topics/examples/full/#mime-types). - -* 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control). +>[!IMPORTANT] +>* Certain legacy web application servers may lack support for the `application/wasm` mimetype for .wasm files. To address this, you have two options: +> 1. Upgrade your web application server to one that supports the `application/wasm` mimetype. +> 2. Manually define the mimetype on your server. You can refer to the guides for [apache](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Apache_Configuration_htaccess#media_types_and_character_encodings) / [IIS](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/staticcontent/mimemap) / [nginx](https://www.nginx.com/resources/wiki/start/topics/examples/full/#mime-types). +> +>* 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control). ## Next Step diff --git a/guides/index-v3.0.md b/guides/index-v3.0.md new file mode 100644 index 0000000..108e402 --- /dev/null +++ b/guides/index-v3.0.md @@ -0,0 +1,19 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: true +title: Mobile Web Capture - User Guide Index +keywords: Documentation, Mobile Web Capture, Dynamsoft Document Scanner, User Guide Index +description: Mobile Web Capture User Guide Index +--- + +# Mobile Web Capture User Guide Index + +Since **MWC** is built on **DDS** and shares its core functionality, we recommend first reading the following guide to understand single-page capturing powered by **DDS**: + +- [DDS Developer Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/document-scanner.html) + +Once you're familiar with DDS, proceed to the following guide on **MWC** to explore additional features for multi-page document management, editing, and annotation: + +- [MWC Developer Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture.html) diff --git a/guides/index.md b/guides/index.md index 2c0ad1f..108e402 100644 --- a/guides/index.md +++ b/guides/index.md @@ -8,12 +8,12 @@ keywords: Documentation, Mobile Web Capture, Dynamsoft Document Scanner, User Gu description: Mobile Web Capture User Guide Index --- -# Mobile Web Capture User Guide Index +# Mobile Web Capture User Guide Index -Since **MWC** is built on **DDS** and shares its core functionality, we recommend first reading the following guide to understand single-page capturing powered by **DDS**: +Since **MWC** is built on **DDS** and shares its core functionality, we recommend first reading the following guide to understand single-page capturing powered by **DDS**: -- [DDS Developer Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/document-scanner.html) +- [DDS Developer Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/document-scanner.html) -Once you're familiar with **DDS**, proceed to the following guide to explore additional features for multi-page document management, editing, and annotation: +Once you're familiar with DDS, proceed to the following guide on **MWC** to explore additional features for multi-page document management, editing, and annotation: -- [MWC Developer Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture.html) +- [MWC Developer Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture.html) diff --git a/guides/mobile-web-capture-customization-v3.0.md b/guides/mobile-web-capture-customization-v3.0.md new file mode 100644 index 0000000..c7b3577 --- /dev/null +++ b/guides/mobile-web-capture-customization-v3.0.md @@ -0,0 +1,564 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Mobile Web Capture - Scan Multi-Page Documents +keywords: Documentation, Mobile Web Capture, Dynamsoft Document Scanner, +description: Mobile Web Capture User Guide +--- + +# How to Customize Mobile Web Capture + +> **Prerequisites:** +> Read the [MWC Getting Started Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture.html) before proceeding. + +This guide expands on the **Hello World** sample from the **MWC Getting Started Guide** and explores the available customization options. + + + +## MobileWebCaptureConfig Overview + +`MobileWebCaptureConfig` is the primary configuration object for customizing **MWC**. 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. `exportConfig`: Configures functions for handling document export operations. + 1. `uploadToServer`: Specifies a function to upload a file to a server. + 2. `downloadFromServer`: Specifies a function to download a document from the server. + 3. `deleteFromServer`: Specifies a function to delete a document from the server. + 4. `onUploadSuccess`: Specifies a function that is triggered when the upload operation succeeds. +4. `showLibraryView`: Configures where or not this **MWC** instance starts with the `LibraryView`. +5. `onClose`: Specifies a function that is triggered when the user closes this **MWC** instance. +6. `documentScannerConfig`: Configures the behavior of the built-in `DocumentScanner` instance. See the details in [`DocumentScannerConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/guides/document-scanner.html#documentscannerconfig-overview). +7. `libraryViewConfig`: Configures the library view with the following properties: + 1. `emptyContentConfig`: Specifies the content displayed in the library view when it is empty (no document). + 2. `toolbarButtonsConfig`: Configures the buttons in the toolbar of the library view. +8. `documentViewConfig`: Configures the document view with the following properties: + 1. `emptyContentConfig`: Specifies the content displayed in the document view when it is empty (no page). + 2. `toolbarButtonsConfig`: Configures the buttons in the toolbar of the document view. +9. `pageViewConfig`: Configures the page view. + 1. `toolbarButtonsConfig`: Configures the buttons in the toolbar of the page view. + 2. `annotationToolbarLabelConfig`: Configures the labels of the annotation options. +10. `transferViewConfig`: Configures the transfer view. + 1. `toolbarButtonsConfig`: Configures the buttons in the toolbar of the transfer view. +11. `historyViewConfig`: Configures the history view. + 1. `emptyContentConfig`: Specifies the content displayed in the history view when it is empty (no uploads). + 2. `toolbarButtonsConfig`: Configures the button in the toolbar of the history view. +12. `ddvResourcePath`: Paths to extra resources such as `.wasm` engine files and CSS files. + +API Reference: [`MobileWebCaptureConfig`](https://www.dynamsoft.com/mobile-web-capture/docs/api/mobile-web-capture.html#mobilewebcaptureconfig) + +## Overall UI and Workflow Customization + +**MWC** automatically creates containers that fill the entire viewport for its **Views** if none are specified in the configuration. These views come with a predefined workflow. The following demonstrates a few ways to customize the overall UI. + +### Specify the UI Container + +When a container is assigned, **MWC** UI will be confined in that container element: + +```html +
+``` + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + container: document.getElementById("myMobileWebCapture") , // Use this container for the full workflow +}); +(async () => { + // Launch the Mobile Web Capture Instance + const fileName = `New_Document_${Date.now().toString().slice(-5)}`; + await mobileWebCapture.launch(fileName); +})(); +``` + +### Enable the LibraryView + +By default, **MWC** starts with `DocumentView`, disabling `LibraryView`, so only one document is created and managed. Enabling `LibraryView` allows multiple documents. + +> Since **MWC** now starts with `LibraryView`, a document name is no longer required. If specified, `LibraryView` is still enabled, but **MWC** will start with `DocumentView`. + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + showLibraryView: true // Enable LibraryView +}); +(async () => { + // Launch the Mobile Web Capture Instance + await mobileWebCapture.launch(); // No need to specify a document name. +})(); +``` + +On the `LibraryView`, the user can + +1. **New** : Create a new document. +2. **Capture** : Create a new document by capturing the first image for it. +3. **Import** : Create a new document by importing one or multiple images or PDF files. + +The user can also enable the **"Upload"** feature. Check out [Enable File Upload](#enable-file-upload) and [Enable Upload History](#enable-upload-history). When the **Upload History** feature is enabled, the user can + +- **Uploads**: View uploaded documents from this session, download, or delete them. + +### Start by Opening a Document + +By default, **MWC** starts empty. However, you can specify a file to be opened as the initial document. + +```html + +``` + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key +}); +document.getElementById("initialFile").onchange = async function () { + const files = Array.from(this.files || []); + if (files.length) { + // Launch the Mobile Web Capture instance with an initial file + if (mobileWebCapture.hasLaunched) + await mobileWebCapture.dispose(); + await mobileWebCapture.launch(files[0]); + } +}; +``` + +API Reference: +- [`hasLaunched`](https://www.dynamsoft.com/mobile-web-capture/docs/api/mobile-web-capture.html#haslaunched) +- [`dispose`](https://www.dynamsoft.com/mobile-web-capture/docs/api/mobile-web-capture.html#dispose) + +### Scan Directly to Document + +When **capturing** a document, it goes through three views: + +1. **`DocumentScannerView`** +2. **`DocumentCorrectionView`** (optional) +3. **`DocumentResultView`** (optional) + +The latter two views can be skipped to speed up the process. + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + documentScannerConfig: { + showResultView: false, + showCorrectionView: false, + }, +}); +(async () => { + // Launch the Mobile Web Capture Instance + const fileName = `New_Document_${Date.now().toString().slice(-5)}`; + await mobileWebCapture.launch(fileName); +})(); +``` + +### Enable File Upload + +When `exportConfig.uploadToServer` is defined, an **Upload** button appears in both `DocumentView` and `PageView`. +> If `LibraryView` is enabled, the **Upload** button will also appear there. + +The following example demonstrates how to enable file upload and exit the Mobile Web Capture Instance after a successful upload. +> If you followed the steps in [Build from Source](#option-1-build-from-source) and are still using the predefined Express server setup, the following upload code will work correctly. See the server configuration details in [`/dev-server/index.js`](https://github.com/Dynamsoft/mobile-web-capture/blob/main/dev-server/index.js). + +```javascript +const uploadToServer = async (fileName, blob) => { + const host = window.location.origin; + // Create form data + const formData = new FormData(); + formData.append("uploadFile", blob, fileName); + // Upload file + const response = await fetch( + `${host}/upload`, // Change this to your actul upload URL + { + method: "POST", + body: formData, + } + ); + if (response.status === 200) { + // **IMPORTANT**: Returning { status: "success" } is required to trigger onUploadSuccess. + return { + status: "success", + }; + } else { + return { + status: "failed", + }; + } +}; +const onUploadSuccess = async (fileName) => { + console.log(`${fileName} uploaded successfully!`); + return true; // Exit the Mobile Web Capture Instance +}; +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + exportConfig: { + uploadToServer, + onUploadSuccess, + }, +}); +(async () => { + // Launch the Mobile Web Capture Instance + const fileName = `New_Document_${Date.now().toString().slice(-5)}`; + await mobileWebCapture.launch(fileName); +})(); +``` + +> ⚠ **IMPORTANT**: The **Upload** feature is enabled simultaneously in `DocumentView` and `PageView` (and in `LibraryView` if it is enabled). If this is not intended, you can hide the **Upload** button in these **Views**. +> Read more: +> 1. [Disable Upload in DocumentView](#example-2-disable-upload-in-documentview) +> 2. [Disable Upload in PageView](#example-1-disable-upload-in-pageview) +> 3. [Disable Upload in LibraryView](#example-2-disable-upload-in-libraryview) + +### Enable Upload History + +When **File Upload** feature is on and `LibraryView` is enabled, we can enable the **Upload History** feature in the `LibraryView` by defining all the following: +1. `exportConfig.uploadToServer` +2. `exportConfig.downloadFromServer` +3. `exportConfig.deleteFromServer` + +The following example demonstrates how to enable this feature. +> If you followed the steps in [Build from Source](#option-1-build-from-source) and are still using the predefined Express server setup, the following code will work correctly. See the server configuration details in [`/dev-server/index.js`](https://github.com/Dynamsoft/mobile-web-capture/blob/main/dev-server/index.js). + +```javascript +const host = window.location.origin; +const shortSessionID = Math.random().toString(36).substring(2, 12); +const uploadToServer = async (fileName, blob) => { + const formData = new FormData(); + formData.append("uploadFile", blob, fileName); + formData.append("fileName", fileName); + formData.append("sessionID", shortSessionID); + // Upload file + const response = await fetch( + `${host}/upload`, // Change this to your actul upload URL + { + method: "POST", + body: formData, + } + ); + const responseText = await response.text(); + if (!responseText || !responseText.includes("UploadedFileName")) { + throw new Error("Invalid server response"); + } + const serverFileName = responseText.match( + /UploadedFileName:(.+)_(\d+)_(.+)$/ + ); + if (!serverFileName) { + throw new Error("Failed to parse server response"); + } + const [, sessionID, uploadTime, realFileName] = serverFileName; + const downloadUrl = `${host}/download?fileName=${encodeURIComponent( + `${sessionID}_${uploadTime}_${realFileName}` + )}`; + // NOTE: Ensure the object returned contains status, fileName, and downloadUrl + return { + status: "success", + fileName: realFileName, + downloadUrl, + uploadTime, + }; +}; +const deleteFromServer = async (doc) => { + const response = await fetch( + `${host}/delete?fileName=${encodeURIComponent( + `${shortSessionID}_${doc.uploadTime}_${doc.fileName}` + )}`, + { + method: "POST", + } + ); +}; +const downloadFromServer = async (doc) => { + window.open(doc.downloadUrl); +}; +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + showLibraryView: true, // Enable LibraryView + exportConfig: { + uploadToServer, + downloadFromServer, + deleteFromServer, + } +}); +(async () => { + // Launch the Mobile Web Capture Instance + const fileName = `New_Document_${Date.now().toString().slice(-5)}`; + await mobileWebCapture.launch(fileName); +})(); +``` + +## View-Based Customization +### DocumentView Configuration + +Consider the following configuration interface used for customizing the `DocumentView`: + +```javascript +interface DocumentViewConfig { + emptyContentConfig?: EmptyContentConfig; + toolbarButtonsConfig?: DocumentToolbarButtonsConfig; +} +``` + +#### Example 1: Display A Message In An Empty Document + +By default, the `DocumentView` displays the following when empty: + +![Empty Document View](https://www.dynamsoft.com/mobile-web-capture/docs/assets/imgs/empty-document-view.png) + +You can customize its appearance using the `emptyContentConfig` property. + +```html +
Start Your Document!
+``` + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + documentViewConfig: { + emptyContentConfig: document.getElementById("customizedDocViewContent"), + }, +}); +``` + +#### Example 2: Disable Upload in DocumentView + +When `exportConfig.uploadToServer` is defined, the **Upload** button appears in both `DocumentView` and `PageView`. The following example demonstrates how to disable this feature by hiding it in `DocumentView`, ensuring that the **Upload** button only appears in `PageView`. + +> Read more in [Enable File Upload](#enable-file-upload). + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + documentViewConfig: { + toolbarButtonsConfig: { // Note that there are two upload buttons in DocumentView + uploadDocument: { + isHidden: true + }, + uploadImage: { + isHidden: true + } + } + } +}); +``` + +#### Example 3: Update the Button Icon + +If you don't like a button's icon, you can customize it. The following example shows how to change the icon of the **"Share Document"** button: + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + documentViewConfig: { + toolbarButtonsConfig: { // Note that there are two upload buttons in DocumentView + shareDocument: { + icon: "path/to/new_icon.png", // Change to the actual path of the new icon + label: "Custom Label" + } + } + } +}); +``` + +### LibraryView Configuration + +Consider the following configuration interface used for customizing the `LibraryView`: + +```javascript +interface LibraryViewConfig { + emptyContentConfig?: EmptyContentConfig; + toolbarButtonsConfig?: LibraryToolbarButtonsConfig; +} +``` + +#### Example 1: Display A Message In An Empty Library + +By default, the `LibraryView` displays the following when empty: + +![Empty Library View](https://www.dynamsoft.com/mobile-web-capture/docs/assets/imgs/empty-library-view.png) + +You can customize its appearance using the `emptyContentConfig` property. + +```html +
Create Your First Document!
+``` + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + showLibraryView: true, // Enable LibraryView + libraryViewConfig: { + emptyContentConfig: document.getElementById("customizedLibraryViewContent"), + }, +}); +``` + +#### Example 2: Disable Upload in LibraryView + +When `exportConfig.uploadToServer` is defined and `showLibraryView` is `true`, an **Upload** button will appears in `LibraryView`. The following example demonstrates how to hide the button. + +> Read more in [Enable File Upload](#enable-file-upload) & [Enabe Upload History](#enable-upload-history). + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + showLibraryView: true // Enable LibraryView + libraryViewConfig: { + toolbarButtonsConfig: { + upload: { + isHidden: true + } + } + } +}); +``` + +### PageView Configuration + +Consider the following configuration interface used for customizing the `PageView`: + +```javascript +interface PageViewConfig { + toolbarButtonsConfig?: PageViewToolbarButtonsConfig; + annotationToolbarLabelConfig?: DDVAnnotationToolbarLabelConfig; +} +``` + +#### Example 1: Disable Upload in PageView + +In this example, we'll demonstrate how to hide the **Upload** button in `PageView` even when `exportConfig.uploadToServer` is defined, ensuring that it only appears in `DocumentView`. + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + pageViewConfig: { + toolbarButtonsConfig: { + upload: { + isHidden: true + } + } + } +}); +``` + +#### Example 2: Change the Labels of the Annotation Toolbar Buttons + +You can customize the labels of the annotation toolbar buttons as follows: + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + pageViewConfig: { + annotationToolbarLabelConfig: { + TextBoxAnnotation: "Input Text", + }, + } +}); +``` + +### TransferView and HistoryView Configuration + +The configuration follows similar patterns, so we won’t cover them here for brevity. + +## Self-Hosting Resource Files + +By default, **MWC** 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](#option-1-build-from-source), meaning that all **MWC** source files must be available on your local machine. + +#### Update the Resource Paths + +The following code modifies how resource files are referenced: + +> In this case, we reference local resource files that are copied during the build process. See [Modify the Build Script](#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](https://www.dynamsoft.com/company/contact/). + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + ddvResourcePath: "./dist/libs/dynamsoft-document-viewer/dist/", + documentScannerConfig: { + 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/", + }, + }, +}); +``` + +### Modify the Build Script + +Update the `scripts` section in `package.json` to automatically copy the libraries during the build process: + +```json +"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 + +Once all dependencies are installed, build the project by running: + +```bash +npm run build +``` + +### Serve the Project Locally + +Start the local development server by running: +```bash +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. + +⚠**IMPORTANT NOTE**: + +* Certain legacy web application servers may lack support for the `application/wasm` mimetype for .wasm files. To address this, you have two options: + 1. Upgrade your web application server to one that supports the `application/wasm` mimetype. + 2. Manually define the mimetype on your server. You can refer to the guides for [apache](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Apache_Configuration_htaccess#media_types_and_character_encodings) / [IIS](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/staticcontent/mimemap) / [nginx](https://www.nginx.com/resources/wiki/start/topics/examples/full/#mime-types). + +* 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control). + +## Next Step + +Start building your own mobile document capture and management solution with **MWC**! If you encounter any technical issues or have suggestions, feel free to [contact us](https://www.dynamsoft.com/company/contact/). + + diff --git a/guides/mobile-web-capture-customization.md b/guides/mobile-web-capture-customization.md index c7b3577..e3893d0 100644 --- a/guides/mobile-web-capture-customization.md +++ b/guides/mobile-web-capture-customization.md @@ -10,8 +10,8 @@ description: Mobile Web Capture User Guide # How to Customize Mobile Web Capture -> **Prerequisites:** -> Read the [MWC Getting Started Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture.html) before proceeding. +> [!TIP] +> Prerequisites: read the [MWC Getting Started Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture.html) before proceeding. This guide expands on the **Hello World** sample from the **MWC Getting Started Guide** and explores the available customization options. @@ -98,6 +98,7 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ By default, **MWC** starts with `DocumentView`, disabling `LibraryView`, so only one document is created and managed. Enabling `LibraryView` allows multiple documents. +> [!NOTE] > Since **MWC** now starts with `LibraryView`, a document name is no longer required. If specified, `LibraryView` is still enabled, but **MWC** will start with `DocumentView`. ```javascript @@ -176,9 +177,13 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ ### Enable File Upload When `exportConfig.uploadToServer` is defined, an **Upload** button appears in both `DocumentView` and `PageView`. + +> [!NOTE] > If `LibraryView` is enabled, the **Upload** button will also appear there. The following example demonstrates how to enable file upload and exit the Mobile Web Capture Instance after a successful upload. + +> [!TIP] > If you followed the steps in [Build from Source](#option-1-build-from-source) and are still using the predefined Express server setup, the following upload code will work correctly. See the server configuration details in [`/dev-server/index.js`](https://github.com/Dynamsoft/mobile-web-capture/blob/main/dev-server/index.js). ```javascript @@ -189,7 +194,7 @@ const uploadToServer = async (fileName, blob) => { formData.append("uploadFile", blob, fileName); // Upload file const response = await fetch( - `${host}/upload`, // Change this to your actul upload URL + `${host}/upload`, // Change this to your actual upload URL { method: "POST", body: formData, @@ -224,7 +229,8 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ })(); ``` -> ⚠ **IMPORTANT**: The **Upload** feature is enabled simultaneously in `DocumentView` and `PageView` (and in `LibraryView` if it is enabled). If this is not intended, you can hide the **Upload** button in these **Views**. +> [!IMPORTANT] +> The **Upload** feature is enabled simultaneously in `DocumentView` and `PageView` (and in `LibraryView` if it is enabled). If this is not intended, you can hide the **Upload** button in these **Views**. > Read more: > 1. [Disable Upload in DocumentView](#example-2-disable-upload-in-documentview) > 2. [Disable Upload in PageView](#example-1-disable-upload-in-pageview) @@ -238,6 +244,8 @@ When **File Upload** feature is on and `LibraryView` is enabled, we can enable t 3. `exportConfig.deleteFromServer` The following example demonstrates how to enable this feature. + +> [!NOTE] > If you followed the steps in [Build from Source](#option-1-build-from-source) and are still using the predefined Express server setup, the following code will work correctly. See the server configuration details in [`/dev-server/index.js`](https://github.com/Dynamsoft/mobile-web-capture/blob/main/dev-server/index.js). ```javascript @@ -250,7 +258,7 @@ const uploadToServer = async (fileName, blob) => { formData.append("sessionID", shortSessionID); // Upload file const response = await fetch( - `${host}/upload`, // Change this to your actul upload URL + `${host}/upload`, // Change this to your actual upload URL { method: "POST", body: formData, @@ -344,6 +352,7 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ When `exportConfig.uploadToServer` is defined, the **Upload** button appears in both `DocumentView` and `PageView`. The following example demonstrates how to disable this feature by hiding it in `DocumentView`, ensuring that the **Upload** button only appears in `PageView`. +> [!TIP] > Read more in [Enable File Upload](#enable-file-upload). ```javascript @@ -417,7 +426,8 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ When `exportConfig.uploadToServer` is defined and `showLibraryView` is `true`, an **Upload** button will appears in `LibraryView`. The following example demonstrates how to hide the button. -> Read more in [Enable File Upload](#enable-file-upload) & [Enabe Upload History](#enable-upload-history). +> [!NOTE] +> Read more in [Enable File Upload](#enable-file-upload) & [Enable Upload History](#enable-upload-history). ```javascript const mobileWebCapture = new Dynamsoft.MobileWebCapture({ @@ -483,12 +493,15 @@ The configuration follows similar patterns, so we won’t cover them here for br ## Self-Hosting Resource Files By default, **MWC** relies on a **CDN** for resources such as `.wasm` engine files. If you require a **fully offline setup**, follow these steps: + +> [!IMPORTANT] > These steps are based on [Build from Source](#option-1-build-from-source), meaning that all **MWC** source files must be available on your local machine. #### Update the Resource Paths The following code modifies how resource files are referenced: +> [!TIP] > In this case, we reference local resource files that are copied during the build process. See [Modify the Build Script](#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](https://www.dynamsoft.com/company/contact/). ```javascript @@ -543,19 +556,18 @@ Once the server is running, open the application in a browser using the address Now, all required files will be **served locally** without relying on a CDN. -⚠**IMPORTANT NOTE**: - -* Certain legacy web application servers may lack support for the `application/wasm` mimetype for .wasm files. To address this, you have two options: - 1. Upgrade your web application server to one that supports the `application/wasm` mimetype. - 2. Manually define the mimetype on your server. You can refer to the guides for [apache](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Apache_Configuration_htaccess#media_types_and_character_encodings) / [IIS](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/staticcontent/mimemap) / [nginx](https://www.nginx.com/resources/wiki/start/topics/examples/full/#mime-types). - -* 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control). +> [!IMPORTANT] +>* Certain legacy web application servers may lack support for the `application/wasm` mimetype for .wasm files. To address this, you have two options: +> 1. Upgrade your web application server to one that supports the `application/wasm` mimetype. +> 2. Manually define the mimetype on your server. You can refer to the guides for [apache](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Apache_Configuration_htaccess#media_types_and_character_encodings) / [IIS](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/staticcontent/mimemap) / [nginx](https://www.nginx.com/resources/wiki/start/topics/examples/full/#mime-types). +> +>* 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control). ## Next Step diff --git a/guides/mobile-web-capture-v3.0.md b/guides/mobile-web-capture-v3.0.md new file mode 100644 index 0000000..6e4ef00 --- /dev/null +++ b/guides/mobile-web-capture-v3.0.md @@ -0,0 +1,239 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Mobile Web Capture - Scan Multi-Page Documents +keywords: Documentation, Mobile Web Capture, Dynamsoft Document Scanner, +description: Mobile Web Capture User Guide +--- + +# Scan Multi-Page Documents with Mobile Web Capture + +> Prerequisites: +> +> Read the [Introduction](https://www.dynamsoft.com/mobile-web-capture/docs/introduction/index.html) before proceeding. + +**Mobile Web Capture (MWC)** is an SDK designed for scanning multi-page documents. It integrates **Dynamsoft Document Scanner (DDS)** functionality while offering additional features such as multi-document management, annotation, and uploading, making it a comprehensive solution for managing complex document workflows. + +> See it in action with the [Mobile Web Capture Demo](https://demo.dynamsoft.com/mobile-web-capture/). + +This guide walks you through building a web application that scans multi-page documents using **MWC**, with **pre-defined configurations**. + +> If you are looking for a solution that scans single-page documents, please read [Dynamsoft Document Scanner User Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/document-scanner.html) instead. + + + +## License + +### Get a Trial License + +If you haven't got a trial license for **MWC**, you can request one through our [customer portal](https://www.dynamsoft.com/customer/license/trialLicense?product=mwc&source=guide). The trial license can be renewed twice, offering a total of two months of free access. + +> **DDS** and **MWC** share the same license keys. 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](https://www.dynamsoft.com/company/contact/). + +## Quick Start + +To use **MWC**, the first step is to obtain its library files. You can acquire them from one of the following sources: + +1. [**GitHub**](https://github.com/Dynamsoft/mobile-web-capture) – Contains the source files for the **MWC** SDK, which can be compiled into library files. +2. [**npm**](https://www.npmjs.com/package/dynamsoft-mobile-web-capture) – Provides precompiled library files via npm for easier installation. +3. [**CDN**](https://cdn.jsdelivr.net/npm/dynamsoft-mobile-web-capture) – 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: + +1. **Build from Source** – Download the source files from GitHub and compile the resource script yourself. +2. **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 **MWC** source files from its [GitHub Repository](https://github.com/Dynamsoft/mobile-web-capture), compiles them into a distributable package, and then runs a *ready-made* Hello World sample page included in the repository. + +Follow these steps: + +1. Download **MWC** from [GitHub](https://github.com/Dynamsoft/mobile-web-capture) as a compressed folder. +2. Extract the contents of the archive. +3. Enter the license key you received in [Get a Trial License](#get-a-trial-license). + > In your code editor, open the Hello World sample located at [`/samples/hello-world.html`](https://github.com/Dynamsoft/mobile-web-capture/blob/main/samples/hello-world.html). Search for `"YOUR_LICENSE_KEY_HERE"` and replace it with your actual license key. +4. Install project dependencies + In the terminal, navigate to the project root directory and run: + ```bash + npm install + ``` +5. Build the project + After the dependencies are installed, build the project by running: + ```bash + npm run build + ``` +6. Serve the project locally + Start the local server by running: + ```bash + 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`](https://github.com/Dynamsoft/mobile-web-capture/blob/main/dev-server/index.js). + +### Option 2: Use Precompiled Script + +Since the **MWC** library files are published on [npm](https://www.npmjs.com/package/dynamsoft-mobile-web-capture), it's easy to reference them from a CDN. + +To use the precompiled script, simply include the following URL in a ` +``` + +Below is the complete Hello World sample page that uses this precompiled script from a CDN. +> This code is identical to the [`/samples/hello-world.html`](https://github.com/Dynamsoft/mobile-web-capture/blob/main/samples/hello-world.html) file mentioned in the [Build from Source](#option-1-build-from-source) section, except for the script source. +> +> **Don't forget** to replace `"YOUR_LICENSE_KEY_HERE"` with your actual license key. + +```html + + + + + + Mobile Web Capture - Hello World + + + + + + +``` + +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 VSCode extension](https://marketplace.visualstudio.com/items?itemName=yandeu.five-server). 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. + +> Instead of using the code above, an alternative way to view the full code is by visiting the [Mobile Web Capture Hello World Sample](https://github.com/Dynamsoft/mobile-web-capture/blob/main/samples/hello-world.html). + +### Reference MWC + +```html + + + + + + Mobile Web Capture - Hello World + + + +``` + +In this step, **MWC** is referenced using a relative local path in the `` section of the HTML. + +```html + +``` + +Alternatively, the script can be referenced from a CDN: + +```html + +``` + +**MWC** wraps all its dependency scripts, so a **MWC** project only needs to include **MWC** itself as a single script. No additional dependency scripts are required. + +> ⚠**IMPORTANT**: 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](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture-customization.html#self-hosting-resource-files). + +### Instantiate MWC + +```javascript +// Instantiate a Mobile Web Capture Object +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key +}); +``` + +API Reference: [`MobileWebCapture()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/mobile-web-capture.html#mobilewebcapture) + +This step creates the **MWC** UI, which, when launched, occupies the entire visible area of the browser window by default. If needed, you can specify a container to restrict the UI's size. For more details, refer to [Specify the UI Container](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture-customization.html#example-1-specify-the-ui-container). + +> A **license key** is required for the instantiation. + +### Launch MWC + +```javascript +const fileName = `New_Document_${Date.now().toString().slice(-5)}`; // Generates a unique filename to use as the initial document name +await mobileWebCapture.launch(fileName); +``` + +API Reference: [`launch()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/mobile-web-capture.html#launch) + +This step launches the UI, starting in **`DocumentView`**, where the user can begin building a document in two ways: +> Note: The `DocumentView` requires a document name, which is passed as a parameter in the `launch()` method. + +1. Capture: Capture image(s) of the document pages. +2. Import: Import one or multiple images or PDF files. + +Once a document has been created, the user can navigate between three views: + +#### The DocumentView +The user can: + +1. **Share**: Share the document as a multi-page PDF file. + > **Download** is enabled where **Share** is not supported (e.g., in Firefox). +2. Manage: Select one or multiple pages for further actions. +3. **Manage** → **Select All** : Select all pages. +4. **Manage** → **Delete** : Delete selected pages from the document. +5. **Manage** → **Share** : Share individual pages as images (**.PNG**). + > **Download** is enabled where **Share** is not supported (e.g., in Firefox). + +The user can also enable the **"Upload"** feature. Check out [Enable File Upload](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture-customization.html#enable-file-upload) + +#### The PageView +When the user presses an image, the `PageView` is launched for that page, where the user can + +1. **Delete** : Remove the current page. +2. **Add Page** : Add more pages to the document. +1. **Share** : Share the current page as an image (**.PNG**). + > **Download** is enabled where **Share** is not supported (e.g., in Firefox). +4. **Edit** : Display additional editing features to further process the page. +5. **Edit** → **Crop** : Select a portion of the page and crop. +6. **Edit** → **Rotate** : Rotate the page **90 degrees counterclockwise**. +7. **Edit** → **Filter** : Adjust the page's pixels. +8. **Edit** → **Annotate** : Add annotations to the page. + +The user can also enable the **"Upload"** feature. Check out [Enable File Upload](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture-customization.html#enable-file-upload) + +## Next Step + +Mobile Web Capture provides extensive customization options. Read on to explore the available customizations in the [MWC Customization Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture-customization.html). diff --git a/guides/mobile-web-capture.md b/guides/mobile-web-capture.md index 857dcc3..40b37f3 100644 --- a/guides/mobile-web-capture.md +++ b/guides/mobile-web-capture.md @@ -10,16 +10,17 @@ description: Mobile Web Capture User Guide # Scan Multi-Page Documents with Mobile Web Capture -> Prerequisites: -> -> Read the [Introduction](https://www.dynamsoft.com/mobile-web-capture/docs/introduction/index.html) before proceeding. +> [!TIP] +> Prerequisites: read the [Introduction](https://www.dynamsoft.com/mobile-web-capture/docs/introduction/index.html) before proceeding. **Mobile Web Capture (MWC)** is an SDK designed for scanning multi-page documents. It integrates **Dynamsoft Document Scanner (DDS)** functionality while offering additional features such as multi-document management, annotation, and uploading, making it a comprehensive solution for managing complex document workflows. +> [!TIP] > See it in action with the [Mobile Web Capture Demo](https://demo.dynamsoft.com/mobile-web-capture/). -This guide walks you through building a web application that scans multi-page documents using MWC, with **pre-defined configurations**. +This guide walks you through building a web application that scans multi-page documents using **MWC**, with **pre-defined configurations**. +> [!TIP] > If you are looking for a solution that scans single-page documents, please read [Dynamsoft Document Scanner User Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/document-scanner.html) instead. ``` -In this step, MWC is referenced using a relative local path in the `` section of the HTML. +In this step, **MWC** is referenced using a relative local path in the `` section of the HTML. ```html @@ -167,12 +180,13 @@ In this step, MWC is referenced using a relative local path in the `` sect Alternatively, the script can be referenced from a CDN: ```html - + ``` -MWC wraps all its dependency scripts, so a MWC project only needs to include MWC itself as a single script. No additional dependency scripts are required. +**MWC** wraps all its dependency scripts, so a **MWC** project only needs to include **MWC** itself as a single script. No additional dependency scripts are required. -> ⚠**IMPORTANT**: 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](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture-customization.html#self-hosting-resource-files). +> [!IMPORTANT] +> 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](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture-customization.html#self-hosting-resource-files). ### Instantiate MWC @@ -185,8 +199,9 @@ const mobileWebCapture = new Dynamsoft.MobileWebCapture({ API Reference: [`MobileWebCapture()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/mobile-web-capture.html#mobilewebcapture) -This step creates the MWC UI, which, when launched, occupies the entire visible area of the browser window by default. If needed, you can specify a container to restrict the UI's size. For more details, refer to [Specify the UI Container](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture-customization.html#specify-the-ui-container). +This step creates the **MWC** UI, which, when launched, occupies the entire visible area of the browser window by default. If needed, you can specify a container to restrict the UI's size. For more details, refer to [Specify the UI Container](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture-customization.html#example-1-specify-the-ui-container). +> [!WARNING] > A **license key** is required for the instantiation. ### Launch MWC @@ -199,10 +214,12 @@ await mobileWebCapture.launch(fileName); API Reference: [`launch()`](https://www.dynamsoft.com/mobile-web-capture/docs/api/mobile-web-capture.html#launch) This step launches the UI, starting in **`DocumentView`**, where the user can begin building a document in two ways: -> Note: The `DocumentView` requires a document name, which is passed as a parameter in the `launch()` method. -1. Capture: Capture image(s) of the document pages. -2. Import: Import one or multiple images or PDF files. +> [!NOTE] +> The `DocumentView` requires a document name, which is passed as a parameter in the `launch()` method. + +1. **Capture**: Capture image(s) of the document pages. +2. **Import**: Import one or multiple images or PDF files. Once a document has been created, the user can navigate between three views: @@ -210,12 +227,12 @@ Once a document has been created, the user can navigate between three views: The user can: 1. **Share**: Share the document as a multi-page PDF file. - > **Download** is enabled where **Share** is not supported (e.g., in Firefox). -2. Manage: Select one or multiple pages for further actions. + - **Download** is enabled where **Share** is not supported (e.g., in Firefox). +2. **Manage**: Select one or multiple pages for further actions. 3. **Manage** → **Select All** : Select all pages. 4. **Manage** → **Delete** : Delete selected pages from the document. 5. **Manage** → **Share** : Share individual pages as images (**.PNG**). - > **Download** is enabled where **Share** is not supported (e.g., in Firefox). + - **Download** is enabled where **Share** is not supported (e.g., in Firefox). The user can also enable the **"Upload"** feature. Check out [Enable File Upload](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture-customization.html#enable-file-upload) @@ -225,12 +242,12 @@ When the user presses an image, the `PageView` is launched for that page, where 1. **Delete** : Remove the current page. 2. **Add Page** : Add more pages to the document. 1. **Share** : Share the current page as an image (**.PNG**). - > **Download** is enabled where **Share** is not supported (e.g., in Firefox). -4. **Edit** : Display additional editing features to further process the page. -5. **Edit** → **Crop** : Select a portion of the page and crop. -6. **Edit** → **Rotate** : Rotate the page **90 degrees counterclockwise**. -7. **Edit** → **Filter** : Adjust the page's pixels. -8. **Edit** → **Annotate** : Add annotations to the page. + - **Download** is enabled where **Share** is not supported (e.g., in Firefox). +2. **Edit** : Display additional editing features to further process the page. +3. **Edit** → **Crop** : Select a portion of the page and crop. +4. **Edit** → **Rotate** : Rotate the page **90 degrees counterclockwise**. +5. **Edit** → **Filter** : Adjust the page's pixels. +6. **Edit** → **Annotate** : Add annotations to the page. The user can also enable the **"Upload"** feature. Check out [Enable File Upload](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture-customization.html#enable-file-upload) diff --git a/introduction/index-v3.0.md b/introduction/index-v3.0.md new file mode 100644 index 0000000..328c8a1 --- /dev/null +++ b/introduction/index-v3.0.md @@ -0,0 +1,181 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Mobile Web Capture - Introduction +keywords: Documentation, Mobile Web Capture, Introduction +breadcrumbText: Introduction +description: Mobile Web Capture Documentation Introduction +permalink: /introduction/index.html +--- + +# Introduction + +When digitizing physical documents—whether for easier storage, better accessibility, or streamlined processing — a hardware scanner is often the preferred choice. For integrating this functionality into web applications, **Dynamsoft’s** [Dynamic Web TWAIN](https://www.dynamsoft.com/web-twain/docs/introduction/index.html) is a widely popular option. + +However, when hardware scanners are not feasible or convenient, mobile device cameras can serve as effective alternatives. **Mobile Web Capture (MWC)** is a document scanning SDK specifically designed to address this need. + +## Common Usage Scenarios + +1. **Document Capture** – Capture a *single* clear image of a physical document, such as a patient intake form or the biographical page of a passport. +2. **Document Management** – Capture images of *multiple* document pages (e.g., a contract) and compile them into a single PDF. +3. **Document Processing** – Add *annotations* to scanned pages and perform common editing tasks such as cropping and color filtering. + +## Choosing the Right Solution + +**MWC** is designed to handle all three scenarios seamlessly. However, for **single-page document capture (Scenario 1)**, **MWC** may feel overly feature-rich. To address this, we developed **Dynamsoft Document Scanner (DDS)** — a streamlined solution tailored for capturing single-page documents using mobile cameras. + +**DDS** not only captures documents but also enhances their quality to meet professional standards, making it an ideal tool for **Scenario 1** as described above. + +> Not sure if it is the right fit? **Try the** [DDS demo](https://demo.dynamsoft.com/document-scanner/) first. If it meets your needs, you can skip the rest of this introduction and proceed directly to the [DDS user guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/document-scanner.html). + +However, if you need multi-page capture, **MWC** extends DDS’s functionality by supporting multi-page documents. Additionally, **MWC** offers advanced features such as document processing, editing, and annotation, making it a comprehensive solution for managing complex document workflows. + +In short, for scenarios requiring **document management beyond single-page capture, MWC provides the flexibility and functionality needed to streamline the entire process.** + +## Key Features + +| Feature | DDS | MWC | +| :-------------------------------------------------------------------------------------------------- | :--- | :--- | +| Capture single documents using mobile devices or webcams | ✓ | ✓ | +| Import a single local image of a document | ✓ | ✓ | +| Import multiple images or PDF files | | ✓ | +| Automatically detect document borders during image capture | ✓ | ✓ | +| Automatically capture and correct images to match detected document boundaries | ✓ | ✓ | +| Organize and manage a multi-page document | | ✓ | +| Organize and manage multiple documents in a library | | ✓ | +| Annotate documents with comments, highlights, or other markings | | ✓ | +| Easily transfer pages between documents | | ✓ | +| Export a single-page document as an image | ✓ | ✓ | +| Export multi-page documents as PDFs with options for selected pages, one or multiple full documents | | ✓ | + +> To deliver these features, we built **DDS** using two core Dynamsoft products: [**Dynamsoft Camera Enhancer**](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/user-guide/index.html?lang=javascript) (DCE) and [**Dynamsoft Document Normalizer**](https://www.dynamsoft.com/document-normalizer/docs/web/programming/javascript/user-guide/index.html?lang=javascript) (DDN). +> +> **MWC** extends this foundation by adding document management, processing, and editing features through [**Dynamsoft Document Viewer**](https://www.dynamsoft.com/document-viewer/docs/introduction/index.html) (DDV). Both products operate within the [**Dynamsoft Capture Vision**](https://www.dynamsoft.com/capture-vision/docs/core/architecture/?lang=javascript) (DCV) architecture. + +## Design Principles + +We designed **DDS** and **MWC** with three core principles in mind: + +1. **Minimal Code** - High-level APIs provide full functionality with just **a couple of lines of code**, significantly reducing development and maintenance costs. +2. **Ready-to-Use UI** - Pre-integrated components and a pre-designed UI enable a **quick setup** while minimizing design efforts. +3. **Effortless Customization** - Tailored configuration objects allow for **easy workflow customization**, addressing common document scenarios without adding development complexity. + +The following example demonstrates how simple it is to power a complete document scanning and management workflow, including all UI elements: + +```javascript +const mobileWebCapture = new Dynamsoft.MobileWebCapture({ + license: "YOUR_LICENSE_KEY_HERE", +}); +await mobileWebCapture.launch(); +``` +The UI elements are modularized into distinct Views, each offering developer-friendly configuration options. These options enable flexible business logic through straightforward configuration objects, helping to reduce development costs and streamline maintenance. + +The following section provides a high-level overview of the Views, followed by a detailed look at two specific Views. + +## Views + +**DDS** and **MWC** workflows are composed of **Views**, each of which comes **ready-to-use** and can be easily customized using configuration objects. + +### DDS Views + +**DDS** includes the following Views for document scanning and correction: + +1. **Document Scanner View** – Captures documents using a camera scanner. +2. **Document Correction View** – Applies further perspective cropping and adjustments. +3. **Document Result View** – Provides a preview of the scanned document. + +### MWC Views + +Building on **DDS**, **MWC** extends functionality with additional Views for full document management, editing, and annotation capabilities: + +1. **Library View** – Manage all multi-page documents. +2. **Document View** – Organize and manage all pages within a specific document. +3. **Page View** – View and edit a single page in a document with features including "Cropy", "Rotate", "Filter", and "Annotate". +4. **Transfer View** – Copy or move pages between documents. + +### Detailed View Breakdown + +Here is a closer look at two specific Views: + +#### Document Scanner View + +![Document Scanner View](/assets/imgs/document-scanner-view-demo.png) + +The **Document Scanner View** (available in both **DDS** and **MWC**) captures scans of documents. It automatically detects document boundaries in the video feed and can optionally select the best frame for scanning, eliminating the need for users to manually snap the image. + +#### Page View + +![Editor View](/assets/imgs/editor-view-demo.png) + +The **Page View** (**MWC** only) allows users to view and edit an individual page of a document with a variety of tools. It supports common editing tasks such as cropping, color filtering, and comprehensive annotation options to enhance document clarity and presentation. + + + + + + + +## System Requirements + +### Secure Context (HTTPS Deployment) + +When deploying your web application for production, ensure it is served over a **secure HTTPS connection**. This is required for the following reasons: + +1. **Browser Security Restrictions** – Most browsers only allow access to camera video streams in a secure context. + > Some browsers like Chrome may grant access to camera video streams for `http://127.0.0.1`, `http://localhost`, or even pages opened directly from the local file system (`file:///...`). This can be helpful during development and testing. + +2. **Dynamsoft License Requirements** – A secure context is required for **Dynamsoft licenses** to function properly. + +### Required Browser Features + +The following** browser features** are required for the **DCE** and **DDN** components of **DDS** and **MWC**: + +1. [`WebAssembly`](https://caniuse.com/?search=WebAssembly) +2. [`Blob`](https://caniuse.com/?search=Blob) +3. [`URL`](https://caniuse.com/?search=URL)/[`createObjectURL`](https://caniuse.com/?search=createObjectURL) +4. [`Web Workers`](https://caniuse.com/?search=Worker) + +### Supported Browsers + +The table below lists the **minimum supported versions** of browsers based on these requirements: + +| Browser | Version | +| :-----: | :-----: | +| Chrome | v78+ | +| Firefox | v79+ | +| Safari | v15+ | +| Edge | v92+ | + +## Next Step + +- If you only need to scan single-page documents and do not require handling PDF files (import or export), you can proceed to the [Dynamsoft Document Scanner Developer Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/document-scanner.html). + +- If you need to handle multi-page documents, PDF files, annotations, and more, you will need the full-featured **Mobile Web Capture (MWC)**. In this case, proceed to the [Mobile Web Capture Developer Guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/mobile-web-capture.html). diff --git a/introduction/index.md b/introduction/index.md index 216ef58..7dbafbe 100644 --- a/introduction/index.md +++ b/introduction/index.md @@ -12,7 +12,7 @@ permalink: /introduction/index.html # Introduction -When digitizing physical documents—whether for easier storage, better accessibility, or streamlined processing — a hardware scanner is often the preferred choice. For integrating this functionality into web applications, **Dynamsoft’s** [Dynamic Web TWAIN](https://www.dynamsoft.com/web-twain/docs/introduction/index.html) is a widely popular option. +When digitizing physical documents—whether for easier storage, better accessibility, or streamlined processing — a hardware scanner is often the preferred choice. For integrating this functionality into web applications, **Dynamsoft’s** [Dynamic Web TWAIN](https://www.dynamsoft.com/web-twain/docs/introduction/index.html) is a widely popular option. However, when hardware scanners are not feasible or convenient, mobile device cameras can serve as effective alternatives. **Mobile Web Capture (MWC)** is a document scanning SDK specifically designed to address this need. @@ -26,9 +26,10 @@ However, when hardware scanners are not feasible or convenient, mobile device ca **MWC** is designed to handle all three scenarios seamlessly. However, for **single-page document capture (Scenario 1)**, **MWC** may feel overly feature-rich. To address this, we developed **Dynamsoft Document Scanner (DDS)** — a streamlined solution tailored for capturing single-page documents using mobile cameras. -**DDS** not only captures documents but also enhances their quality to meet professional standards, making it an ideal tool for **Scenario 1**. +**DDS** not only captures documents but also enhances their quality to meet professional standards, making it an ideal tool for **Scenario 1** as described above. -> Not sure if it’s the right fit? **Try the** [DDS demo](https://demo.dynamsoft.com/document-scanner/) first. If it meets your needs, you can skip the rest of this introduction and proceed directly to the [DDS user guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/document-scanner.html). +> [!TIP] +> Not sure if it is the right fit? **Try the** [DDS demo](https://demo.dynamsoft.com/document-scanner/) first. If it meets your needs, you can skip the rest of this introduction and proceed directly to the [DDS user guide](https://www.dynamsoft.com/mobile-web-capture/docs/guides/document-scanner.html). However, if you need multi-page capture, **MWC** extends DDS’s functionality by supporting multi-page documents. Additionally, **MWC** offers advanced features such as document processing, editing, and annotation, making it a comprehensive solution for managing complex document workflows. @@ -50,6 +51,7 @@ In short, for scenarios requiring **document management beyond single-page captu | Export a single-page document as an image | ✓ | ✓ | | Export multi-page documents as PDFs with options for selected pages, one or multiple full documents | | ✓ | +> [!NOTE] > To deliver these features, we built **DDS** using two core Dynamsoft products: [**Dynamsoft Camera Enhancer**](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/user-guide/index.html?lang=javascript) (DCE) and [**Dynamsoft Document Normalizer**](https://www.dynamsoft.com/document-normalizer/docs/web/programming/javascript/user-guide/index.html?lang=javascript) (DDN). > > **MWC** extends this foundation by adding document management, processing, and editing features through [**Dynamsoft Document Viewer**](https://www.dynamsoft.com/document-viewer/docs/introduction/index.html) (DDV). Both products operate within the [**Dynamsoft Capture Vision**](https://www.dynamsoft.com/capture-vision/docs/core/architecture/?lang=javascript) (DCV) architecture. @@ -60,7 +62,7 @@ We designed **DDS** and **MWC** with three core principles in mind: 1. **Minimal Code** - High-level APIs provide full functionality with just **a couple of lines of code**, significantly reducing development and maintenance costs. 2. **Ready-to-Use UI** - Pre-integrated components and a pre-designed UI enable a **quick setup** while minimizing design efforts. -3. **Cost-Effective Customization** - Tailored configuration objects allow for **easy workflow customization**, addressing common document scenarios without adding development complexity. +3. **Effortless Customization** - Tailored configuration objects allow for **easy workflow customization**, addressing common document scenarios without adding development complexity. The following example demonstrates how simple it is to power a complete document scanning and management workflow, including all UI elements: @@ -97,7 +99,7 @@ Building on **DDS**, **MWC** extends functionality with additional Views for ful ### Detailed View Breakdown -Here’s a closer look at two specific Views: +Here is a closer look at two specific Views: #### Document Scanner View @@ -150,6 +152,7 @@ The Transfer View --> When deploying your web application for production, ensure it is served over a **secure HTTPS connection**. This is required for the following reasons: 1. **Browser Security Restrictions** – Most browsers only allow access to camera video streams in a secure context. + > [!NOTE] > Some browsers like Chrome may grant access to camera video streams for `http://127.0.0.1`, `http://localhost`, or even pages opened directly from the local file system (`file:///...`). This can be helpful during development and testing. 2. **Dynamsoft License Requirements** – A secure context is required for **Dynamsoft licenses** to function properly.