In This Topic
Tutorials / TWAIN Acquisition in DocuVieware

TWAIN Acquisition in DocuVieware

In This Topic

Although part of the daily work in many document workflows, TWAIN acquisition in web applications is not as straightforward in a traditional Windows application for several technical reasons.
The first is that a web application is not able to access certain resources of the system for obvious security reasons, instead, the web applications work in a kind of sandbox with limited rights and access.
The other difficulty is the fact that the web application comes in two separate parts, client and server, which must communicate. But the server part has no access to the client system in this context.

It would be tempting to use the many TWAIN methods and options already present in GdPicture.NET™ for this but, for the reasons mentioned above, only devices connected to the server would be visible.

 TWAIN and DocuVieware

To overcome these technical difficulties, DocuVieware™ offers a simple and transparent tool that allows the connection and communication between the web application and the TWAIN acquisition devices.

This tool is a lightweight, self-contained, secured software component that installs locally on the client machine (this is a one-time operation).
This component is available as an MSI package that is embedded and served by DocuVieware™ directly. This way you are assured that you users always have the right version.

The TWAIN acquisition capabilities of DocuVieware™ are very easy to use since they are built-in and enabled by default through the EnableTwainAcquisitionButton property.
It comes with standard support for any TWAIN compliant acquisition device and a dedicated acquisition dialog that lets you choose the source and the destination of the acquired pages (either append to the currently loaded document or into a new one).

While this might be enough for many cases, sometimes you may need a finer control over the process and the acquisition options in your business process.
In this case, you can use the JavaScript client API to take control of the TWAIN acquisition and customize its behavior as needed as described in the next part.

Whether you use the default built-in feature or implement your own acquisition process with the API, the acquisition result is the same: all acquired pages will automatically go directly into the corresponding DocuVieware™ instance to be handled just like any other document.
This makes the process consistent and natural regardless of the source, whether it is a document open from a local, remote source or an acquired document.

 Potential issues and troubleshooting

The local service is compiled and run in 32-bit mode, even on 64-bit Windows operating systems. The goal is to maximise device compatibility, so it works for everyone and it turns out every TWAIN device has a 32-bit driver, 64-bit drivers are still too rare. The counterpart of this is that the allocable memory is smaller which means that you may reach a memory limit at some point making the acquisition process slower and slower and in some cases even eventually stop.

Unfortunately, there is no universal formula for calculating this memory limit because it depends on many factors (Windows version, the amount of physical RAM on the system, how much allocable memory is left available for applications, acquisition settings, etc...) and can be very different from one system to another. Therefore, the most effective way to determine this limit is to test the actual conditions of your application (number of pages, quality, colour or not, etc...) and see if the process comes to an end correctly.

If you're reaching some kind of limitation, there are a few things you can try to mitigate it easily, the general idea being to reduce the overall size of the acquisition.                

  • Check the acquisition parameters and especially the resolution and colour bit depth. Acquiring several pages at 600 DPI with 32-bit colour will consume a lot of memory so if the documents can be acquired at 200 DPI in black and white instead, the memory needed for the acquisition will be dramatically reduced, and the process will run much more smoothly.
  • In case the documents have to be acquired at high resolution then the other lever on which to act is the size of the batch. For instance, if the acquisition stops after 15 pages instead of acquiring 20 or 30 pages in a single row, you can split the operation into 2 or 3 subsequent batches of 10 pages each (those are arbitrary values for the example, not a golden rule) to work around the memory limit.
  • Finally, depending on your business needs and requirements, you could also build your own TWAIN acquisition process and control all aspects and options. This may allow you to lock certain options and thus prevent the user from using excessive settings and possible memory problems that may result.
 Custom TWAIN Acquisition Process Walkthrough

Here is the workflow that must be followed to proceed with the TWAIN acquisition using the API. For this example let's assume your DocuVieware™ instance is called DocuVieware1.

  1. Check for local service status

    This is done by simply calling the TwainGetLocalServiceStatus method, as documented, it returns a value that will let you know if the local service is either ready, not responding or if the wrong version is running.

    In case the service is not running (or if the wrong version is running) you can start the download process of the latest version by calling the TwainDownloadServiceSetup method.

    This software will require administrative rights to be installed on the client machine.
    It is also recommended to close all the browsers before installing the package.
    The software will start automatically with Windows after installation.
    Checking the local service status.
    Copy Code
    var status = DocuViewareAPI.TwainGetLocalServiceStatus("DocuVieware1");
    if (status !== 0) {
       console.log("Local service cannot be accessed. Please install it now.");
  2. Retrieve the available devices

    Now that you know the service is up and running, you can retrieve the list of the TWAIN devices installed on the system.

    This is done using the TwainGetSources method that will not only return the source name but also a few details information about it in case you need it.

    Retrieving the available devices.
    Copy Code
    var sourceList = DocuViewareAPI.TwainGetSources("DocuVieware1");
    if (sourceList != null) {
       var source = sourceList.defaultSource;
       console.log("Default source is " + source);
    } else {
       console.log("No available source have been found.");
  3. Define the acquisition parameters

    This step can be done anytime in the process, it can set the parameters for the subsequent acquisitions or simply set the parameters for the next one so if you call it between two batches you can set different options.

    The method to call to do that is TwainSetConfig and it allows you to easily set the most common acquisition parameters such as the bit depth, resolution, duplex, if you want the device driver UI to be shown for advanced configuration or if you want it hidden.
    It also allows you to set advanced options if the scanning device supports it.

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

    Defining the parameters.
    Copy Code
    DocuViewareAPI.TwainSetConfig("DocuVieware1", true, true, 200, 24, false, true, [{ capability: DocuViewareAPI.TwainCapabilities.ICAP_FILTER, value: "0" }]);
  4. Acquire from the source

    Everything is ready, you can proceed with the acquisition itself. The only thing left to choose now is where the acquired pages should go.

    Two options are available, you can acquire to a new document so it will only contain the pages from the batch, or, you can choose to append the pages to the existing document (currently loaded document).

    For acquisition to a new document, the method to call is TwainAcquireToNewDocument and you just need to provide the source name you want to acquire from.

    If you want to go with option two, you can also choose where you want to append the new pages. It can be at the end of the document, before the current page or after the current page. In any case, the method to do that is TwainAcquireToCurrentDocument.
    It is basically the same but with an extra parameter to set the position.

    Let's assume we want 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) that would be:

    Acquiring from the source.
    Copy Code
    DocuViewareAPI.TwainAcquireToCurrentDocument("DocuVieware1", "TWAIN2 FreeImage Software Scanner", 1);
 What to do next?

Now that you have acquired content in your DocuVieware™ instance, you can save the document. As always in DocuVieware™, the current document only exists server side so to proceed with the file saving operation there are a few different options.

To save the document locally (on client machine) the built-in Save feature is available, it can also be done using the Print feature (and choose PDF over printer for output).

However, if you need to save the document server side (to push it into a database or to export it to a filesystem of some sort for instance) then, you will need to implement a Custom Action so please refer to the corresponding tutorial to learn more.

Technically speaking, the document acquired in DocuVieware™ takes the form of a multipage image document.
You are free to keep it as is (and save it in TIFF, the document format of choice for this case) or to convert it to another format more adapted to your needs like the PDF for example. In both cases, you can achieve it by simply calling either the SaveAsTIFF or SaveAsPDF method.

See Also