Hello, World: Scan DSL¶

{
  "twain_cap_setting" : {
    "ICAP_PIXELTYPE" : "TWPT_RGB", // Color
    "ICAP_XRESOLUTION" : "100", // DPI: 100
    "ICAP_YRESOLUTION" : "100",
    "ICAP_SUPPORTEDSIZES" : "TWSS_USLETTER" // Paper size: TWSS_USLETTER, TWSS_A4, ...
  },
  "output_settings" : [ {
    "type" : "save",
    "format" : "pdf",
    "save_path" : "${TMP}\\${TMS}${EXT}" // Can be absolute path or path containing variables
  } ]
}

You can then pass the scan request in JSON to one of the methods accepting it. For example:

String scanRequestInJson = "{ ... }"; // scan request in DSL
Imaging imaging = new com.asprise.imaging.core.Imaging(null);
Result r = imaging.scan(scanRequestInJson, "select", true, true);

// Alternatively, use the user-friendly Asprise Scan UI Dialog
r = new AspriseScanUI().setRequest(Request.fromJson(scanRequestInJson))
      .showDialog(null, "Dialog Title", false, null);

Make Use of DSL’s Flexibility¶

The scan request is in plain string, so that you can externalize it - for example, load it from an external file, url or database.

You may also consider setting up a number of scanning profiles to allow the user to perform personalized tasks.

twain_cap_setting: Scan Settings¶

twain_cap_setting specifies scanning settings. You may use either TWAIN constant name or the actual contant value in both attribute names and values. For example, "ICAP_PIXELTYPE": "TWPT_GRAY" is equivalent to "0x0101": "1".

Various capability setting and resetting operations are supported:

Set Single Value

Using a single value to set a capability directly. Example: "ICAP_PIXELTYPE": "TWPT_GRAY"

Set Value with Fallback

A list of values separated with comma instructs Asprise Scanning to try each value in order until setting is successful. Example: "ICAP_PIXELTYPE": "TWPT_GRAY,TWPT_RGB"

Reset a Capability

Appending the capability name with /RESET to instruct the device to reset a capability to its device default value. Example: "ICAP_XSCALING/RESET": null

You may specify capability setting attributes in any order as Asprise Scanning will intelligently coordinate capability setting properly.

Common used capability list (note that a particular scanner may not support all the capabilities list below):

prompt_scan_more: Scan Multiple Pages in a Session¶

Set prompt_scan_more to true to prompt the user to scan multiple pages in a session.

i18n: Internationalization and Localization¶

Set lang to any of the following values:

• en English
• de Deutsch
• es Español
• fr Français
• it Italiano
• ja 日本語
• pt Português
• zh 中文
• user user’s OS locale

If you need to display the scanner’s UI, you may also consider to set the TWAIN capability CAP_LANGUAGE to a desired language (TWLG_USERLOCALE, TWLG_DAN, TWLG_DUT, TWLG_ENG, TWLG_FCF, TWLG_FIN, TWLG_FRN, TWLG_GER, TWLG_ICE, TWLG_ITN, TWLG_NOR, TWLG_POR, TWLG_SPA, TWLG_SWE, or TWLG_USA).

retrieve_caps: Image Information to be Returned¶

Use it when you are interested to know the metadata about the images or the actual scanning setting used when scanning the images. retrieve_caps specifies an array of capabilites should be returned for each image acquried. You may use either TWAIN constant name or the actual contant value as the array element. For example, ["ICAP_PIXELTYPE", "ICAP_XRESOLUTION"] is equivalent to ["0x0101",  "0x1118"].

You may refer to twain_cap_setting: Scan Settings for common used capabilities.

retrieve_extended_image_attrs: Extended Image Attributes to be Returned¶

Similar to retrieve_caps, retrieve_extended_image_attrs specifies an array of extended image attributes to be returned for each image acquried. You may use either TWAIN constant name or the actual contant value as the array element. For example, ["TWEI_PATCHCODE"] is equivalent to ["0x1212"].

Note that only high end scanners may return extended image attributes.

For your convenience, "BARCODE" will be expanded to the following list of attributes: “TWEI_BARCODECOUNT”, “TWEI_BARCODECONFIDENCE”, “TWEI_BARCODEX”, “TWEI_BARCODEY”, “TWEI_BARCODETYPE”, “TWEI_BARCODEROTATION”, “TWEI_BARCODETEXTLENGTH”, “TWEI_BARCODETEXT”.

recognize_barcodes: Barcode Recognition¶

You may request high end scanners to read barcodes using retrieve_extended_image_attrs. However, the rest of scanners are unable to decode barcodes. By setting recognize_barcodes to true, you instruct Asprise Scanning to recognize a wide range of barcode and QR code formats even if the scanner devices don’t support barcode recognition. The following barcode formats are supported:

• CODE 128 (128b, 128C, 128raw)
• EAN-8 EAN-13
• UPC-A, UPC-E
• code 3 of 9
• code interleaved 2 of 5
• QR code
• DataMatrix
• Aztec
• PDF 417

detect_blank_pages: Detect/Discard Blank Pages Automatically¶

To detect blank pages, you can set detect_blank_pages to true. You may also tune the following paramters:

blank_page_threshold

Specifies the maximum ink coverage to be considered as blank. The default value is 0.02, meaning if the ink coverage is less than 2%, then it is considered as blank. Valid value range: 0 ~ 1.0

blank_page_margin_percent

Page margins are often prone to noise. This parameter allow you to exclude certain percentage of page on the margins. Default value is 8, meaning 8% of page width is considered as left and right margins and 8% of page height is for top and bottom margins. Valid value range: 0 ~ 100

blank_page_policy

What to do with blank page? “keep” (default) or “remove”.

doc_separators: Document Separation¶

Asprise scan makes batch separation easily and improves documents organization for both high end scanners as well as economic models. Even if the scanner doesn’t support automatic document separatation, you can use Asprise scan to perform auto document separation on a batch scan and save scan results in multiple PDF or TIFF files.

You may use any combination of the following as a document separator:

Patch codes

Patch codes are a set of 6 distinct barcode patterns (1, 2, 3, 4, 6 and T) that are traditionally used as document separators when scanning. There are six distinct barcode patterns (Patch 1, 2, 3, 4, 6 and T). A common use now is to use the Patch T code or the Patch 2 code as a Page (document) separator. To use patch T as the only separator, you specify "TWEI_PATCHCODE:5:DOC_SEP". To use any of the patch code as separator, you specify "TWEI_PATCHCODE:?:DOC_SEP" (? matches a single character and * matches any number of characters; DOC_SEP means the separating page should not be included in the document). Note to use this feature, you need: 1) set ICAP_PATCHCODEDETECTIONENABLED to 1 in twain_cap_setting: Scan Settings; 2) retrieve "TWEI_PATCHCODE" in retrieve_extended_image_attrs as described in retrieve_extended_image_attrs: Extended Image Attributes to be Returned.

Any other TWAIN extended image attributes (TWEI)

Many high end scanners are capable of providing other extended image attributes, for example, TWEI_BARCODETEXT returns the barcode text natively recognized by the scanner when ICAP_BARCODEDETECTIONENABLED is set to 1. For example, if there is a barcode with text doc_[x] on first pages of the documents, you can use "TWEI_BARCODETEXT:doc_*:DOC_NEW" (? matches a single character and * matches any number of characters; DOC_NEW means the separating page is included as the first page of the new document).

Barcodes

To separate documents, you can also use Asprise scan’s built in barcode recognition. Turn on barcode reading as instructed in recognize_barcodes: Barcode Recognition and specify the barcode content match for document separation, e.g. "barcode:abc*:DOC_NEW".

Blank pages

To use blank pages for document separation, you simply specify "blank:DOC_SEP".

Manual document separation using Asprise Dialog

On Asprise Dialog, the user can manually mark an image as a document separator (separating documents only, it is not part of any document) or mark it as beginning of a new document (it is the first page of the document) or unmark it.

Image Formats Supported¶

You use format attribute to specify the desired output format. The following list of image formats are supported:

jpg

JPEG format. This is the default format, i.e., jpg will be used if format attribute is not present.

Use jpeg_quality to specify the JPEG quality. The default value is 80.

bmp

Bitmap format.

png

Portable Network Graphics.

tif

Tagged Image File Format.

Use tiff_compression to specify the compression to be used for TIFF. Valid values are: G4, G3, LZW, RLE, ZIP and NONE (default).

pdf

Portable Document Format. The following list of attributes may be used to customize PDF output:

pdf_force_black_white: Default is false, set to true to use CCITT Group 4 Compression for ultra small file size.

pdfa_compliant: Default is false, set to true to force PDF-A/1 compliance.

pdf_text_line: Optionally, you can specify a line to text to be printed on the bottom left of the first page. Macros can be used e.g., “Scanned by ${COMPUTERNAME}/${USERNAME} on ${DATETIME}”.

pdf_owner_password, pdf_user_password: Optionally, you may specify password when pdfa_compliant is false.

exif: the following tags can be specified: DocumentName, UserComment and Copyright.

save, save-thumbnail¶

You use save and save-thumbnail to save the scanned images or thumbnails to local hard disk drives or mapped network locations.

save_path is a required attribute, which you use to specify the target output location. Note save_path specifies the complete target file location, not the containing folder. If you set "save_path": .\\test.jpg and there are multiple images scanned, you’ll get only the last one as previous images will be overwritten. To avoid this problem, you may use any of the macros listed below:

${TMS}

Timestamp with milliseconds, e.g, ‘2020-12-25_08-06-27.880’.

${TM}

Timestamp without milliseconds, e.g, ‘2020-12-25_08-06-27’.

${DATE}

Readable timestamp in a format similar to ISO 8601.

${I}

Image index in a scanning session.

${EXT}

Image file extension according to the image format specified using format (default is JPG).

${TMP}, ${USERPROFILE} and all other env variables

Environment variables are supported. You may define custom environment variables and use them in the path as long as your enclose the names with ${ and }.

Unsupported macros will be replaced with _.

The actual path that the image is written will be returned in the result.

upload, upload-thumbnail¶

You use upload and upload-thumbnail to upload the scanned images or thumbnails to a remote server. The back end can be implemented in any programming language like C, C#/VB.NET, Java, Node.js, PHP, Python, Ruby on Rails, etc. as image data are sent using standard HTTP POST.

To specify the upload destination, you need to set upload_target to an object with the following attributes:

url

The only required attribute; specifies the target URL.

max_retries

Max number of retries before giving up; the default value is 2.

post_file_field_name

The name of the POST field for image files. Default value is ‘asprise_scans’ if there is only one file or ‘asprise_scans[]’ if there are many files. You don’t need to add ‘[]’ as the system will auto fix it.

post_fields

Optionally specifies additional fields to be POSTed.

cookies

Optional cookies to be sent over along.

auth

Optionally authentication token

headers

Optionally adds an array of additional HTTP request headers

log_file

Optionally specify a local file to print logging information for debug purpose.

max_operation_time

Max HTTP operation time allowed in seconds. Default value is 1200 (20 minutes).

return-base64, return-base64-thumbnail¶

Use return-base64 and return-base64-thumbnail to return the data of the scanned images and thumbnails in base64 format.

Once obtained the base64 encoded data from the result, you can then decode base64 data into binary and read the image from it.