diff --git a/.github/workflows/full-site-build.yml b/.github/workflows/full-site-build.yml deleted file mode 100644 index 306588f..0000000 --- a/.github/workflows/full-site-build.yml +++ /dev/null @@ -1,82 +0,0 @@ -# This is a basic workflow to help you get started with Actions - -name: Full-Site-Build - -# Controls when the workflow will run -on: - # Triggers the workflow on push events but only for the master branch - # push: - # branches: [ preview ] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# A workflow run is made up of one or more jobs that can run sequentially or in parallel -jobs: - # This workflow contains jobs called "Build-Main" and "Build-Preview" - Build-Main: - if: ${{ github.ref == 'refs/heads/main' }} - # The type of runner that the job will run on - runs-on: self-hosted - - # Steps represent a sequence of tasks that will be executed as part of the job - steps: - # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - #- uses: actions/checkout@v2 - - # Runs a set of commands using the runners shell - - name: Build the site - run: | - cd /home/ubuntu - [ -d MWCDoc ] && rm -rf MWCDoc - [ ! -d MWCDoc ] && mkdir -p MWCDoc - [ ! -d mobile-web-capture-docs ] && git clone --depth 1 https://github.com/dynamsoft-docs/mobile-web-capture-docs.git mobile-web-capture-docs - [ ! -d Docs-Template-Repo-Preview ] && git clone --depth 1 --branch preview https://github.com/dynamsoft-docs/Docs-Template-Repo.git Docs-Template-Repo-Preview - cd mobile-web-capture-docs && git pull && cd .. && cp -rfp ./mobile-web-capture-docs/* ./MWCDoc/ - cd Docs-Template-Repo-Preview && git pull && cd .. && cp -rfp ./Docs-Template-Repo-Preview/* ./MWCDoc/ - cd MWCDoc && bundle exec jekyll build - #python3 /home/ubuntu/ftp.py /home/ubuntu/MWCDoc/_site/ ./www.dynamsoft.com/mobile-web-capture/docs/ prod - - - name: Sync files - uses: SamKirkland/FTP-Deploy-Action@4.3.0 - with: - server: ${{ secrets.FTP_DYNAMSOFT_LOCAL_SERVER }} - username: ${{ secrets.FTP_DYNAMSOFT_LOCAL_USER }} - password: ${{ secrets.FTP_DYNAMSOFT_LOCAL_PASSWORD }} - port: 21 - local-dir: /home/ubuntu/MWCDoc/_site/ - server-dir: /www.dynamsoft.com/mobile-web-capture/docs/ - - Build-Preview: - if: ${{ github.ref == 'refs/heads/preview' }} - # The type of runner that the job will run on - runs-on: self-hosted - - # Steps represent a sequence of tasks that will be executed as part of the job - steps: - # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - #- uses: actions/checkout@v2 - - # Runs a set of commands using the runners shell - - name: Build the site - run: | - cd /home/ubuntu - [ -d MWCDocPreview ] && rm -rf MWCDocPreview - [ -d mobile-web-capture-docs-preview ] && rm -rf mobile-web-capture-docs-preview - [ ! -d MWCDocPreview ] && mkdir -p MWCDocPreview - [ ! -d mobile-web-capture-docs-preview ] && git clone --depth 1 --branch preview https://github.com/dynamsoft-docs/mobile-web-capture-docs.git mobile-web-capture-docs-preview - cd mobile-web-capture-docs-preview && git pull && cd .. && cp -rfp ./mobile-web-capture-docs-preview/* ./MWCDocPreview/ - cd Docs-Template-Repo-Preview && git pull && cd .. && cp -rfp ./Docs-Template-Repo-Preview/* ./MWCDocPreview/ - sed -i -e "1,3s/blob\/master$/blob\/preview/" \ - -e "1,3s/blob\/main$/blob\/preview/" /home/ubuntu/MWCDocPreview/_config.yml - cd MWCDocPreview && bundle exec jekyll build - - - name: Sync files - uses: SamKirkland/FTP-Deploy-Action@4.3.0 - with: - server: ${{ secrets.FTP_TEST_SITE_SERVER }} - username: ${{ secrets.FTP_TEST_SITE_USER }} - password: ${{ secrets.FTP_TEST_SITE_PASSWORD }} - port: 7500 - local-dir: /home/ubuntu/MWCDocPreview/_site/ - server-dir: /www.dynamsoft.com/mobile-web-capture/docs/ diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 8652116..0905c6c 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -20,14 +20,14 @@ jobs: if: ${{ github.ref == 'refs/heads/main' }} uses: dynamsoft-docs/Docs-Template-Repo/.github/workflows/called-workflow-build-sync-production.yml@main with: - doc-repo: mobile-web-capture-docs - doc-url: mobile-web-capture/docs/ + doc-repo: mobile-document-scanner-docs-js + doc-url: mobile-document-scanner/docs/web/ secrets: inherit Build-Preview: if: ${{ github.ref == 'refs/heads/preview' }} uses: dynamsoft-docs/Docs-Template-Repo/.github/workflows/called-workflow-build-sync-testing.yml@main with: - doc-repo: mobile-web-capture-docs - doc-url: mobile-web-capture/docs/ + doc-repo: mobile-document-scanner-docs-js + doc-url: mobile-document-scanner/docs/web/ secrets: inherit diff --git a/_config.yml b/_config.yml index 279c87d..d252933 100644 --- a/_config.yml +++ b/_config.yml @@ -1,29 +1,29 @@ repository: dynamsoft-docs/mobile-web-capture-docs repositoryUrl: https://github.com/dynamsoft-docs/mobile-web-capture-docs/blob/main -docFullPath: https://www.dynamsoft.com/mobile-web-capture/docs -firstLevelUrl: /mobile-web-capture/docs -docHomePage: /mobile-web-capture/docs/introduction/ +docFullPath: https://www.dynamsoft.com/mobile-document-scanner/docs/web +firstLevelUrl: /mobile-document-scanner/docs/web +docHomePage: /mobile-document-scanner/docs/web/introduction/ -introduction: /mobile-web-capture/docs/introduction/ -gettingstarted: /mobile-web-capture/docs/gettingstarted/ -codegallery: /mobile-web-capture/docs/codegallery/ -code-gallery: /mobile-web-capture/docs/code-gallery/ -api: /mobile-web-capture/docs/api/ +introduction: /mobile-document-scanner/docs/web/introduction/ +gettingstarted: /mobile-document-scanner/docs/web/gettingstarted/ +codegallery: /mobile-document-scanner/docs/web/codegallery/ +code-gallery: /mobile-document-scanner/docs/web/code-gallery/ +api: /mobile-document-scanner/docs/web/api/ -guides: /mobile-web-capture/docs/guides/ +guides: /mobile-document-scanner/docs/web/guides/ -release-notes: /mobile-web-capture/docs/release-notes/ +release-notes: /mobile-document-scanner/docs/web/release-notes/ useVersionTree: true -assets: /mobile-web-capture/docs/assets/ -edit_icon: /mobile-web-capture/docs/assets/img-icon/edit-icon.png -smile_icon: /mobile-web-capture/docs/assets/img-icon/icon-smile.png -sad_icon: /mobile-web-capture/docs/assets/img-icon/icon-sad.png +assets: /mobile-document-scanner/docs/web/assets/ +edit_icon: /mobile-document-scanner/docs/web/assets//img-icon/edit-icon.png +smile_icon: /mobile-document-scanner/docs/web/assets/img-icon/icon-smile.png +sad_icon: /mobile-document-scanner/docs/web/assets/img-icon/icon-sad.png -baseurl: "/mobile-web-capture/docs" +baseurl: "/mobile-document-scanner/docs/web" -download: "/mobile-web-capture/downloads/" +download: "/mobile-document-scanner/downloads/" plugins: - jemoji diff --git a/_includes/mwcNav-v2.0.html b/_includes/mwcNav-v2.0.html deleted file mode 100644 index 9560106..0000000 --- a/_includes/mwcNav-v2.0.html +++ /dev/null @@ -1,67 +0,0 @@ - - -
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`]({{ site.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 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. - 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 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**](#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. - -```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 discuss a few ways to adjust the **DDS** workflow. - -#### Example 1: Confine DocumentScanner UI to a Specific Container - -As long as the `DocumentScanner` container is assigned, **DDS** confines its **Views** within that container. - -> [!NOTE] -> Containers assigned to its constituent **Views** will be ignored. - -```html - -``` - -```javascript -const documentScanner = new Dynamsoft.DocumentScanner({ - license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key - container: document.getElementById("myDocumentScannerContainer") , // Use this container for the full workflow - scannerViewConfig: { - container: document.getElementById("myDocumentScannerViewContainer") // This container is ignored - } -}); -``` - -API Reference: - -- [`DocumentScanner()`]({{ site.api }}document-scanner.html#documentscanner) -- [`DocumentScannerConfig`]({{ site.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: - -```javascript -const documentScanner = new Dynamsoft.DocumentScanner({ - license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key - showResultView: false, - showCorrectionView: false -}); -``` - -API Reference: - -- [`DocumentScanner()`]({{ site.api }}document-scanner.html#documentscanner) -- [`DocumentScannerConfig`]({{ site.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** renders the full workflow using these three containers. - -```html - - - -``` - -```javascript -const documentScanner = new Dynamsoft.DocumentScanner({ - license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key - scannerViewConfig: { - container: document.getElementById("myDocumentScannerViewContainer") - }, - correctionViewConfig: { - container: document.getElementById("myDocumentCorrectionViewContainer") - }, - resultViewConfig: { - container: document.getElementById("myScanResultViewContainer") - } -}); -``` - -API Reference: - -- [`DocumentScanner()`]({{ site.api }}document-scanner.html#documentscanner) -- [`DocumentScannerConfig`]({{ site.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()`]({{ site.api }}document-scanner.html#documentscanner) -- [`DocumentScannerConfig`]({{ site.api }}document-scanner.html#documentscannerconfig) -- [`DocumentScannerViewConfig`]({{ site.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 -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`. - -> [!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.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. - -##### 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 - }, - }); - ``` - -API Reference: - -- [`DocumentScanner()`]({{ site.api }}document-scanner.html#documentscanner) -- [`DocumentScannerConfig`]({{ site.api }}document-scanner.html#documentscannerconfig) -- [`DocumentScannerViewConfig`]({{ site.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; - }; -} -``` - -API Reference: - -[`ScanRegion`]({{ site.api }}document-scanner.html#scanregion) - -Here is how the scanning region is set: - -1. Use the `ratio` property to set the height-to-width of the rectangular scanning region, then scale the rectangle up to fit within the viewfinder. -2. Translate the rectangular 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`: - -```javascript -interface DocumentCorrectionViewConfig { - container?: HTMLElement; - toolbarButtonsConfig?: DocumentCorrectionViewToolbarButtonsConfig; - onFinish?: (result: DocumentScanResult) => void; -} -``` - -`container` is covered in [Workflow Customization](#workflow-customization). Below we discuss the other two properties. - -##### Styling Buttons - -The `toolbarButtonsConfig` property of type `DocumentCorrectionViewToolbarButtonsConfig` customizes the appearance and functionality of the UI buttons. Here is its definition: - -```javascript -type ToolbarButtonConfig = PickNo image scanned. Please try again.
"; +} +``` + +## Custom Usage + +This section builds on the Hello World sample to demonstrate how to configure **MDS**, typically by adjusting the `DocumentScannerConfig` object. + +### `DocumentScannerConfig` Overview + +[`DocumentScannerConfig`]({{ site.api }}document-scanner.html#documentscannerconfig) is the primary configuration object for customizing **MDS**. It includes the following properties: + +1. `license`: The license key. +2. `container`: The HTML container for the entire workflow. If not specified (like in the Hello World Sample), one is created automatically. +3. `showCorrectionView`: 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. + 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 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 **MDS** with `DocumentScannerConfig`: + +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](#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, **MDS** automatically creates "containers" for its **Views**. In this section we discuss a few ways to adjust the **MDS** workflow. + +#### Example 1: Confine DocumentScanner UI to a Specific Container + +As long as the `DocumentScanner` container is assigned, **MDS** confines its **Views** within that container. + +> [!NOTE] +> Containers assigned to its constituent **Views** will be ignored. + +```html + +``` + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + container: document.getElementById("myDocumentScannerContainer") , // Use this container for the full workflow + scannerViewConfig: { + container: document.getElementById("myDocumentScannerViewContainer") // This container is ignored + } +}); +``` + +API Reference: + +- [`DocumentScanner()`]({{ site.api }}document-scanner.html#documentscanner) +- [`DocumentScannerConfig`]({{ site.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: + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + showResultView: false, + showCorrectionView: false +}); +``` + +API Reference: + +- [`DocumentScanner()`]({{ site.api }}document-scanner.html#documentscanner) +- [`DocumentScannerConfig`]({{ site.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, **MDS** renders the full workflow using these three containers. + +```html + + + +``` + +```javascript +const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key + scannerViewConfig: { + container: document.getElementById("myDocumentScannerViewContainer") + }, + correctionViewConfig: { + container: document.getElementById("myDocumentCorrectionViewContainer") + }, + resultViewConfig: { + container: document.getElementById("myScanResultViewContainer") + } +}); +``` + +API Reference: + +- [`DocumentScanner()`]({{ site.api }}document-scanner.html#documentscanner) +- [`DocumentScannerConfig`]({{ site.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()` MDS 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, MDS 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()`]({{ site.api }}document-scanner.html#documentscanner) +- [`DocumentScannerConfig`]({{ site.api }}document-scanner.html#documentscannerconfig) +- [`DocumentScannerViewConfig`]({{ site.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 +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`. + +> [!TIP] +> If **MDS** 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.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. + +##### Steps to Customize the UI for `DocumentScannerView` +1. Follow the instructions in [Build from Source](#build-from-source) to obtain the source files for **MDS**. +2. Edit `/src/document-scanner.ui.html` to apply your customizations. +3. Build the project to generate the updated file in `/dist/document-scanner.ui.html`: + + ```shell + npm run build + ``` +4. Update the configuration to use the local file instead of the CDN version: + + ```javascript + const documentScanner = new Dynamsoft.DocumentScanner({ + license: "YOUR_LICENSE_KEY_HERE", // Replace with your actual license key + scannerViewConfig: { + cameraEnhancerUIPath: "../dist/document-scanner.ui.html", // Use the local file + }, + }); + ``` + +API Reference: + +- [`DocumentScanner()`]({{ site.api }}document-scanner.html#documentscanner) +- [`DocumentScannerConfig`]({{ site.api }}document-scanner.html#documentscannerconfig) +- [`DocumentScannerViewConfig`]({{ site.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; + }; +} +``` + +API Reference: + +[`ScanRegion`]({{ site.api }}document-scanner.html#scanregion) + +Here is how the scanning region is set: + +1. Use the `ratio` property to set the height-to-width of the rectangular scanning region, then scale the rectangle up to fit within the viewfinder. +2. Translate the rectangular 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`: + +```javascript +interface DocumentCorrectionViewConfig { + container?: HTMLElement; + toolbarButtonsConfig?: DocumentCorrectionViewToolbarButtonsConfig; + onFinish?: (result: DocumentScanResult) => void; +} +``` + +`container` is covered in [Workflow Customization](#workflow-customization). Below we discuss the other two properties. + +##### 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