Basic Scan

Methods
AcquireImage() CloseSource() DisableSource()
EnableSource() OpenSource() SelectSource()
SelectSourceByIndex() SetOpenSourceTimeout() startScan()
Properties
BitDepth IfAppendImage IfDisableSourceAfterAcquire
IfDuplexEnabled IfFeederEnabled IfShowUI
ImageCaptureDriverType PageSize PixelType
Resolution SourceCount
Events
OnPostAllTransfers OnPostTransfer OnPostTransferAsync

Code example

The following code example demonstrates how to use the APIs above to perform basic scanning.

function BasicScan() {
    if (DWObject) {
        if (Dynamsoft.Lib.env.bMac) {
            DWObject.ImageCaptureDriverType = EnumDWT_Driver.TWAIN_AND_ICA;
        }
        DWObject.RegisterEvent('OnPostTransfer', function () {
            console.log('One page scanned!');
        });
        DWObject.RegisterEvent('OnPostAllTransfers', function () {
            DWObject.CloseSource();
        });
        DWObject.SelectSource(function () {
            DWObject.SetOpenSourceTimeout(3000);
            DWObject.OpenSource();
            DWObject.IfShowUI = false;
            DWObject.IfDisableSourceAfterAcquire = true;
            DWObject.PixelType = EnumDWT_PixelType.TWPT_RGB;
            DWObject.BitDepth = 24;
            DWObject.PageSize = EnumDWT_CapSupportedSizes.TWSS_A4;
            DWObject.Resolution = 300;
            DWObject.IfFeederEnabled = true;
            DWObject.IfDuplexEnabled = true;
            DWObject.IfAppendImage = false;
            DWObject.AcquireImage(function () {
                    /**
                    * Actually not necessary when you have 
                    * IfDisableSourceAfterAcquire set to true.
                    */
                    DWObject.DisableSource();
                },
                function () {
                        DWObject.DisableSource();
                }
            );
        }, function () {
            console.log('Failed to select a source, there are ' +
                DWObject.SourceCount + ' sources in total.');
        });
    }
}

Methods

AcquireImage()
Starts image acquisition.
Syntax .AcquireImage([optionalDeviceConfig], [optionalAsyncSuccessFunc, optionalAsyncFailureFunc]);
Parameters optional optionalDeviceConfig: A JS object used to set up the device for image acquisition.
<OnSuccess function> optional optionalAsyncSuccessFunc: callback function triggered when acquiring succeeds.
<OnFailure function> optional optionalAsyncFailureFunc: callback function triggered when acquiring fails.
Return value boolean
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v1.0 ✓ | v10.0 ✓ | v11.0 ✓ | v11.0 ✓ | v12.1
Usage notes The parameters are only available in the HTML5 Edition. As the parameters are all optional, there are 4 ways to use this method as demonstrated below.
IfGetImageInfo and IfGetExtImageInfo are added in version 15.0 which when set to false may speed up the scanning process a bit.
Example
var DeviceConfig = {
    IfShowUI: false,
    PixelType: EnumDWT_PixelType.TWPT_RGB,
    Resolution: 300,
    IfFeederEnabled: true,
    IfDuplexEnabled: false,
    IfDisableSourceAfterAcquire: true,
    IfGetImageInfo: true,
    IfGetExtImageInfo: true
};
function AsyncSuccessFunc() {
    console.log('successful');
}
function AsyncFailureFunc(errorCode, errorString) {
    alert(errorString);
}
function AcquireImage1() {
    DWObject.SelectSource();
    DWObject.OpenSource();
    DWObject.IfShowUI = false;
    DWObject.PixelType = EnumDWT_PixelType.TWPT_RGB;
    DWObject.Resolution = 300;
    DWObject.IfFeederEnabled = true;
    DWObject.IfDuplexEnabled = false;
    DWObject.IfDisableSourceAfterAcquire = true;
    DWObject.AcquireImage();
}
function AcquireImage2() {
    DWObject.SelectSource();
    DWObject.OpenSource();
    DWObject.AcquireImage(DeviceConfig);
}
function AcquireImage3() {
    DWObject.SelectSource();
    DWObject.OpenSource();
    DWObject.IfShowUI = false;
    DWObject.PixelType = EnumDWT_PixelType.TWPT_RGB;
    DWObject.Resolution = 300;
    DWObject.IfFeederEnabled = true;
    DWObject.IfDuplexEnabled = false;
    DWObject.IfDisableSourceAfterAcquire = true;
    DWObject.AcquireImage(AsyncSuccessFunc, AsyncFailureFunc);
}
function AcquireImage4() {
    DWObject.SelectSource();
    DWObject.OpenSource();
    DWObject.AcquireImage(DeviceConfig, AsyncSuccessFunc, AsyncFailureFunc);
}
CloseSource()
Closes 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();
Parameters None
Return value boolean
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v1.0 ✓ | v10.0 ✓ | v11.0 ✓ | v11.0 ✓ | v12.1
Usage notes In version 10.0 ~ 11.2, CloseSource() is called automatically after all pages have been scanned. This method can be called after SelectSource() and before OpenSource() in order to close any existing connections.
Example
DWObject.RegisterEvent('OnPostAllTransfers', function () {
    DWObject.CloseSource();
});
DisableSource()
Disables the Data Source (a TWAIN/ICA/SANE device which in most cases is a scanner) to stop the acquiring process. If the source's user interface is displayed, it will be closed.
Syntax .DisableSource();
Parameters None
Return value boolean
Availability
ActiveXH5(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().
Example
DWObject.RegisterEvent('OnPostAllTransfers', function () {
    DWObject.DisableSource();
});
EnableSource()
Enables the source to start the acquiring process.
Syntax .EnableSource();
Parameters None
Return value boolean
Availability
ActiveXH5(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.
Example
function AcquireImage4() {
    DWObject.SelectSource();
    DWObject.OpenSource();
    DWObject.EnableSource();
}
OpenSource()
Loads the currently selected Data Source into memory and initializes it for image acquisition. If no source is specified (neither SelectSource() nor SelectSourceByIndex() has been called), the default source will be loaded.
Syntax .OpenSource();
Parameters None
Return value boolean
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v1.0 ✓ | v10.0 ✓ | v11.0 ✓ | v11.0 ✓ | v12.1
Usage notes Call OpenSource() before you negotiate any capabilities.
Example
DWObject.SelectSource();
DWObject.OpenSource();
DWObject.IfShowUI = false;
DWObject.Resolution = 300;
DWObject.AcquireImage();
SelectSource()
Brings up the Source Selection User Interface (UI) for the user to choose a Data Source.
Syntax .SelectSource([optionalAsyncSuccessFunc, optionalAsyncFailureFunc]);
Parameters <OnSuccess function> optional optionalAsyncSuccessFunc: callback function triggered when selecting succeeds.
<OnFailure function> optional optionalAsyncFailureFunc: callback function triggered when selecting fails.
Return value boolean, only when used synchronously (without parameters).
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v1.0 ✓ | v10.0 ✓ | v11.0 ✓ | v11.0 ✓ | v14.0
Usage notes The optional parameters which make the method asynchronous were added in v14.0 of the HTML5 edition and in v14.1 of the ActiveX edition.
Example
DWObject.SelectSource();
DWObject.OpenSource();
DWObject.IfShowUI = false;
DWObject.Resolution = 300;
DWObject.AcquireImage();
DWObject.SelectSource(function () {
    DWObject.OpenSource();
    DWObject.IfShowUI = false;
    DWObject.Resolution = 300;
    DWObject.AcquireImage();
}, function () {
    console.log('Failed to select a source, there are ' +
        DWObject.SourceCount + ' sources in total.');
});
SelectSourceByIndex()
Selects a Data Source by its index in the Data Source Manager.
Syntax .SelectSourceByIndex(Number index);
Parameters number index: The index of the targeted Data Source in the Data Source Manager.
Return value boolean
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v1.0 ✓ | v10.0 ✓ | v11.0 ✓ | v11.0 ✓ | v12.1
Usage notes Use this method when you don't want to show the Data Source Selecting UI.
Example
DWObject.SelectSourceByIndex(0);
DWObject.IfShowUI = false;
DWObject.Resolution = 300;
DWObject.AcquireImage();
SetOpenSourceTimeout()
Sets a timer which stops the source opening process once it expires.
Syntax .SetOpenSourceTimeout(nMilliseconds);
Parameters number nMilliseconds: The time, in milliseconds (thousandths of a second).
Return value boolean
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v11.0 ✓ | v11.0 ✓ | v11.0 ✓ | v11.0
Usage notes SetOpenSourceTimeout() should be called before OpenSource().
Example
DWObject.SelectSource();
DWObject.SetOpenSourceTimeout(3000);
DWObject.OpenSource();
DWObject.AcquireImage();
startScan()
Initiate a scan job by pass in all the settings in a JSON object called scanSetup.
Syntax .startScan(scanSetup);
Parameters scanSetup scanSetup: The settings for the scan job. Check out the example below for more information.
Return value boolean
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v15.0
Usage notes none
Example
DWObject.startScan(scanSetup: scanSetup): Promise
    .then(function (scanSetup: scanSetup) {}) /** */
    .catch(function (errorString: string, errorCode: int) {
        /** Do some damage control */
    })
scanSetup = {
    setupId: "", // An id that specifies this specific setup.
    exception: "fail", // "ignore" or “fail”
    scanner: "name of the scanner", //Optional. Use the default source if vacant
    ui: {
        bShowUI: true,
        bShowIndicator: true, // Whether to show the indicator of the device
    },
    transferMode: EnumDWT_TransferMode.TWSX_NATIVE, //file, memory, native
    fileXfer: { //Optional, for file transfer mode only
        fileName: "C:\\WebTWAIN<%06d>.bmp", //file path
        fileFormat: EnumDWT_FileFormat.TWFF_BMP,
        jpegQuality: 80,
        compressionType: EnumDWT_CompressionType.TWCP_NONE 
        //if applicable  
        /*EnumDWT_CompressionType:{
            TWCP_NONE =0, 
            TWCP_PACKBITS=1,  
            TWCP_GROUP31D=2, 
            TWCP_GROUP31DEOL=3, 
            TWCP_GROUP32D=4,
            TWCP_GROUP4=5, 
            TWCP_JPEG=6,
            TWCP_LZW=7, 
            TWCP_JBIG=8, 
            TWCP_PNG=9,
            TWCP_RLE4=10, 
            TWCP_RLE8=11, 
            TWCP_BITFIELDS=12, 
            TWCP_ZIP=13, 
            TWCP_JPEG2000=14
            }*/
    }
    insertingIndex: 3,
    profile: "", 
    //base64String, if not empty, it overrides settings and more settings.
    settings: {
        exception: "fail", // "ignore" (default) or "fail",  
        pixelType: EnumDWT_PixelType.TWPT_RGB, //rgb, bw, gray, etc
        resolution: 200, // 300
        bFeeder: true, //whether to enable feeder
        bDuplex: true, //whether to enable duplex
    },
    moreSettings: {
        exception: "fail", // "ignore" or “fail”
        bitDepth: 24, //1,8,24,etc 
        pageSize: EnumDWT_CapSupportedSizes.TWSS_A4, //A4, etc.
        unit: EnumDWT_UnitType.TWUN_INCHES, //
        layout: {
            left: float,
            top: float,
            right: float,
            bottom: float
        }, //Optional. If specified, it'll override pageSize
        pixelFlavor: EnumDWT_CapPixelFlavor.TWPF_CHOCOLATE,
        //TWPF_CHOCOLATE (0) or TWPF_VANILLA (1)
        brightness: 0,
        contrast: 0,
        nXferCount: -1, 
        //Number of pages to transfer per scan
        autoDiscardBlankPages: true,//Device dependent
        autoBorderDetection: true,//Device dependent
        autoDeskew: true,//Device dependent
        autoBright: true //Device dependent
    },
    funcScanStatus:funcScanStatus(status),  
    //status is a JSON object that contains info like currentPage, totalPage, etc.
    outputSetup : {
        type: "http", 
        // http is the only supported type in v15.0
        format: EnumDWT_ImageType.IT_PDF, 
        // Specify the output file type
        reTries: 3,
        // Specify the number of times to try the upload before it succeeds
        useUploader: false,
        //Whether to use the File Uploader module
        singlePost: true,
        //Whether to upload all data in one or multiple posts
        showProgressBar: true,
        //Whether to show the progress bar when uploading
        removeAfterOutput: true,
        //Whether to remove the images after the upload is done
        funcHttpUploadStatus:funcHttpUploadStatus(fileInfo),  
        //fileInfo is a JSON object that has info like 
        //fileName, percentage, statusCode, responseString.
        pdfSetup: {// Specify how the PDF file is created.  
            author: 'tom',
            compression: EnumDWT_PDFCompressionType,
            creator: 'dwt',
            creationDate: 'D:20181231',
            keyWords: 'dwt',
            modifiedDate: 'D:20181231',
            producer: 'dynamsoft',
            subject: 'blah',
            title: 'dwt',
            version: 1.4,
            quality: 80 //only for JPEG compression
        },
        tiffSetup: {// Specify how the TIFF file is created.  
            quality: 80, //only for JPEG compression
            compression: EnumDWT_TIFFCompressionType,
            // Specify the compression type
            tiffTags: [{ // Specify the tags to be added to the TIFF
                tagIdentifier: 700,
                content: "Custom Tiff Tag Value",
                useBase64Encoding: true
            }]
        },
        httpParams: {
            url: "http://dynamsoft.com/receivepost.aspx", 
            // Specify the URL to post to
            headers: {}, 
            // Headers to be added in the post request
            formFields: {}, 
            // Extra form fileds to be added in the post
            maxSizeLimit: 100000, 
            // Set a limit on how big a file is allowed to be uploaded (bytes)
            threads: 4, 
            // Specifies how many threads are to be used for the upload
            remoteName:"RemoteName<%06d>", 
            // Specifies the names for the files (streams) in the form
            fileName: "uploadedFile<%06d>.jpg" 
            // Specifies the names for the uploaded files
        }
    }
}

Properties

BitDepth
Returns or sets the pixel bit depth for the current value of PixelType.
Type number
Accessors Get Set
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v3.0 ✓ | v10.0 ✓ | v11.0
Usage notes Set this property after OpenSource() and before AcquireImage().
Set BitDepth based on the current value of PixelType. By default, the bit depth is 1 for 'TWPT_BW'(0), 8 for 'TWPT_GRAY'(1) and 24 for 'TWPT_RGB'(2).
IfAppendImage
Returns or sets whether newly acquired images are inserted or appended.
Type boolean
Accessors Get Set
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v5.1 ✓ | v10.0 ✓ | v11.0 ✓ | v11.0 ✓ | v12.1
Usage notes The value of the property defaults to true which means the newly acquired images will be appended after the last image in buffer. If it's set to false, the images will be inserted before the current image. An important thing to note here is that, by design, the current image is always the last acquired one which means the images acquired after IfAppendImage is set to false will be displayed/kept in reverse order. To make sure the order is as the pages are scanned while IfAppendImage is false, the easiest way is to increase CurrentImageIndexInBuffer by 1 in the event OnPostTransfer.
IfDisableSourceAfterAcquire
Returns or sets whether to close the user interface after all images have been acquired.
Type boolean
Accessors Get Set
Availability
ActiveXH5(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(). This property only makes sense when IfShowUI is set to true.
IfDuplexEnabled
Returns or sets whether to enable duplex scanning (in other words, whether to scan both sides of the paper).
Type boolean
Accessors Get Set
Availability
ActiveXH5(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
Returns or sets whether a Data Source's Automatic Document Feeder (ADF) is enabled for scanning.
Type boolean
Accessors Get Set
Availability
ActiveXH5(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
Returns or sets whether the source displays the user interface when scanning.
Type boolean
Accessors Get Set
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v3.0 ✓ | v10.0 ✓ | v11.0 ✓ | v11.0
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 scanning will begin immediately.
ImageCaptureDriverType
Returns or sets whether to use TWAIN or ICA protocol on macOS.
Type number
Accessors Get Set
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v11.0 ✓ | v11.0
Usage notes Set this property right after the SDK is initialized or after calling CloseSourceManager() and OpenSourceManager().

This property only works on macOS. Allowed values are

EnumDWT_Driver.TWAIN: 0
EnumDWT_Driver.ICA: 3
EnumDWT_Driver.TWAIN_AND_ICA: 4 (added in v14.0, this is the default value since v14.0)

When the property is set to EnumDWT_Driver.TWAIN or 0, only devices with TWAIN drivers can be used. When set to EnumDWT_Driver.ICA or 3, only devices with ICA drivers can be used which are typically listed here. When set to EnumDWT_Driver.TWAIN_AND_ICA or 4, both TWAIN and ICA devices can be used.

Dynamsoft recommends the use of ICA drivers on macOS for the following reasons:

  1. 1. Usually there is no need to install a driver for your scanner anymore, you can plug and play
  2. 2. Generally, ICA drivers - which come with the Mac OS - works better
PageSize
Returns or sets the page size the source uses to acquire images.
Type EnumDWT_CapSupportedSizes
Accessors Get Set
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v3.0 ✓ | v10.0 ✓ | v11.0 ✓ | v11.0
Usage notes Set this property after OpenSource() and before AcquireImage().
PixelType
Returns or sets the pixel type used when acquiring images.
Type EnumDWT_PixelType
Accessors Get Set
Availability
ActiveXH5(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
Returns or sets the resolution used when acquiring images.
Type number
Accessors Get Set
Availability
ActiveXH5(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.
Type number
Accessors Get
Usage notes If SourceCount returns 0, it means there is no source available to use on the system.
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v1.0 ✓ | v10.0 ✓ | v11.0 ✓ | v11.0 ✓ | v12.1
Usage notes If SourceCount returns 0, it means there is no source available to use on the system.

Events

OnPostAllTransfers
This event is triggered when all page(s) have been scanned and transferred.
Syntax .RegisterEvent('OnPostAllTransfers',function(){...});
Arguments
  • None
Example
DWObject.RegisterEvent('OnPostAllTransfers', function() {
    console.log(DWObject.HowManyImagesInBuffer);
});
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v2.0 ✓ | v10.0 ✓ | v11.0 ✓ | v11.0 ✓ | v12.1
Usage notes This event fires after all pages in the document feeder have been scanned. This is a good place to upload the images, detect barcodes, discard blank pages, etc.
OnPostTransfer
This event is triggered after each page has been scanned and transferred.
Syntax .RegisterEvent('OnPostTransfer',function(){...});
Arguments
  • none
Example
DWObject.RegisterEvent('OnPostTransfer', function() {
    console.log("An image has been scanned");
});
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v1.0 ✓ | v10.0 ✓ | v11.0 ✓ | v11.0 ✓ | v12.1
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('OnPostTransfer',function(outputInfo){...});
Arguments
  • outputInfo: Contains info like the ImageID of the transferred image if TransferMode is "Native" or "Memory", the Path of the transferred image on the local drive if the TransferMode is set to "File" and imageInfo or extendedImageInfo about the transferred image which is returned by the scanner.
Example
DWObject.RegisterEvent('OnPostTransferAsync', function(outputInfo){
    console.log("The image ID is" + outputInfo.ImageID);
});
Availability
ActiveXH5(Windows)H5(macOS/TWAIN)H5(macOS/ICA)H5(Linux)
✓ | v15.0

results matching ""

    No results matching ""

    results matching ""

      No results matching ""