TWAIN acquisition in DocuVieware

TWAIN acquisition in web applications presents unique challenges compared to traditional Windows applications.

Web applications operate in a sandboxed environment with limited system access for security reasons. Additionally, web applications consist of separate client and server components that must communicate, but the server has no direct access to client-side resources like scanning devices.

Using the TWAIN methods available in GdPicture.NET directly isn’t possible because only devices connected to the server would be visible.

TWAIN and DocuVieware

To overcome these technical challenges, DocuVieware provides a tool that enables connection and communication between the web application and TWAIN acquisition devices.

This tool is a lightweight, self-contained, secured software component that installs locally on the client machine (a one-time operation). The component is available as an MSI package embedded and served by DocuVieware directly, ensuring your users always have the correct version.

DocuVieware includes built-in TWAIN acquisition, enabled by default through the EnableTwainAcquisitionButton property. It supports any TWAIN-compliant device and provides a dedicated acquisition dialog for choosing the source and destination of acquired pages (append to the current document or create a new one).

While this default behavior works for many cases, some scenarios require finer control over the process and acquisition options. In these cases, use the JavaScript client API to take control of the TWAIN acquisition and customize its behavior, as described in the next section.

Whether you use the default built-in feature or implement your own acquisition process with the API, the result is the same: All acquired pages automatically go directly into the corresponding DocuVieware instance. This makes the process consistent regardless of the source — whether it’s a document opened from a local or remote source or an acquired document.

Potential issues and troubleshooting

The local service is compiled and runs in 32-bit mode, even on 64-bit Windows operating systems. This maximizes device compatibility since every TWAIN device has a 32-bit driver, while 64-bit drivers are still rare. The tradeoff is that allocatable memory is smaller, which means you may reach a memory limit that makes the acquisition process slower or eventually causes it to stop.

There’s no universal formula for calculating this memory limit because it depends on many factors:

  • Windows version
  • Amount of physical RAM on the system
  • Available allocatable memory for applications
  • Acquisition settings

These factors vary significantly between systems. The most effective way to determine this limit is to test the actual conditions of your application (number of pages, quality, color depth) and verify that the process completes correctly.

If you reach a limitation, try these mitigation strategies to reduce the overall size of the acquisition:

  • Check acquisition parameters — Review the resolution and color bit depth. Acquiring several pages at 600 DPI with 32-bit color consumes significant memory. If documents can be acquired at 200 DPI in black and white instead, memory usage drops dramatically and the process runs more smoothly.
  • Reduce batch size — If the acquisition stops after 15 pages when attempting to acquire 20 or 30 pages, split the operation into smaller batches of 10 pages each to work around the memory limit.
  • Build a custom acquisition process — Depending on your requirements, you can build your own TWAIN acquisition process to control all options. This enables you to lock certain settings and prevent users from selecting excessive parameters that cause memory problems.

Custom TWAIN acquisition process walkthrough

The following workflow demonstrates TWAIN acquisition using the API. For this example, assume your DocuVieware instance is called DocuVieware1.

Check for local service status

Call the TwainGetLocalServiceStatus method to check the local service status. As documented, it returns a value indicating whether the local service is ready, not responding, or running the wrong version.

If the service isn’t running (or if the wrong version is running), start the download process of the latest version by calling the TwainDownloadServiceSetup method.

This software requires administrative rights to install on the client machine. Close all browsers before installing the package.

The software starts automatically with Windows after installation.

JavaScript
var status = DocuViewareAPI.TwainGetLocalServiceStatus("DocuVieware1");
if (status !== 0) {
    console.log("Local service cannot be accessed. Please install it now.");
    DocuViewareAPI.TwainDownloadServiceSetup("DocuVieware1");
}

Retrieve the available devices

Once the service is running, retrieve the list of TWAIN devices installed on the system.

Use the TwainGetSources method to return the source names and detailed information about each device.

JavaScript
var sourceList = DocuViewareAPI.TwainGetSources("DocuVieware1");
if (sourceList != null) {
    var source = sourceList.defaultSource;
    console.log("Default source is " + source);
} else {
    console.log("No available sources have been found.");
}

Define the acquisition parameters

Set acquisition parameters at any point in the process. You can configure parameters for subsequent acquisitions or set them between batches to use different options.

Call TwainSetConfig to set common acquisition parameters such as bit depth, resolution, duplex mode, and whether to show the device driver UI for advanced configuration.

For a 24-bit, 200 DPI acquisition from the document feeder without showing the device driver UI and with red color dropout enabled, use:

JavaScript
DocuViewareAPI.TwainSetConfig("DocuVieware1", true, true, 200, 24, false, true, [
    { capability: DocuViewareAPI.TwainCapabilities.ICAP_FILTER, value: "0" }
]);

Acquire from the source

With everything configured, proceed with the acquisition. Choose where the acquired pages should go:

  • New document — The acquired pages create a new document containing only the pages from this batch.
  • Append to existing document — The acquired pages are added to the currently loaded document.

For acquisition to a new document, call TwainAcquireToNewDocument and provide the source name.

To append pages to the existing document, call TwainAcquireToCurrentDocument. This method includes an extra parameter to set the position: at the end of the document, before the current page, or after the current page.

To acquire pages at the end of the currently loaded document from a device called “TWAIN2 FreeImage Software Scanner” (virtual scanning device from the TWAIN Group), use:

JavaScript
DocuViewareAPI.TwainAcquireToCurrentDocument("DocuVieware1", "TWAIN2 FreeImage Software Scanner", 1);

Next steps

After acquiring content in your DocuVieware instance, save the document. In DocuVieware, the current document exists only on the server side, so several options are available for saving.

To save the document locally (on the client machine), use the built-in Save feature. Alternatively, use the Print feature and select PDF as the output instead of a printer.

To save the document server side (to push it into a database or export to a filesystem), implement a custom action. Refer to the custom actions guide to learn more.

The document acquired in DocuVieware takes the form of a multipage image document. You can keep it as is and save it in TIFF format (the preferred format for this case), or convert it to another format such as PDF. In both cases, call either the SaveAsTIFF or SaveAsPDF method.