Web Demos

BARCODE READER SDK DEMO

Explore the flexibe barcode reading settings to optimize for your specific usage scenario.

WEB TWAIN SDK DEMO

Try the most popular web scanner features: scan images, import local images and PDF files, edit, save to local, upload to database, and etc.

BARCODE READER JAVASCRIPT DEMO

Transform any camera-equipped devices into real-time, browser-based barcode and QR code scanners.

MRZ SCANNER WEB DEMO

Detects the machine-readable zone of a passport, scans the text, and parses into human-readable data.

APP STORE DEMOS

BARCODE READER SDK FOR IOS

BARCODE READER SDK FOR ANDROID

VIEW MORE DEMOS >
Dev Center
Table of contents

{WebTwainObject} Scan

The properties and methods on this page live in the namespace {WebTwainObject}. {WebTwainObject} denotes the WebTwain instance. Learn about how to create a web twain object.

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

Methods

       
GetSourceNameItems() GetSourceNames() GetSourceNamesAsync() SelectSource()
SelectSourceAsync() SelectSourceByIndex() SelectSourceByIndexAsync() SetOpenSourceTimeout()
OpenSource() OpenSourceAsync() EnableSourceUI() EnableSource()
AcquireImage() startScan() DisableSource() CloseSource()
CloseSourceAsync() CloseWorkingProcess() GetDevicesAsync() SelectDeviceAsync()
AcquireImageAsync()      

Properties

       
CurrentSourceName IfDisableSourceAfterAcquire IfDuplexEnabled IfFeederEnabled
PageSize PixelType Resolution SourceCount

Events

     
OnPostAllTransfers OnPostTransfer OnPostTransferAsync
OnPreAllTransfers OnPreTransfer  

2. The following APIs are compatible with TWAIN and ICA

Methods

   
getCapabilities() setCapabilities()

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

Methods

       
OpenSourceManager() OpenSourceManagerAsync() CloseSourceManager() CloseSourceManagerAsync()
GetCustomDSData() GetCustomDSDataEx() CancelAllPendingTransfers() FeedPage()
ResetImageLayout() RewindPage() SetCustomDSData() SetCustomDSDataEx()
SetFileXferInfo() SetImageLayout()    

Properties

       
BitDepth Brightness Contrast DataSourceStatus
DefaultSourceName Duplex IfAutoBright IfAutoDiscardBlankpages
IfAutoFeed IfAutomaticBorderDetection IfAutomaticDeskew IfAutoScan
IfFeederLoaded IfPaperDetectable IfShowIndicator IfShowUI
IfUIControllable IfUseTwainDSM ImageCaptureDriverType ImageLayoutDocumentNumber
ImageLayoutFrameBottom ImageLayoutFrameLeft ImageLayoutFrameNumber ImageLayoutFrameRight
ImageLayoutFrameTop ImageLayoutPageNumber ImagePixelType MagData
MagType PendingXfers PixelFlavor TransferMode
Unit XferCount IfAppendImage  

Events

 
OnSourceUIClose

AcquireImage

Start image acquisition.

Syntax

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

interface DeviceConfiguration {
    IfShowUI?: boolean; //Whether to show the built-in User Interface from the device vendor
    PixelType?: Dynamsoft.DWT.EnumDWT_PixelType | number | string; //Whether to scan in color, grey or black & white
    Resolution?: number; //Measured by dots per pixel (DPI)
    IfFeederEnabled?: boolean; //Whether to use the document feeder or the flatbed of the device
    IfDuplexEnabled?: boolean; //Whether to scan one side or both sides
    IfDisableSourceAfterAcquire?: boolean; //Whether to close the built-in User Interface after aquisition. Only valid when {IfShowUI} is true.
    IfGetImageInfo?: boolean; //Whether to retrieve information about the image after it's transferred.
    IfGetExtImageInfo?: boolean; //Whether to retrieve extended information about the image after it's transferred.
    extendedImageInfoQueryLevel?: Dynamsoft.DWT.EnumDWT_ExtImageInfo | number; //How much extended information is retrieved. Only valid when {IfGetExtImageInfo} is true.
    SelectSourceByIndex?: number; //Specify a source by its index.
    IfCloseSourceAfterAcquire?: boolean; //Whether to close the data source after aquisition. Default: false.
}

Parameters

deviceConfiguration: Configuration for the acquisition.

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v1.0+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

extendedImageInfoQueryLevel is 0 by default which means the following information will be retrieved (if available):

Label Value
TWEI_BARCODEX 0x1200
TWEI_BARCODEY 0x1201
TWEI_BARCODETEXT 0x1202
TWEI_BARCODETYPE 0x1203
TWEI_ENDORSEDTEXT 0x1213
TWEI_BARCODECONFIDENCE 0x121A
TWEI_BARCODEROTATION 0x121B
TWEI_BARCODETEXTLENGTH 0x121C
TWEI_BOOKNAME 0x1238
TWEI_CHAPTERNUMBER 0x1239
TWEI_DOCUMENTNUMBER 0x123A
TWEI_PAGENUMBER 0x123B
TWEI_CAMERA 0x123C
TWEI_FRAMENUMBER 0x123D
TWEI_FRAME 0x123E
TWEI_PIXELFLAVOR 0x123F
TWEI_MAGDATA 0x1243
TWEI_MAGTYPE 0x1244
TWEI_PAGESIDE 0x1245

If it’s set to 1, the following will also be retrieved (if available):

Label Value
TWEI_DESHADETOP 0x1204
TWEI_DESHADELEFT 0x1205
TWEI_DESHADEHEIGHT 0x1206
TWEI_DESHADEWIDTH 0x1207
TWEI_DESHADESIZE 0x1208
TWEI_SPECKLESREMOVED 0x1209
TWEI_HORZLINEXCOORD 0x120A
TWEI_HORZLINEYCOORD 0x120B
TWEI_HORZLINELENGTH 0x120C
TWEI_HORZLINETHICKNESS 0x120D
TWEI_VERTLINEXCOORD 0x120E
TWEI_VERTLINEYCOORD 0x120F
TWEI_VERTLINELENGTH 0x1210
TWEI_VERTLINETHICKNESS 0x1211
TWEI_PATCHCODE 0x1212
TWEI_FORMCONFIDENCE 0x1214
TWEI_FORMTEMPLATEMATCH 0x1215
TWEI_FORMTEMPLATEPAGEMATCH 0x1216
TWEI_FORMHORZDOCOFFSET 0x1217
TWEI_FORMVERTDOCOFFSET 0x1218
TWEI_BARCODECOUNT 0x1219
TWEI_DESHADECOUNT 0x121D
TWEI_DESHADEBLACKCOUNTOLD 0x121E
TWEI_DESHADEBLACKCOUNTNEW 0x121F
TWEI_DESHADEBLACKRLMIN 0x1220
TWEI_DESHADEBLACKRLMAX 0x1221
TWEI_DESHADEWHITECOUNTOLD 0x1222
TWEI_DESHADEWHITECOUNTNEW 0x1223
TWEI_DESHADEWHITERLMIN 0x1224
TWEI_DESHADEWHITERLAVE 0x1225
TWEI_DESHADEWHITERLMAX 0x1226
TWEI_BLACKSPECKLESREMOVED 0x1227
TWEI_WHITESPECKLESREMOVED 0x1228
TWEI_HORZLINECOUNT 0x1229
TWEI_VERTLINECOUNT 0x122A
TWEI_DESKEWSTATUS 0x122B
TWEI_SKEWORIGINALANGLE 0x122C
TWEI_SKEWFINALANGLE 0x122D
TWEI_SKEWCONFIDENCE 0x122E
TWEI_SKEWWINDOWX1 0x122F
TWEI_SKEWWINDOWY1 0x1230
TWEI_SKEWWINDOWX2 0x1231
TWEI_SKEWWINDOWY2 0x1232
TWEI_SKEWWINDOWX3 0x1233
TWEI_SKEWWINDOWY3 0x1234
TWEI_SKEWWINDOWX4 0x1235
TWEI_SKEWWINDOWY4 0x1236
TWEI_ICCPROFILE 0x1240
TWEI_LASTSEGMENT 0x1241
TWEI_SEGMENTNUMBER 0x1242
TWEI_FILESYSTEMSOURCE 0x1246
TWEI_IMAGEMERGED 0x1247
TWEI_MAGDATALENGTH 0x1248
TWEI_PAPERCOUNT 0x1249
TWEI_PRINTERTEXT 0x124A

If it’s set to 2, then besides what’s mentioned in the two tables above, the Dynamic Web TWAIN library will also try to query the scanner for its own custom extended image info.

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,
};

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

function failureCallback(errorCode, errorString) {
  alert(errorString);
}

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

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

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

function AcquireImage4() {
  DWObject.SelectSource(function () {
    DWObject.OpenSource();
    DWObject.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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v1.0+ v10.0+ v11.0+ v11.0+ v12.1+

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v18.0+ v16.1+ v16.1+ v16.1+ v16.1+

DisableSource

Disable the data source (a TWAIN/ICA/SANE device which in most cases is a scanner) to stop the acquiring process. If the data source’s user interface is displayed, it will be closed.

Syntax

DisableSource(): boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v1.0+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

After DisableSource() is called, the Source is still open and you can continue to acquire images by calling AcquireImage() or EnableSource() .


EnableSource

Enable the data source to start the acquiring process.

Syntax

EnableSource(): boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v1.0+ v10.0+ v11.0+ v11.0+ v12.1+

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
): 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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
not supported v16.0+ v16.0+ v16.0+ v16.0+

Usage notes

This method enables the user to manipulate the settings for scanning but not start an actual scan. It only works if the source supports the capability CAP_ENABLEDSUIONLY . User can call GetCustomDSDataEx() to save the settings in the callback successCallBack and later call SetCustomDSDataEx() to apply the settings before starting a scan.


OpenSource

Load a data source to get it ready to acquire images.

Syntax

OpenSource(): boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v1.0+ v10.0+ v11.0+ v11.0+ v12.1+

OpenSourceAsync

Load a data source to get it ready to acquire images.

Syntax

OpenSourceAsync(): Promise<boolean>;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v18.0+ v16.1+ v16.1+ v16.1+ v16.1+

GetSourceNames

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

Syntax

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

interface SourceDetails {
    /**
     * The driver type which can be "TWAIN" | "ICA" | "SANE"
     */
    DriverType?: string;
    /**
     * Information about the driver if it's DriverType is "ICA"
     */
    DeviceInfo?: any;
    /**
     * The name of the data source. E.g. "TWAIN2 FreeImage Software Scanner".
     */
    ProductName?: string;
    /**
     * Whether it is the default source.
     */
    IsDefaultSource?: boolean;
    /**
     * Whether it is the current source.
     */
    IsCurrentSource?: boolean;
    /**
     * The family name of the data source. E.g. "Software Scan".
     */
    ProductFamily?: string;
    /**
     * The manufacturer of the data source. E.g. "TWAIN Working Group".
     */
    Manufacturer?: string;
    /**
     *
     */
    SupportedGroups?: 1073741827,
    /**
     * The version of the protocol based on which the data source is developed.
     */
    ProtocolMajor?: number;
    ProtocolMinor?: number;
    /**
     * Detailed version of the data source.
     */
    Version?: Version;
}
interface Version {
    MajorNum?: number;
    MinorNum?: number;
    Language?: number;
    Country?: number;
    Info?: string;
}

Parameters

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
not supported v15.3+ v15.3+ v15.3+ v15.3+

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v18.0+ v16.1+ v16.1+ v16.1+ v16.1+

SelectSource

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

Syntax

SelectSource(
    successCallBack?: () => void,
    failureCallBack?: (errorCode: number, errorString: string) => void
): boolean | 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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v1.0+ v10.0+ v11.0+ v11.0+ v14.0+

Usage notes

  • It’s recommended to use this API asynchronously by pass arguments to the parameters successCallback and failureCallback.
  • On Windows and Windows only, you can call this method with no arguments so that it runs synchronously and return a boolean value.

Example

DWObject.SelectSource(
  function () {
    DWObject.OpenSource();
    DWObject.AcquireImage();
  },
  function (errorCode, errorString) {
    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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v16.1+ v16.1+ v16.1+ v16.1+ v16.1+

Example

DWObject.SelectSourceAsync()
  .then(function (sourceIndex) {
    console.log(sourceIndex);
    return DWObject.AcquireImageAsync();
  })
  .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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v1.0+ v10.0+ v11.0+ v11.0+ v12.1+

Example

DWObject.SelectSourceByIndex(0);
DWObject.OpenSource();
DWObject.AcquireImage();

SelectSourceByIndexAsync

Select a data source by its index.

Syntax

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

Parameters

index: The index of the data source.

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v16.1+ v16.1+ v16.1+ v16.1+ v16.1+

Example

DWObject.SelectSourceByIndexAsync(0)
  .then(() => {
    return DWObject.OpenSourceAsync();
  })
  .then(() => {
    return DWObject.AcquireImageAsync();
  });

SetOpenSourceTimeout

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

Syntax

SetOpenSourceTimeout(duration: number): boolean;

Parameters

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v11.0+ v11.0+ v11.0+ v11.0+ not supported

Example

DWObject.SelectSource(function () {
  DWObject.SetOpenSourceTimeout(3000);
  DWObject.OpenSource();
  DWObject.AcquireImage();
});

startScan

Start the acquisition by passing all settings at once.

Syntax

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

interface ScanSetup {
  /**
   * An id that specifies this specific setup.
   */
  setupId?: string,
  /**
   * Whether to ignore or fail the acquistion when an exception is raised. Set "ignore" or "fail".
   */
  exception?: string,
  /**
   * The name of the data source (the scanner). If not set, the default data source is used.
   */
  scanner?: string,
  ui?: {
    /**
     * Whether to show the UI of the device.
     */
    bShowUI?: boolean,
    /**
     * Whether to show the indicator of the device.
     */
    bShowIndicator?: boolean,
  },
  /**
   * The TWAIN transfer mode.
   */
  transferMode?: Dynamsoft.DWT.EnumDWT_TransferMode | number,
  /**
   * Set how the transfer is done.
   */
  fileXfer?: {
    /**
     * Specify the file name (or pattern) for file transfer.
     * Example: "C:\\WebTWAIN<%06d>.bmp"
     */
    fileName?: string,
    /**
     * Specify the file format.
     */
    fileFormat?: Dynamsoft.DWT.EnumDWT_FileFormat | number,
    /**
     * Specify the quality of JPEG files.
     */
    jpegQuality?: number,
    /**
     * Specify the compression type of the file.
     */
    compressionType?: Dynamsoft.DWT.EnumDWT_CompressionType | number
  }
  /**
   * Set where the scanned images are inserted.
   */
  insertingIndex?: number,
  /**
   * The profile is a base64 string, if present, it overrides settings and more settings.
   */
  profile?: string,
  /**
   * Basic settings.
   */
  settings?: {
    /**
     * "ignore" (default) or "fail".
     */
    exception?: string,
    /**
     * Specify the pixel type.
     */
    pixelType?: Dynamsoft.DWT.EnumDWT_PixelType | number,
    /**
     * Specify the resolution.
     */
    resolution?: number,
    /**
     * Whether to enable document feader.
     */
    bFeeder?: boolean,
    /**
     * Whether to enable duplex scan.
     */
    bDuplex?: boolean
  },
  moreSettings?: {
    /**
     * "ignore" (default) or "fail".
     */
    exception?: string,
    /**
     * Specify the bit depth.
     */
    bitDepth?: number,
    /**
     * Specify the page size.
     */
    pageSize?: Dynamsoft.DWT.EnumDWT_CapSupportedSizes | number,
    /**
     * Specify the unit.
     */
    unit?: Dynamsoft.DWT.EnumDWT_UnitType | number,
    /**
     * Specify a layout to scan, if present, it'll override pageSize.
     */
    layout?: {
      left?: number,
      top?: number,
      right?: number,
      bottom?: number
    },
    /**
     * Specify the pixel flavor.
     */
    pixelFlavor?: Dynamsoft.DWT.EnumDWT_CapPixelFlavor | number,
    /**
     * Specify Brightness.
     */
    brightness?: number,
    /**
     * Specify contrast.
     */
    contrast?: number,
    /**
     * Specify how many images are transferred per session.
     */
    nXferCount?: number,
    /**
     * Whether to enable automatic blank image detection and removal.
     */
    autoDiscardBlankPages?: boolean,
    /**
     * Whether to enable automatic border detection.
     */
    autoBorderDetection?: boolean,
    /**
     * Whether to enable automatic skew correction.
     */
    autoDeskew?: boolean,
    /**
     * Whether to enable automatic brightness adjustment.
     */
    autoBright?: boolean
  },
  /**
   * A callback triggered before the scan, after the scan and after each page has been transferred.
   * Returned status
   * {event: 'beforeAcquire', result: {…}} //Equivalent to OnPreAllTransfers event
   * {event: 'postTransfer', bScanCompleted: false, result: {…}} //Equivalent to OnPostTransfer event
   * {event: 'postTransfer', bScanCompleted: true, result: {…}} //Equivalent to OnPostAllTransfers event
   */
  funcScanStatus?: (status: Status) => void,
  /**
   * Set up how the scanned images are outputted.
   */
  outputSetup?: {
    /**
     * Output type. "http" is the only supported type for now.
     */
    type?: string,
    /**
     * Set the output format.
     */
    format?: Dynamsoft.DWT.EnumDWT_ImageType | number,
    /**
     * Specify how many times the library will try the output.
     */
    reTries?: 3,
    /**
     * Whether to use the FileUploader.
     */
    useUploader?: false,
    /**
     * Whether to upload all images in one HTTP post.
     */
    singlePost?: boolean,
    /**
     * Whether to show a progress bar when outputting.
     */
    showProgressBar?: boolean,
    /**
     * Whether to remove the images after outputting.
     */
    removeAfterOutput?: boolean,
    /**
     * A callback triggered during the outputting.
     * @argument fileInfo A JSON object that contains the fileName, percentage, statusCode, responseString, etc.
     */
    funcHttpUploadStatus?: (fileInfo: any) => void,
    /**
     * Setup for PDF output.
     */
    pdfSetup?: {
      author?: string,
      compression?: Dynamsoft.DWT.EnumDWT_PDFCompressionType | number,
      creator?: string,
      /**
       * Example: 'D:20181231'
       */
      creationDate?: string,
      keyWords?: string,
      /**
       * Example: 'D:20181231'
       */
      modifiedDate?: string,
      producer?: string,
      subject?: string,
      title?: string,
      version?: number,
      quality?: number
    },
    /**
     * Setup for TIFF output.
     */
    tiffSetup?: {
      quality?: number,
      compression?: Dynamsoft.DWT.EnumDWT_TIFFCompressionType | number,
      /**
       * Specify Tiff custom tags.
       */
      tiffTags?: TiffTag[]
    },
    /**
     * Setup for HTTP upload via Post.
     */
    httpParams?: {
      /**
       * Target of the request.
       * Example: "http://dynamsoft.com/receivepost.aspx"
       */
      url?: string,
      /**
       * Custom headers in the form.
       * Example: {md5: ""}
       */
      headers?: any,
      /**
       * Custom form fields.
       * Example: {"UploadedBy": "Dynamsoft"}
       */
      formFields?: any,
      /**
       * The maximum size of a file to be uploaded (in bytes).
       */
      maxSizeLimit?: number,
      /**
       * Specify how many threads (<=4) are to be used. Only valid when {useUploader} is true.
       */
      threads?: number,
      /**
       * Specify the names for the files in the form.
       * Example: "RemoteName<%06d>"
       */
      remoteName?: string,
      /**
       * Specify the name(s) (pattern) of the uploaded files.
       * Example: "uploadedFile<%06d>.jpg"
       */
      fileName?: string
    }
  }
}

Parameters

scanSetup: Configuration for the acquisition.

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
not supported v15.0+ v15.1+ v15.1+ v15.1+

Sample

Make use of the API startScan


CancelAllPendingTransfers

Cancels all pending transfers.

Syntax

CancelAllPendingTransfers(): boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

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


CloseSourceManager

Closes and unloads Data Source Manager.

Syntax

CloseSourceManager(): boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ v11.0+ v12.1+

CloseSourceManagerAsync

Closes and unloads Data Source Manager.

Syntax

CloseSourceManagerAsync(): Promise<boolean>;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v18.0+ v16.1+ v16.1+ v16.1+ v16.1+

CloseWorkingProcess

Closes the scanning process to release resources on the machine.

Syntax

CloseWorkingProcess(): boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v11.2+ v11.2+ v11.2+ v11.2+ v12.1+

Usage notes

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


FeedPage

Ejects the current page and begins scanning the next page in the document feeder.

Syntax

FeedPage(): boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Usage notes

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


GetCustomDSData

Get the custom data source data and saves the data in a specified file.

Syntax

GetCustomDSData(fileName: string): boolean;

Parameters

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.0+ v10.0+ v11.0+ not supported not supported

Example

DWObject.GetCustomDSData("C:\\customDSData");

GetCustomDSDataEx

Gets custom DS data and returns it in a base64 string.

Syntax

GetCustomDSDataEx(): string;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.0+ v10.0+ v11.0+ not supported not supported

GetSourceNameItems

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

Syntax

GetSourceNameItems(index: number): string;

Parameters

index: The index of the data source.

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v7.0+ v10.0+ v11.0+ v11.0+ v12.1+

OpenSourceManager

Load and open data source manager.

Syntax

OpenSourceManager(): boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

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


OpenSourceManagerAsync

Load and open data source manager.

Syntax

OpenSourceManagerAsync(): Promise<boolean>;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v18.0+ v16.1+ v16.1+ v16.1+ v16.1+

Usage notes

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


ResetImageLayout

Reset the image layout in the data source.

Syntax

ResetImageLayout(): boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Usage notes

To set the image layout manually, you can use SetImageLayout()


RewindPage

If called while {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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Usage notes

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


SetCustomDSData

Sets custom data source data to be used for scanning, the data is stored in a file which can be regarded as a scanning profile.

Syntax

SetCustomDSData(fileName: string): boolean;

Parameters

fileName: The path of the file.

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.0+ v10.0+ v11.0+ not supported not supported

Usage notes

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


SetCustomDSDataEx

Set custom data source data to be used for scanning, the input is a base64 string.

Syntax

SetCustomDSDataEx(dsDataString: string): boolean;

Parameters

dsDataString: The string that contains custom data source data.

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.0+ v10.0+ v11.0+ not supported not supported

Usage notes

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


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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ v17.0+ not supported

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.

Check out the available formats Dynamsoft.DWT.EnumDWT_FileFormat.

Example

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

SetImageLayout

Set the left, top, right, and bottom sides of the image layout rectangle for the current data source. 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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Usage notes

The arguments set to the parameters left , top , right , bottom are based on the value of the Unit property which is inches by default.

This API is device-dependent. If a data source doesn’t support the customization of 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

Example

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

BitDepth

Return or set the pixel bit depth for the current value of PixelType .

Syntax

BitDepth: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v3.0+ v10.0+ v11.0+ not supported not supported

Usage notes

Set this property after OpenSource() and before AcquireImage() .

By default, the 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.

Syntax

IfAppendImage: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.1+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

The value of this property defaults to true , which means 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. The important thing to note is that, by design, the current image is always the last acquired one which means that the images acquired after setting IfAppendImage to false will be displayed / retained in the reverse order.


IfDisableSourceAfterAcquire

Return or set whether to close the built-in User Interface after all images have been acquired.

Syntax

IfDisableSourceAfterAcquire: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v3.0+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

This property only makes sense when IfShowUI is set to true .


IfDuplexEnabled

Return or set whether to enable duplex scanning (in other words, whether to scan both sides of the paper).

Syntax

IfDuplexEnabled: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v3.0+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

Set this property after OpenSource() and before AcquireImage() .

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


IfFeederEnabled

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

Syntax

IfFeederEnabled: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v3.0+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

Set this property after OpenSource() and before AcquireImage() .

If the property is set to true , the data source will try acquiring images from the document feeder first. If the data source doesn’t have a document feeder, the flatbed will be used.


IfShowUI

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

Syntax

IfShowUI: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v3.0+ v10.0+ v11.0+ not supported not supported

Usage notes

If the property is set to true , the data source will display its user interface when AcquireImage() is called. Otherwise, the UI will not be displayed and the scan will start immediately.

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


ImageCaptureDriverType

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

Syntax

ImageCaptureDriverType: Dynamsoft.DWT.EnumDWT_Driver | number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
not supported not supported v11.0+ v11.0+ not supported

Usage notes

Set this property right after the SDK is initialized or after calling CloseSourceManager() and OpenSourceManager() .

The allowed values for EnumDWT_Driver are

Label Value Description
TWAIN 0 Use data sources that conforms to the TWAIN protocol (Default value on Windows)
ICA 3 Use data sources that conforms to the Image Capture Architecture
SANE 3 Use data sources that conforms to the SANE API (Default value on Linux)
TWAIN_AND_ICA 4 Use both TWAIN and ICA data sources (Default value on MacOS)
TWAIN_AND_TWAIN64 4 Use both 32bit and 64bit TWAIN drivers
TWAIN64 5 Use 64bit TWAIN sources

PageSize

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

Syntax

PageSize: Dynamsoft.DWT.EnumDWT_CapSupportedSizes | number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v3.0+ v10.0+ v11.0+ v11.0+ not supported

Usage notes

Set this property after OpenSource() and before AcquireImage().


PixelType

Return or set the pixel type used when acquiring images.

Syntax

PixelType: Dynamsoft.DWT.EnumDWT_PixelType | number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v3.0+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

Set this property after OpenSource() and before AcquireImage().


Resolution

Return or set the resolution used when acquiring images.

Syntax

Resolution: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v3.0+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

Set this property after OpenSource() and before AcquireImage().


SourceCount

Returns how many data sources are available on the local system.

Syntax

readonly SourceCount: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v1.0+ v10.0+ v11.0+ v11.0+ v12.1+

BlankImageThreshold

Retrun or set the dividing line between black and white.

Syntax

BlankImageThreshold: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v5.2+ v5.2+ v5.2+ v5.2+

Usage notes

BlankImageThreshold ranges from 0 to 255 and is 128 by default, it’s only effective when [ PixelType ] is set to TWPT_BW . The bigger the value is, the more likely an image may be regarded as blank.


Brightness

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

Syntax

Brightness: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported v12.1+

Usage notes

Set this property after OpenSource() and before AcquireImage() .

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


Contrast

Return or set Contrast to be used for scanning by the data source.

Syntax

Contrast: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported v12.1+

Usage notes

Set this property after OpenSource() and before AcquireImage() .

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


CurrentSourceName

Return the device name of current source.

Syntax

readonly CurrentSourceName: string;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

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


DataSourceStatus

Return a value that indicates the data source status.

Syntax

DataSourceStatus: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

Value Description
0 The data source is closed.
1 The data source is opened.
2 The data source is enabled.
3 The data source is acquiring images.

DefaultSourceName

Return the name of the last used source.

Syntax

DefaultSourceName: string;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Duplex

Return whether the source supports duplex. If yes, it further returns the level of duplex the data source supports.

Syntax

readonly Duplex: Dynamsoft.DWT.EnumDWT_DUPLEX | number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Usage notes

Label Value Description
TWDX_NONE 0 duplex is not supported
TWDX_1PASSDUPLEX 1 1-pass duplex
TWDX_2PASSDUPLEX 2 2-pass duplex

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 does not support Linux.


IfAutoBright

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

Syntax

IfAutoBright: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

IfAutoDiscardBlankpages

Return or set whether the data source (the scanner) discards blank images during scanning automatically.

Syntax

IfAutoDiscardBlankpages: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v7.0+ v10.0+ v11.0+ not supported not supported

Usage notes

The property works only if the device and its driver supports discarding blank pages. You can find whether your device supports this capbility from its user manual.

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


IfAutoFeed

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

Syntax

IfAutoFeed: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v7.0+ v10.0+ v11.0+ not supported not supported

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 to enable the data source’s automatic border detection feature.

Syntax

IfAutomaticBorderDetection: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v7.0+ v10.0+ v11.0+ not supported not supported

Usage notes

The property works only if the device and its driver support detecting the border automatically. You can find whether your device supports this capbility from its user manual.

Once enabled, the data source (scanner) will automatically detect the borders of the document so that no extra margins are scanned.


IfAutomaticDeskew

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

Syntax

IfAutomaticDeskew: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v7.0+ v10.0+ v11.0+ not supported not supported

Usage notes

The property works only if the device and its driver supports automatical deskewing. You can find whether your device supports this capbility from its user manual.


IfAutoScan

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

Syntax

IfAutoScan: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Usage notes

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

The fundamental assumption behind this property is that the device may be able to 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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Usage notes

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


IfPaperDetectable

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

Syntax

readonly IfPaperDetectable: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Usage notes

Check this property after OpenSource() is called.


IfShowIndicator

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

Syntax

IfShowIndicator: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Usage notes

This property works only when IfShowUI is set to false .

The indicator will only be hidden if you set both IfShowUI and IfShowIndicator to false .


IfUIControllable

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

Syntax

readonly IfUIControllable: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Usage notes

Check this property after OpenSource() is called.


IfUseTwainDSM

Return or set whether the new TWAIN DSM (data source Manager) is used 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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v6.2+ v10.0+ v11.0+ not supported not supported

Usage notes

This property should be set before any TWAIN related methods or properties are called or set.


ImageLayoutFrameBottom

Return the value of the bottom edge of the current image frame (in Unit).

Syntax

readonly ImageLayoutFrameBottom: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

ImageLayoutFrameLeft

Return the value of the left edge of the current image frame (in Unit).

Syntax

readonly ImageLayoutFrameLeft: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

ImageLayoutFrameRight

Return the value of the right edge of the current image frame (in Unit).

Syntax

readonly ImageLayoutFrameRight: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

ImageLayoutFrameTop

Return the value of the top edge of the current image frame (in Unit).

Syntax

readonly ImageLayoutFrameTop: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

ImageLayoutDocumentNumber

Return the document number of the current image.

Syntax

readonly ImageLayoutDocumentNumber: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

ImageLayoutPageNumber

Return the page number of the current image.

Syntax

readonly ImageLayoutPageNumber: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

ImageBitsPerPixel

Return the bit depth of the current image.

Syntax

readonly ImageBitsPerPixel: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

ImageLength

Return the length of the current image.

Syntax

readonly ImageLength: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

ImageWidth

Return the width of the current image.

Syntax

readonly ImageWidth: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

ImageXResolution

Return the horizontal resolution of the current image.

Syntax

readonly ImageXResolution: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

ImageYResolution

Return the vertical resolution of the current image.

Syntax

readonly ImageYResolution: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

ImagePixelType

Return the pixel type of the current image.

Syntax

readonly ImagePixelType: Dynamsoft.DWT.EnumDWT_PixelType | number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
all versions all versions all versions all versions all versions

MagData

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

Syntax

readonly MagData: string;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v8.0+ v8.0+ v8.0+ v8.0+ v8.0+

MagType

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

Syntax

readonly MagType: Dynamsoft.DWT.EnumDWT_MagType | number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v8.0+ v8.0+ v8.0+ v8.0+ v8.0+

Usage notes

The numbers returned by these APIs are based on the value of the Unit property which by default means “inches”.

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

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 which normally occurs when the ADF (Automatic Document Feeder) is used.


PixelFlavor

Return or set the pixel flavor to be used for acquiring images.

Syntax

PixelFlavor: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

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;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported not supported

Usage notes

Allowed values are

  • TWSX_NATIVE 0: The default mode. In this mode, the whole image is transfered in a single memory block.
  • TWSX_FILE 1: In this mode, the image is transfered to a specified file on the disk directly. This mode is ideal when transferring large images that might encounter memory limitations with Native mode. Check out SetFileXferInfo for more information.
  • TWSX_MEMORY 2: In this mode, the image is transferred in multiple memory blocks. It’s ideal for transferring very large images or a large number of images in a short time.

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 measure for all quantities. Note that this setting is only effective for TWAIN (hardware) related operations.

Syntax

Unit: Dynamsoft.DWT.EnumDWT_UnitType | number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ v11.0+ not supported

Usage notes

Allowed values are

Label Value Description
TWUN_INCHES 0 inches(Default)
TWUN_CENTIMETERS 1 centimeters
TWUN_PICAS 2 picas
TWUN_POINTS 3 points
TWUN_TWIPS 4 twips
TWUN_PIXELS 5 pixels
TWUN_MILLIMETERS 6 millimeters

XferCount

Return and set the number of images your application is willing to accept for each scan job.

Syntax

XferCount: number;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ not supported v12.1+

Usage notes

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


OnPostAllTransfers

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

Syntax

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

This event fires after all pages in the document feeder have been scanned and transferred. This is a good place to upload the images, detect barcodes, discard blank pages, etc.

Example

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

OnPostTransfer

This event is triggered after each page has been scanned and transferred.

Syntax

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v1.0+ v10.0+ v11.0+ v11.0+ v12.1+

Example

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

OnPostTransferAsync

This event is triggered 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.

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
not supported v15.0+ v15.1+ v15.1+ v15.1+

Usage notes

interface outputInfo {
  /**
   * Id of the image if it's transferred to the buffer.
   */
  imageId?: number;
  /**
   * Path of the image if it's transferred to the disk.
   */
  Path?: string;
  /**
   * Information about the image.
   */
  imageInfo?: object;
  /**
   * Extended information about the image.
   */
  extendedImageInfo?: object;
}

Example

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

OnPreAllTransfers

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

Syntax

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ v11.0+ v12.1+

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

In such cases, the event OnPreTransfer is triggered multiple times but OnPreAllTransfers is triggerred only once.

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


OnPreTransfer

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

Syntax

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v5.2+ v10.0+ v11.0+ v11.0+ v12.1+

Usage notes

In the callback function of this event, you can

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

OnSourceUIClose

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

Syntax

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v8.0.1+ v10.0+ v11.0+ not supported not supported

getCapabilities

Gets detailed information about all capabilities of the current data source.

Syntax

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

/**
 * Detailed information about a specific capability
 */
interface CapabilityDetails {
    /**
     * The Capability.
     */
    capability: ValueAndLabel;
    /**
     * The container type of the Capability
     */
    conType?: ValueAndLabel;
    /**
     * The index for the current value of the Capability
     */
    curIndex?: number;
    /**
     * The current value of the Capability
     */
    curValue?: ValueAndLabel;
    /**
     * The index for the default value of the Capability
     */
    defIndex?: number;
    /**
     * The operation types that are supported by the Capability. Types include {"get", "set", "reset" "getdefault", "getcurrent"}
     */
    query?: string[];
    /**
     * The value type of the Capability. Value types include
        TWTY_BOOL: 6
        TWTY_FIX32: 7
        TWTY_FRAME: 8
        TWTY_INT8: 0
        TWTY_INT16: 1
        TWTY_INT32: 2
        TWTY_STR32: 9
        TWTY_STR64: 10
        TWTY_STR128: 11
        TWTY_STR255: 12
        TWTY_UINT8: 3
        TWTY_UINT16: 4
        TWTY_int: 5
     */
    valueType?: ValueAndLabel;
    /**
     * The available values of the Capability
     */
    values?: ValueAndLabel[];
}

interface ValueAndLabel {
    /**
     * Numeric representation of the item
     */
    value?: Dynamsoft.DWT.EnumDWT_Cap | Dynamsoft.DWT.EnumDWT_CapType | Dynamsoft.DWT.EnumDWT_CapValueType | number;
    /**
     * Label or name of the item
     */
    label?: string;
}

Parameters

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

  • capabilityDetails: Detailed information about the specified capabilities.

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

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v16.0+ v16.0+ v16.0+ v16.0+ v16.0+

Usage notes

Check out the Enumerations


setCapabilities

Sets up one or multiple capabilities in one call.

Syntax

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

interface Capabilities {
    /**
     * Whether to "ignore" or "fail" the request if an exception occurs. This is an overall setting that is inherited by all capabilities.
     */
    exception: string;
    /**
     * Specifies how to set capabilities
     */
    capabilities: CapabilitySetup[]
}

interface CapabilitySetup {
    /**
     * Specify a capability
     */
    capability: Dynamsoft.DWT.EnumDWT_Cap | number;
    /**
     * The value to set to the capability or the value of the capability after setting.
     */
    curValue: number | string; //array is not supported
    errorCode?: number;
    errorString?: string;
    /**
     * Whether to "ignore" or "fail" the request if an exception occurs when setting this specific capability.
     */
    exception? : string;
}

Parameters

capabilities: A object that describes how to set capabilities.

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

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

  • capabilities: The capabilities to set.

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v16.0+ v16.0+ v16.0+ v16.0+ v16.0+

Usage notes

To make things easier, Dynamsoft designed the API with a simplified parameter Capabilities which only requires the minimum information for setting a capability: a number to specify the capability and the value to set to it. Underneath, Dynamsoft takes care of container type setting, value type setting as well as data validation.

Pay attention to the argument you set to the overall parameter exception and the individual parameter exception for each capability. If the overall parameter is set to fail , the setting will abort as soon as an exception is raised while setting any of the capabilities. Otherwise, ignore means to carry on setting the next capability even when the previous one failed. Aside from the overall parameter, the individual exception 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 the capabilities which you think are important. This way, you get notified if these important capabilities failed to be set while other less-important ones are ignored when setting them failed.

Example

DWObject.SelectSourceByIndex(0);
DWObject.IfShowUI = false;
DWObject.OpenSource();
DWObject.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) {
    DWObject.AcquireImage(
      function () {},
      function () {
        console.log(DWObject.ErrorString);
      }
    );
  },
  function (errorData) {
    console.error(errorData);
    DWObject.AcquireImage(
      function () {},
      function () {
        console.log(DWObject.ErrorString);
      }
    );
  }
);

GetDevicesAsync

Return all available devices (scanners, eSCL scanners, etc.) for the device type (if specified)

Syntax

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

Parameters

deviceType: The device type

refresh: Default value is false

Example

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v18.0+ v18.0+ v18.0+ v18.0+ v18.0+

Remark

Device APIs


SelectDeviceAsync

Select the device to use for scanning

Syntax

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

Example

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

Parameters

device: the device

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v18.0+ v18.0+ v18.0+ v18.0+ v18.0+

AcquireImageAsync

Scan documents into another DWObject control. eSCL is not supported.

Syntax

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

Parameters

deviceConfiguration: The device configuration

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v18.0+ v18.0+ v18.0+ v18.0+ v18.0+

Example

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

Is this page helpful?

YesYes NoNo

In this article:

latest version

    • Latest Version (18.1)
    • Version 18.0
    • Version 17.3
    • Version 17.2.1
    • Version 17.1.1
    • Version 17.0
    • Version 16.2
    • Version 16.1.1
    Change +