{WebTwainObject} Scan

The properties and methods on this page live in the namespace {WebTwainObject}. {WebTwainObject} denotes the WebTwain instance. Learn more about creating WebTwain instances here.

1. The following APIs are compatible with TWAIN, ICA, and SANE (Windows, macOS and Linux)

Methods

Properties

Events

2. The following APIs are compatible with TWAIN and ICA

Methods

3. The following APIs are compatible with TWAIN (mostly Windows, but also possibly macOS)

Methods

Properties

Events

AcquireImage()

Request a scan, then store to the image buffer of the WebTwain instance upon completion of the scan. By default, the scans are displayed from the dwtcontrolContainer container.

Syntax

AcquireImage(): void;

AcquireImage(
  deviceConfiguration: DeviceConfiguration
): void;

AcquireImage(
  successCallBack: () => void,
  failureCallBack: (
    errorCode: number,
    errorString: string) => void
): void;

AcquireImage(
  deviceConfiguration: DeviceConfiguration,
  successCallBack: () => void,
  failureCallBack: (
      deviceConfiguration: DeviceConfiguration,
      errorCode: number,
      errorString: string) => void
): void;

Parameters

deviceConfiguration: Configuration for the acquisition. Please refer to DeviceConfiguration.

successCallback: A callback function that is executed if the request succeeds.

failureCallback: A callback function that is executed if the request fails.

• errorCode: The error code.
• errorString: The error string.

Availability

Example

The example code shows 4 ways to use the API AcquireImage()

var deviceConfiguration = {
  IfShowUI: false,
  PixelType: Dynamsoft.DWT.EnumDWT_PixelType.TWPT_RGB,
  Resolution: 300,
  IfFeederEnabled: true,
  IfDuplexEnabled: false,
  IfDisableSourceAfterAcquire: true,
  IfGetImageInfo: true,
  IfGetExtImageInfo: true,
  extendedImageInfoQueryLevel: 0,
  IfCloseSourceAfterAcquire: true,
};

function successCallback() {
  DWTObject.CloseSource();
  console.log("successful");
}

function failureCallback(errorCode, errorString) {
  DWTObject.CloseSource();
  alert(errorString);
}

function AcquireImage1() {
  DWTObject.SelectSource(function () {
    DWTObject.OpenSource();
    DWTObject.IfShowUI = false;
    DWTObject.PixelType = Dynamsoft.DWT.EnumDWT_PixelType.TWPT_RGB;
    DWTObject.Resolution = 300;
    DWTObject.IfFeederEnabled = true;
    DWTObject.IfDuplexEnabled = false;
    DWTObject.IfDisableSourceAfterAcquire = true;
    DWTObject.AcquireImage();
  }, failureCallback);
}

function AcquireImage2() {
  DWTObject.SelectSource(function () {
    DWTObject.OpenSource();
    DWTObject.AcquireImage(deviceConfiguration);
  }, failureCallback);
}

function AcquireImage3() {
  DWTObject.SelectSource(function () {
    DWTObject.OpenSource();
    DWTObject.IfShowUI = false;
    DWTObject.PixelType = Dynamsoft.DWT.EnumDWT_PixelType.TWPT_RGB;
    DWTObject.Resolution = 300;
    DWTObject.IfFeederEnabled = true;
    DWTObject.IfDuplexEnabled = false;
    DWTObject.IfDisableSourceAfterAcquire = true;
    DWTObject.AcquireImage(successCallback, failureCallback);
  }, failureCallback);
}

function AcquireImage4() {
  DWTObject.SelectSource(function () {
    DWTObject.OpenSource();
    DWTObject.AcquireImage(
      deviceConfiguration,
      successCallback,
      failureCallback
    );
  }, failureCallback);
}

CloseSource()

Close the data source (a TWAIN/ICA/SANE device, which in most cases is a scanner) to free it to be used by other applications.

Syntax

CloseSource(): boolean;

Availability

Example

// Close the scanner source in the success/failure callback after all images are acquired. In this case, the source can be freed and used by others.
DWTObject.OpenSource();
DWTObject.AcquireImage(successCallback,failureCallback);

function successCallback() {
  console.log("successful");
  DWTObject.CloseSource();
}

function failureCallback(errorCode, errorString) {
  alert(errorString);
  DWTObject.CloseSource();
}

CloseSourceAsync()

Close the data source (a TWAIN/ICA/SANE device, which in most cases is a scanner) to free it to be used by other applications.

Syntax

CloseSourceAsync(): Promise<boolean>;

Availability

DisableSource()

Disable the data source (a TWAIN/ICA/SANE device, which in most cases is a scanner) to stop the acquisition process. This also closes the data source’s user interface, if it is displayed.

Syntax

DisableSource(): boolean;

Availability

Usage notes

After calling DisableSource(), the data source remains open, and you can continue to acquire images by calling AcquireImage() or EnableSource().

EnableSource()

Enable the data source to start the acquisition process.

Syntax

EnableSource(): boolean;

Availability

Usage notes

The method is equivalent to AcquireImage() without parameters.

EnableSourceUI()

Display the TWAIN source’s built-in user interface.

Syntax

EnableSourceUI(
    successCallBack: () => void,
    failureCallBack: (errorCode: number, errorString: string) => void
): boolean;

Parameters

successCallback: A callback function that is executed if the request succeeds.

failureCallback: A callback function that is executed if the request fails.

• errorCode: The error code.
• errorString: The error string.

Availability

Usage notes

This method enables the user to manipulate the scan settings without actually starting a scan. It only works if the source supports the capability CAP_ENABLEDSUIONLY. You can call GetCustomDSDataEx() to save the settings in the callback successCallBack. You can then call SetCustomDSDataEx() at a later time to apply these settings before starting a scan.

OpenSource()

Load a data source to prepare it for image acquisition.

Syntax

OpenSource(): boolean;

Availability

Example

DWTObject.GetSourceNames(); // for example ['PaperStream IP fi-7300NX Net', 'TWAIN2 FreeImage Software Scanner']
DWTObject.SelectSourceByIndex(0); // choose scanner with the name "PaperStream IP fi-7300NX Net"
DWTObject.OpenSource();
DWTObject.AcquireImage(successCallback, failureCallback);

function successCallback() {
  DWTObject.CloseSource();
  console.log("successful");
}

function failureCallback(errorCode, errorString) {
  DWTObject.CloseSource();
  alert(errorString);
}

OpenSourceAsync()

Load a data source to prepare it for image acquisition.

Syntax

OpenSourceAsync(): Promise<boolean>;

Availability

GetSourceNames()

Return all available data sources (scanners, etc.), and optionally all detailed information about them.

Syntax

GetSourceNames(bIncludeDetails?: boolean): string[] | SourceDetails[];

Parameters

bIncludeDetails: Whether to return more details about the data sources or just their names.

Arguments

SourceDetails: Please refer to SourceDetails.

Availability

Example

DWTObject.GetSourceNames(); // return a list of scanner sources such as ['PaperStream IP fi-7300NX Net', 'TWAIN2 FreeImage Software Scanner']

GetSourceNamesAsync()

Return all available data sources (scanners, etc.) and optionally all detailed information about them.

Syntax

GetSourceNamesAsync(bIncludeDetails: boolean): Promise<string[] | ISourceDetails[]>;

Parameters

bIncludeDetails: Whether to return more details about the data sources or just their names.

Availability

SelectSource()

Bring up the Source Selection User Interface (UI) for the user to choose a data source.

Syntax

SelectSource(): boolean | string;

// Call this API asynchronously to avoid blocking the browser's main thread 
SelectSource(
    successCallBack: () => void,
    failureCallBack: (errorCode: number, errorString: string) => void
): void;

Parameters

successCallback: A callback function that is executed if the request succeeds.

failureCallback: A callback function that is executed if the request fails.

• errorCode: The error code.
• errorString: The error string.

Availability

Usage notes

• We recommend calling this API asynchronously by passing arguments to successCallback and failureCallback.
• Windows only: you can call this API without arguments, in which case it runs synchronously and returns a boolean value.

Example

DWTObject.SelectSource(
  function () {
    DWTObject.OpenSource();
    DWTObject.AcquireImage(successCallback, failureCallback);
  },
  function (errorCode, errorString) {
    console.log(errorString);
  }
);

function successCallback() {
  DWTObject.CloseSource();
  console.log("successful");
}

function failureCallback(errorCode, errorString) {
  DWTObject.CloseSource();
  console.log(errorString);
}

SelectSourceAsync()

Bring up the Source Selection User Interface (UI) for the user to choose a data source.

Syntax

SelectSourceAsync(deviceType?: Dynamsoft.DWT.EnumDWT_DeviceType | number): Promise<number>;

Parameters

deviceType: Specify the device type of scanners. Please refer to EnumDWT_DeviceType.

Availability

Example

DWTObject.SelectSourceAsync()
  .then(function (sourceIndex) {
    console.log(sourceIndex);
    return DWTObject.AcquireImageAsync({
      IfCloseSourceAfterAcquire: true,
    });
  })
  .catch(function (e) {
    console.log(e);
  });

SelectSourceByIndex()

Select a data source by its index.

Syntax

SelectSourceByIndex(index: number): boolean;

Parameters

index: The index of the data source.

Availability

Example

DWTObject.GetSourceNames(); // for example ['PaperStream IP fi-7300NX Net', 'TWAIN2 FreeImage Software Scanner']
DWTObject.SelectSourceByIndex(0); // choose scanner with the name "PaperStream IP fi-7300NX Net"
DWTObject.OpenSource();
DWTObject.AcquireImage(successCallback, failureCallback);

function successCallback() {
  DWTObject.CloseSource();
  console.log("successful");
}

function failureCallback(errorCode, errorString) {
  DWTObject.CloseSource();
  console.log(errorString);
}

SelectSourceByIndexAsync()

Select a data source by its index.

Syntax

SelectSourceByIndexAsync(index: number): Promise<boolean>;

Parameters

index: The index of the data source.

Availability

Example

DWTObject.SelectSourceByIndexAsync(0)
  .then(() => {
    return DWTObject.OpenSourceAsync();
  })
  .then(() => {
    return DWTObject.AcquireImageAsync({
      IfCloseSourceAfterAcquire: true,
    });
  });

SetOpenSourceTimeout()

Set a timer which stops the data source opening process once it expires.

Syntax

SetOpenSourceTimeout(duration: number): boolean;

Parameters

duration: Set the duration of the timer (in milliseconds).

Availability

Example

DWTObject.SelectSource(function () {
  DWTObject.SetOpenSourceTimeout(3000); // stop the opening process if the source cannot be opened within 3000 ms.
  DWTObject.OpenSource();
  DWTObject.AcquireImage();
});

startScan()

Start the acquisition by passing all settings at once.

Syntax

startScan(scanSetup: ScanSetup): Promise<ScanSetup>;

Parameters

scanSetup: Configuration for the acquisition. Please refer to ScanSetup.

Availability

Sample

Make use of the API startScan

CancelAllPendingTransfers()

Cancel all pending transfers.

Syntax

CancelAllPendingTransfers(): boolean;

Availability

Usage notes

This method is only valid in the events OnPreAllTransfers, OnPreTransfer and OnPostTransfer.

CloseSourceManager()

Close and unload the Data Source Manager.

Syntax

CloseSourceManager(): boolean;

Availability

Example

DWTObject.CloseSourceManager();

CloseSourceManagerAsync()

Close and unload the Data Source Manager.

Syntax

CloseSourceManagerAsync(): Promise<boolean>;

Availability

CloseWorkingProcess()

Close the scanning process to release resources on the machine.

Syntax

CloseWorkingProcess(): boolean;

Availability

Usage notes

In the HTML5 edition, Dynamic Web TWAIN uses a separate process to communicate with the scanners. When not scanning, you can choose to close this process to free up resources on the end user’s machine. (CPU, memory, etc.)

FeedPage()

Eject the current page and begin scanning the next page in the document feeder.

Syntax

FeedPage(): boolean;

Availability

Usage notes

Use this method after calling OpenSource(), and make sure IfFeederEnabled is true .

GetCustomDSData()

Get the custom data source data and save the data to a specified file.

Syntax

GetCustomDSData(fileName: string): boolean;

Parameters

fileName: The path of the file to save the data source data to.

Availability

Usage notes

Typically, the data source data file is set by the method SetCustomDSData().

Example

// Please note, the API only works for TWAIN driver.
DWTObject.GetCustomDSData("C:\\Users\\UserName\\Desktop\\ProfileName");

GetCustomDSDataEx()

Get custom DS data and return it in a base64 string.

Syntax

GetCustomDSDataEx(): string;

Availability

Usage notes

Typically, the data source data file is set by the method SetCustomDSDataEx().

Example

// Please note, the API only works for TWAIN driver.
DWTObject.GetCustomDSDataEx(); // Return a base64 string

GetSourceNameItems()

Get the name of a data source by its index in the data source manager source list.

Syntax

GetSourceNameItems(index: number): string;

Parameters

index: The index of the data source.

Availability

Example

DWTObject.GetSourceNames(); // [scanner 1, scanner 2, scanner 3...]
DWTObject.GetSourceNameItems(0); // return the name of scanner 1

OpenSourceManager()

Load and open the data source manager.

Syntax

OpenSourceManager(): boolean;

Availability

Usage notes

If application identification needs to be set, it should be set before calling this API.

Example

DWTObject.OpenSourceManager(); 

OpenSourceManagerAsync()

Load and open the data source manager.

Syntax

OpenSourceManagerAsync(): Promise<boolean>;

Availability

Usage notes

If application identification needs to be set, it should be set before calling this API.

ResetImageLayout()

Reset the image layout in the data source.

Syntax

ResetImageLayout(): boolean;

Availability

Usage notes

You can use SetImageLayout() to set the image layout manually.

RewindPage()

If called while the {IfFeederEnabled} property is true, the data source will return the current page to the input area, and return the last page from the output area into the acquisition area.

Syntax

RewindPage(): boolean;

Availability

Usage notes

Use this API after calling OpenSource(), and make sure IfFeederEnabled is true .

SetCustomDSData()

Set custom data source data to be used for scanning. The data is stored in a file which may be regarded as a scanning profile.

Syntax

SetCustomDSData(fileName: string): boolean;

Parameters

fileName: The path of the file.

Availability

Usage notes

Typically, the data source data file is created by the method GetCustomDSData().

Example

// Please note, the API only works for TWAIN driver.
DWTObject.SetCustomDSData("C:\\Users\\UserName\\Desktop\\ProfileName");

SetCustomDSDataEx()

Set custom data source data to be used for scanning. The input format is a base64 string.

Syntax

SetCustomDSDataEx(dsDataString: string): boolean;

Parameters

dsDataString: The string that contains custom data source data.

Availability

Usage notes

Typically the data source data string is created by the method GetCustomDSDataEx()

// Please note, the API only works for TWAIN driver.
DWTObject.SetCustomDSData("the base64 string of your profile");

SetFileXferInfo()

Set the file transfer information to be used in File Transfer mode.

Syntax

SetFileXferInfo(
    fileName: string,
    fileFormat: Dynamsoft.DWT.EnumDWT_FileFormat | number
): boolean;

Parameters

fileName: The path to transfer the file to.

fileFormat: The format of the file.

Availability

Usage notes

Make sure the format you set is supported by the data source.

Example argument for the parameter fileName

• “C:\webtwain.jpg”: The next scanned image will be compressed as a JPEG file named webtwain and transferred to “C:\”.
• “C:\webtwain” + <> + “.jpg”: The scanned images will result in “C:\webtwain1.jpg”, “C:\webtwain2.jpg”, “C:\webtwain3.jpg”, etc.
• “C:\webtwain” + <%06d> + “.jpg”: The scanned images will result in “C:\webtwain000001.jpg”, “C:\webtwain000002.jpg”, “C:\webtwain000003.jpg”, etc.

Available file formats are defined in Dynamsoft.DWT.EnumDWT_FileFormat.

Example

DWTObject.OpenSource();
DWTObject.TransferMode = Dynamsoft.DWT.EnumDWT_TransferMode.TWSX_FILE;
if (DWTObject.TransferMode === Dynamsoft.DWT.EnumDWT_TransferMode.TWSX_FILE) {
    if (
        DWTObject.SetFileXferInfo(
            "C:\\Temp\\WebTWAIN<%06d>.bmp",
            Dynamsoft.DWT.EnumDWT_FileFormat.TWFF_BMP
        )
    ) {
          DWTObject.IfShowUI = true;
          DWTObject.AcquireImage(successCallback, failureCallback);
    }
}

function successCallback() {
  DWTObject.CloseSource();
  console.log("successful");
}

function failureCallback(errorCode, errorString) {
  DWTObject.CloseSource();
  console.log(errorString);
}

SetImageLayout()

Set the image layout rectangle for the current data source by specifying the rectangle’s left, top, right, and bottom sides, respectively. The image layout rectangle defines a frame of the data source’s scanning area to be acquired.

Syntax

SetImageLayout(
    left: number,
    top: number,
    right: number,
    bottom: number
): boolean;

Parameters

left: Specify the rectangle (leftmost coordinate).

top: Specify the rectangle (topmost coordinate).

right: Specify the rectangle (rightmost coordinate).

bottom: Specify the rectangle (bottommost coordinate).

Availability

Usage notes

The arguments set to the parameters left , top , right , bottom are expressed in the measurement unit defined by the Unit property, which is inches by default.

This API is device-dependent. If a data source does not support customizing the scan area, this method might not work correctly.

Since there are several ways to negotiate the scan area, it becomes confusing when deciding what should take precedence.

The TWAIN Working Group has suggested the following behavior:

• Setting the frame with SetImageLayout() shall be equivalent to setting the frame with CapGetFrameBottom(), CapGetFrameLeft(), CapGetFrameRight(), CapGetFrameTop() and the property PageSize shall return TWSS_NONE (0).
• If the current frame is set from negotiating the capability ICAP_FRAMES with the method CapSetFrame(), the property PageSize shall return TWSS_NONE (0) and the image layout shall reflect the same frame with the properties ImageLayoutFrameBottom, ImageLayoutFrameLeft, ImageLayoutFrameRight and ImageLayoutFrameTop.
• If the current fixed frame is set by the property PageSize, the same dimensions shall be reflected in the APIs CapGetFrameBottom(), CapGetFrameLeft(), CapGetFrameRight(), CapGetFrameTop() as well as ImageLayoutFrameBottom, ImageLayoutFrameLeft, ImageLayoutFrameRight and ImageLayoutFrameTop. Note, however, the orientation (in other words, whether it’s in the portrait mole or landscape mode) also plays a role in the order of the values.

Example

DWTObject.SelectSource();
DWTObject.OpenSource();
DWTObject.IfShowUI = false;
DWTObject.Unit = Dynamsoft.DWT.EnumDWT_UnitType.TWUN_PIXELS;
DWTObject.SetImageLayout(50, 50, 100, 100);
DWTObject.AcquireImage(successCallback, failureCallback);

function successCallback() {
  DWTObject.CloseSource();
  console.log("successful");
}

function failureCallback(errorCode, errorString) {
  DWTObject.CloseSource();
  console.log(errorString);
}

BitDepth

Return or set the pixel bit depth for the current color mode (defined by PixelType).

Syntax

BitDepth: number;

Availability

Usage notes

Set this property after OpenSource() and before AcquireImage() for the desired bit depth to take effect upon calling AcquireImage().

The default bit depth is 1 for TWPT_BW , 8 for TWPT_GRAY and 24 for TWPT_RGB .

IfAppendImage

Return or set whether newly acquired images are inserted or appended to the image buffer.

Syntax

IfAppendImage: boolean;

Availability

Usage notes

The value of this property defaults to true, meaning that the newly acquired image will be appended to the last image in the buffer.

If it’s set to false , the images will be inserted before the current image. Note that by design, the current image is always the previously acquired image. This means that the images acquired after setting IfAppendImage to false will be displayed/retained in reverse order.

Read this article learn how to insert new images to a specified index in the image buffer.

IfDisableSourceAfterAcquire

Return or set whether or not to disable the scanner (i.e., the image source) after acquiring all images. When this property is set to true and the scanning UI is open, this setting simultaneously closes the scanning UI when disabling the image source.

Syntax

IfDisableSourceAfterAcquire: boolean;

Availability

Example

DWTObject.OpenSource();
DWTObject.IfDisableSourceAfterAcquire = true; // Close the scanner UI after images acquired.
DWTObject.IfShowUI = true;
DWTObject.AcquireImage(successCallback,failureCallback);

function successCallback() {
    DWTObject.CloseSource();
}

function failureCallback(errorCode, errorString) {
    DWTObject.CloseSource();
}

IfDuplexEnabled

Return or set whether or not to enable duplex scanning (scanning both sides of the paper).

Syntax

IfDuplexEnabled: boolean;

Availability

Usage notes

Set this property after calling OpenSource() and before calling AcquireImage() for the setting to take effect upon calling AcquireImage().

Not all scanners support duplex scanning. To confirm, check the user manual of the device or check the value of Duplex after calling OpenSource().

Example

DWTObject.OpenSource();

if (DWTObject.Duplex != 0) { // Note: DWTObject.Duplex doesn't support Linux.
    DWTObject.IfDuplexEnabled = true;
}

DWTObject.AcquireImage(successCallback, failureCallback);

function successCallback() {
  DWTObject.CloseSource();
  console.log("successful");
}

function failureCallback(errorCode, errorString) {
  DWTObject.CloseSource();
  console.log(errorString);
}

IfFeederEnabled

Return or set whether or not a data source’s Automatic Document Feeder (ADF) is enabled for scanning.

Syntax

IfFeederEnabled: boolean;

Availability

Usage notes

Set this property after OpenSource() and before AcquireImage() for the setting to take effect upon calling AcquireImage().

If the property is set to true, the data source attempt to acquire images from the document feeder first. Otherwise, if the data source does not have a document feeder, the data source will use the flatbed.

Example

DWTObject.OpenSource();
DWTObject.IfFeederEnabled = true;
DWTObject.AcquireImage(successCallback, failureCallback);

function successCallback() {
  DWTObject.CloseSource();
  console.log("successful");
}

function failureCallback(errorCode, errorString) {
  DWTObject.CloseSource();
  console.log(errorString);
}

IfShowUI

Return or set whether or not the data source displays the user interface when scanning.

Syntax

IfShowUI: boolean;

Availability

Usage notes

when the property is set to true, the data source displays its user interface when AcquireImage() is called. Otherwise, the scan starts immediately without displaying the UI.

It is recommended to use this API after OpenSource() is called.

Example

DWTObject.OpenSource();
DWTObject.IfShowUI = true; // display the scanner UI before acquiring image
DWTObject.AcquireImage(successCallback, failureCallback);

function successCallback() {
  DWTObject.CloseSource();
  console.log("successful");
}

function failureCallback(errorCode, errorString) {
  DWTObject.CloseSource();
  console.log(errorString);
}

ImageCaptureDriverType

Return or set the driver type, which determines the type of sources to use.

Syntax

ImageCaptureDriverType: Dynamsoft.DWT.EnumDWT_Driver | number;

Availability

Usage notes

Set this property immediately after initializing the SDK, or after calling CloseSourceManager() and OpenSourceManager().

The allowed values for EnumDWT_Driver are

PageSize

Return or set the page size that the data source uses to acquire images.

Syntax

PageSize: Dynamsoft.DWT.EnumDWT_CapSupportedSizes | number;

Parameters

PageSize: Please refer to EnumDWT_CapSupportedSizes

Availability

Usage notes

Set this property after OpenSource() and before AcquireImage() for the setting to take effect upon calling AcquireImage().

PixelType

Return or set the pixel type used when acquiring images.

Syntax

PixelType: Dynamsoft.DWT.EnumDWT_PixelType | number;

Please refer to EnumDWT_PixelType.

Availability

Usage notes

Set this property after OpenSource() and before AcquireImage() for the setting to take effect upon calling AcquireImage().

Resolution

Return or set the resolution used when acquiring images.

Syntax

Resolution: number;

Availability

Usage notes

Set this property after OpenSource() and before AcquireImage() for the setting to take effect upon calling AcquireImage().

SourceCount

Return the number of data sources available on the local system.

Syntax

readonly SourceCount: number;

Availability

BlankImageThreshold

Return or set the blank image detection threshold. Higher values are lenient (higher likelihood of detecting blank pages), and lower values are stringent (lower likelihood of detecting blank pages).

Syntax

BlankImageThreshold: number;

Availability

Usage notes

BlankImageThreshold ranges from 0 to 255, and is 128 by default. This property only takes effect when PixelType is set to TWPT_BW . The bigger the value is, the more likely it is for an image to be classified as blank.

Brightness

Return or set the brightness value used for scanning by the data source.

Syntax

Brightness: number;

Availability

Usage notes

Set this property after OpenSource() and before AcquireImage() for the setting to take effect upon calling AcquireImage().

Typically, the value range is -1000 ~ 1000 where -1000 indicates the darkest and 1000 the brightest.

Contrast

Return or set the contrast value used for scanning by the data source.

Syntax

Contrast: number;

Availability

Usage notes

Set this property after OpenSource() and before AcquireImage() for the setting to take effect upon calling AcquireImage().

Typically, the value range is -1000 ~ 1000, where -1000 indicates the lowest contrast and 1000 the highest contrast.

CurrentSourceName

Return the device name of the current data source.

Syntax

readonly CurrentSourceName: string;

Availability

Usage notes

If no source is currently selected, this property returns “”.

DataSourceStatus

Return the data source status code.

Syntax

DataSourceStatus: number;

Availability

Usage notes

DefaultSourceName

Return the name of the last used source.

Syntax

DefaultSourceName: string;

Availability

Duplex

Indicate if the data source supports 1-pass duplex scanning, 2-pass duplex scanning, or does not support duplex scanning at all.

Syntax

readonly Duplex: Dynamsoft.DWT.EnumDWT_DUPLEX | number;

Availability

Usage notes

1-pass means the paper gets scanned on both sides at the same time. 2-pass means the paper passes the light bar twice to get both sides scanned separately.

This property is not supported on Linux.

IfAutoBright

Return or set whether or not to enable the data source’s auto-brightness feature.

Syntax

IfAutoBright: boolean;

Availability

IfAutoDiscardBlankpages

Return or set whether or not the data source automatically discards blank images during scanning.

Syntax

IfAutoDiscardBlankpages: boolean;

Availability

Usage notes

This property works only if the device and its driver support discarding blank pages. You can find whether your device supports this capability from the device’s user manual.

Alternatively, the Dynamic Web TWAIN library can also detect blank images after they are transferred.

IfAutoFeed

Return or set whether or not to enable the data source’s automatic document feeding feature.

Syntax

IfAutoFeed: boolean;

Availability

Usage notes

If set to true , the data source will automatically feed the next page from the document feeder as soon as the previous page is scanned.

IfAutomaticBorderDetection

Return or set whether or not to enable the data source’s automatic border detection feature.

Syntax

IfAutomaticBorderDetection: boolean;

Availability

Usage notes

The property works only if the device and its driver support automatic border detection. You can check for device capability support in the device’s user manual.

Once enabled, the data source (scanner) automatically detects the borders of the document so as to not scan extra margins.

IfAutomaticDeskew

Return or set whether or not to enable the data source’s automatic skew correction feature.

Syntax

IfAutomaticDeskew: boolean;

Availability

Usage notes

The property works only if the device and its driver supports automatic de-skewing. You can check for device capability support in the device’s user manual.

IfAutoScan

Return or set whether or not to enable the data source’s automatic document scanning feature.

Syntax

IfAutoScan: boolean;

Availability

Usage notes

This property is only valid when IfFeederEnabled is set to true .

The fundamental assumption behind this property is that the device can capture the number of images indicated by the property XferCount without waiting for the Application to request the image transfers. This is only possible if the device has internal buffers capable of caching the images it captures.

IfFeederLoaded

Return whether or not there are documents loaded in the data source’s feeder.

Syntax

readonly IfFeederLoaded: boolean;

Availability

Usage notes

This property is only valid when IfFeederEnabled and IfPaperDetectable are true.

IfPaperDetectable

Return whether or not the Source has a paper sensor that can detect pages on the ADF or flatbed.

Syntax

readonly IfPaperDetectable: boolean;

Availability

Usage notes

Check this property after calling OpenSource().

IfShowIndicator

Return or set whether or not the data source displays a progress indicator during acquisition and transfer.

Syntax

IfShowIndicator: boolean;

Availability

Usage notes

This property works only when IfShowUI is set to false.

The indicator will only be hidden when both IfShowUI and IfShowIndicator are false .

IfUIControllable

Return whether or not the data source supports acquisitions with the UI (User Interface) disabled.

Syntax

readonly IfUIControllable: boolean;

Availability

Usage notes

Check this property after calling OpenSource().

IfUseTwainDSM

Return or set whether or not to use the new TWAIN DSM (Data Source Manager) for acquisitions. The new TWAIN DSM is a DLL called TWAINDSM.dll while the default/old DSM is called twain_32.dll.

Syntax

IfUseTwainDSM: boolean;

Availability

Usage notes

This property should be set before calling or setting any TWAIN-related methods or properties.

ImageLayoutFrameBottom

Return the value of the bottom edge of the current image frame, with distance measured in Unit (defaults to inches).

Syntax

readonly ImageLayoutFrameBottom: number;

Availability

ImageLayoutFrameLeft

Return the value of the left edge of the current image frame, with distance measured in Unit (defaults to inches).

Syntax

readonly ImageLayoutFrameLeft: number;

Availability

ImageLayoutFrameNumber

Return the frame number of the current image.

Syntax

readonly ImageLayoutFrameNumber: number;

Availability

Usage Notes

Usually a chronological index of the acquired frames, these frames are related to one another in some way. Usually, they were acquired from the same page. The source assigns these values. The initial value is 1. The value resets upon acquiring a new image.

ImageLayoutFrameNumber property, along with other properties about the current image information, is valid only in the OnPreTransfer and OnPostTransfer events. The frame information here only applies to the current frame. To get information about all frames to be transferred in an acquire session, please use capability negotiation. In this case, the capability is ICAP_FRAMES (4372).

ImageLayoutFrameRight

Return the value of the right edge of the current image frame, with distance measured in Unit (defaults to inches).

Syntax

readonly ImageLayoutFrameRight: number;

Availability

ImageLayoutFrameTop

Return the value of the top edge of the current image frame, with distance measured in Unit (defaults to inches).

Syntax

readonly ImageLayoutFrameTop: number;

Availability

ImageLayoutDocumentNumber

Return the document number of the current image.

Syntax

readonly ImageLayoutDocumentNumber: number;

Availability

ImageLayoutPageNumber

Return the page number of the current image.

Syntax

readonly ImageLayoutPageNumber: number;

Availability

ImageBitsPerPixel

Return the bit depth of the current image.

Syntax

readonly ImageBitsPerPixel: number;

Availability

ImageLength

Return the length of the current image.

Syntax

readonly ImageLength: number;

Availability

ImageWidth

Return the width of the current image.

Syntax

readonly ImageWidth: number;

Availability

ImageXResolution

Return the horizontal resolution of the current image.

Syntax

readonly ImageXResolution: number;

Availability

ImageYResolution

Return the vertical resolution of the current image.

Syntax

readonly ImageYResolution: number;

Availability

ImagePixelType

Return the pixel type of the current image.

Syntax

readonly ImagePixelType: Dynamsoft.DWT.EnumDWT_PixelType | number;

Please refer to EnumDWT_PixelType.

Availability

MagData

Return magnetic data if the data source supports magnetic data recognition.

Syntax

readonly MagData: string;

Availability

MagType

Return the type of the magnetic data if the data source supports magnetic data recognition.

Syntax

readonly MagType: Dynamsoft.DWT.EnumDWT_MagType | number;

Please refer to EnumDWT_MagType.

Availability

Usage notes

The values returned by these APIs are expressed in the measurement unit defined by the Unit property, which is inches by default.

These APIs are only valid in the callbacks for the events OnPreTransfer and OnPostTransfer.

MagData and MagType are device-dependent. Check the user manual of the device to see if magnetic data recognition is supported.

PendingXfers

Return the number of transfers the data source is ready to supply upon demand.

Syntax

readonly PendingXfers: number;

Availability

Usage notes

This property is only valid in the event OnPostTransfer.

The data source returns -1 if it is not sure how many transfers are pending. This normally occurs when the ADF (Automatic Document Feeder) is used.

PixelFlavor

Return or set the pixel flavor used for acquiring images.

Syntax

PixelFlavor: number;

Availability

Usage notes

Available values:

• 0: Chocolate. Zero pixel represents darkest shade
• 1: Vanilla. Zero pixel represents lightest shade.

TransferMode

Return or set the data source’s transfer mode.

Syntax

TransferMode: Dynamsoft.DWT.EnumDWT_TransferMode | number;

Please refer to EnumDWT_TransferMode.

Availability

Usage notes

Allowed values are

• TWSX_NATIVE | 0: The default mode - this mode transfers the whole image in a single memory block.
• TWSX_FILE | 1: Transfer the image to a specified file on the disk directly. This mode is ideal when transferring large images that may encounter memory limits with Native mode. Check out SetFileXferInfo for more information.
• TWSX_MEMORY | 2: Transfer the image in multiple memory blocks. This mode is ideal for transferring very large images or a large number of images quickly.

TWSX_NATIVE and TWSX_MEMORY are required by all TWAIN data sources while TWSX_FILE is not. Therefore, make sure the data source supports TWSX_FILE before you use it.

Unit

Return or set the unit of measurement for all quantities. This setting only applies to TWAIN/ICA (hardware) -related operations.

Syntax

Unit: Dynamsoft.DWT.EnumDWT_UnitType | number;

Availability

Usage notes

Allowed values are

XferCount

Return or set the number of images the web application is willing to accept for each scan.

Syntax

XferCount: number;

Availability

Usage notes

Allowed values are between -1 and 215, where -1 indicate multiple images.

OnPostAllTransfers

This event triggers when all page(s) have been scanned and transferred.

Syntax

RegisterEvent("OnPostAllTransfers", function () {});

Availability

Usage notes

This event triggers after all pages in the document feeder have been scanned and transferred. This event is convenient for uploading the images, detecting barcodes, discarding blank pages, etc.

Example

DWTObject.RegisterEvent("OnPostAllTransfers", function () {
  console.log("All images are transferred.");
});

OnPostTransfer

This event triggers after each page has been scanned and transferred.

Syntax

RegisterEvent("OnPostTransfer", function () {});

Availability

Example

DWTObject.RegisterEvent("OnPostTransfer", function () {
  console.log("An image has been scanned");
});

OnPostTransferAsync

This event triggers after each page has been scanned and transferred. This is the asynchronous counterpart to the synchronous event OnPostTransfer.

Syntax

RegisterEvent("OnPostTransferAsync", function (outputInfo: OutputInfo) {});

Parameters

outputInfo: Detailed information about the image that just got transferred. Please refer to OutputInfo.

Availability

Example

DWTObject.RegisterEvent("OnPostTransferAsync", function (outputInfo) {
  console.log("The image ID is " + outputInfo.imageId);
});

OnPreAllTransfers

This event triggers when all images are scanned and ready to be transferred.

Syntax

RegisterEvent("OnPreAllTransfers", function () {});

Availability

Usage notes

Multiple transfers may occur in two cases:

• Multiple images are scanned through the ADF(Auto Document Feeder)
• Multiple frames are scanned on one single page

Multiple transfers trigger the OnPreTransfer event multiple times but only triggers OnPreAllTransfers once.

In the callback function of this event, you can call CancelAllPendingTransfers() to cancel all transfers.

OnPreTransfer

This event triggers when a page has been scanned and is ready to be transferred.

Syntax

RegisterEvent('OnPreTransfer',function(){...});

Availability

Usage notes

In the callback function of this event, you can:

• Check PendingXFERs for the number of pending transfers.
• Get information about the transferred image, such as ImageLayoutDocumentNumber, ImageLayoutFrameLeft, ImageLayoutFrameTop, ImageLayoutFrameRight, ImageLayoutFrameBottom, ImageLayoutPageNumber, ImageLayoutFrameNumber, etc.
• Call CancelAllPendingTransfers() to cancel the rest of the transfers.

OnSourceUIClose

This event triggers when the user interface of the data source is closed manually by the user.

Syntax

RegisterEvent("OnSourceUIClose", function () {});

Availability

getCapabilities()

Get detailed information about specified or all capabilities of the current data source.

Syntax

getCapabilities(
    capabilities: Dynamsoft.DWT.EnumDWT_Cap[] | number[],
    successCallback: (capabilityDetails: CapabilityDetails[]) => void,
    failureCallback: (errorCode: number, errorString: string) => void
): void; 

getCapabilities(
    successCallback: (capabilityDetails: CapabilityDetails[]) => void,
    failureCallback: (errorCode: number, errorString: string) => void
): void;

Parameters

capabilities: Specifies the capabilities to query. Please refer to Dynamsoft.DWT.EnumDWT_Cap.

successCallback: A callback function that is executed if the request succeeds.

• capabilityDetails: Detailed information about the specified capabilities. Please refer to CapabilityDetails.

failureCallback: A callback function that is executed if the request fails.

• errorCode: The error code.
• errorString: The error string.

Availability

setCapabilities()

Set the value of one or more capabilities.

Syntax

setCapabilities(
    capabilities: Capabilities,
    successCallback: (capabilities: Capabilities) => void,
    failureCallback: (capabilities: Capabilities) => void
): boolean;

Parameters

capabilities: An object that contains capability values to be set.

successCallback: A callback function that is executed if the request succeeds.

• capabilities: The capabilities to set.

failureCallback: A callback function that is executed if the request fails.

• capabilities: The capabilities to set.

Please refer to Capabilities.

Availability

Usage notes

For simplicity, Dynamsoft designed the API with a simplified parameter Capabilities which only requires the minimum information to set a capability: a number to specify the capability and a value to set the capability to. DWT takes care of container type setting, value type setting as well as data validation, all behind the scene.

Take note of the overall exception parameter and the individual exception parameter for each capability. If the overall parameter is set to fail, the setting aborts upon encountering the first exception raised while setting any of the capabilities. If the overall parameter is set to fail, the API carries on setting the next capability upon encountering a exception setting a previous capability.

The individual exception argument is optional but takes precedence if set. In other words, you can set the overall exception to ignore and then set the individual one to fail for critical capabilities. This way, you get notified if these critical capabilities fail to be set, and ignore failing to set less important capabilities.

Example

DWTObject.SelectSourceByIndex(0);
DWTObject.IfShowUI = false;
DWTObject.OpenSource();
DWTObject.setCapabilities(
  {
    exception: "ignore",
    capabilities: [
      {
        capability: Dynamsoft.DWT.EnumDWT_Cap.ICAP_CONTRAST, // your own capability
        curValue: 500, // your own curValue
      },
      {
        capability: Dynamsoft.DWT.EnumDWT_Cap.CAP_PRINTERSTRING, // your own capability
        curValue: "abc", // your own curValue
        exception: "fail",
      },
      {
        capability: Dynamsoft.DWT.EnumDWT_Cap.ICAP_PIXELTYPE, // your own capability
        curValue: 0, // your own curValue
      },
    ],
  },
  function (successData) {
    DWTObject.AcquireImage(
      function () {
        DWTObject.CloseSource();
      },
      function () {
        DWTObject.CloseSource();
        console.log(DWTObject.ErrorString);
      }
    );
  },
  function (errorData) {
    console.error(errorData);
    DWTObject.AcquireImage(
      function () {
        DWTObject.CloseSource();
      },
      function () {
        DWTObject.CloseSource();
        console.log(DWTObject.ErrorString);
      }
    );
  }
);

GetDevicesAsync()

Return all available devices (scanners, eSCL scanners, etc.). Optionally, only return devices of a specified type.

Syntax

GetDevicesAsync(deviceType?: Dynamsoft.DWT.EnumDWT_DeviceType | number, refresh?:boolean): Promise<Device[]>;

Parameters

deviceType: The device type. Please refer to EnumDWT_DeviceType.

refresh: Default value is false.

Arguments

Device: Please refer to Device.

Example

DWTObject.GetDevicesAsync().then((deviceList)=>{
  return DWTObject.SelectDeviceAsync(deviceList[0])  //Select the first device
}).then(()=>{
    return DWTObject.AcquireImageAsync({
      IfCloseSourceAfterAcquire: true,
    }) 
}).catch((e)=>{
    console.error(e)
})

Availability

SelectDeviceAsync()

Select the device to be used for scanning.

Syntax

SelectDeviceAsync(device: Device): Promise< boolean>;

Example

DWTObject.GetDevicesAsync().then((deviceList)=>{
  return DWTObject.SelectDeviceAsync(deviceList[0])  //Select the first device
}).then(()=>{
    return DWTObject.AcquireImageAsync({
      IfCloseSourceAfterAcquire: true,
    }) 
}).catch((e)=>{
    console.error(e)
})

Parameters

device: the device object. Please refer to Device.

Availability

AcquireImageAsync()

Request a scan, then store to the image buffer of the WebTwain instance upon completion of the scan. By default, the scans are displayed from the dwtcontrolContainer container.

Syntax

AcquireImageAsync(deviceConfiguration?: DeviceConfiguration): Promise< boolean>;

Parameters

deviceConfiguration: The device configuration. Please refer to DeviceConfiguration.

Availability

Example

DWTObject.GetDevicesAsync().then((deviceList)=>{
  return DWTObject.SelectDeviceAsync(deviceList[0])  //Select the first device
}).then(()=>{
    return DWTObject.AcquireImageAsync({
      IfCloseSourceAfterAcquire: true,
    }) 
}).catch((e)=>{
    console.error(e)
})