codesharks

cScanTWAIN - version 2

Looking for version 3 or version 4

Quick Start

This section offers a brief overview for how to get started and what you need to do as a developer to easily add scanning capabilities to your web application.

Typical Deployment File Structure

This is just a sample, you can place the files anywhere accessible by your web server.
/public
/lib
/cScan
cscan.min.css
cscanConfig.js
cscan.min.js

[ If you want PDF import support then include pdf support files.
These do not need to be in the same path as cscan.min.js but they do need to be in the same path together ]
pdf.min.js
pdf.worker.min.js

[ If you want to allow downloading of the cScanTWAIN.exe companion application,
see CSHARKS.CSCAN_DOWNLOAD_LINK in the cscanConfig.js configuration file]
cScanTWAIN.exe

Including files

cScanTWAIN consists of only a few files. First you need to include the CSS and library files in the HTML document. Basic understanding of HTML and CSS is a pre-requisite so this should need little explanation. Somewhere you will need to call the Javascript function csharks.cScanShow() which will open the scanner dialog and allow the user to begin scanning.

<link rel="stylesheet" href="/lib/cScan/cscan.min.css"/>

</head>
<body>

<button onclick="csharks.cScanShow()">SCAN</button>

<script src="/lib/cScan/pdf.min.js"></script>

<script src="/lib/cScan/cscanConfig.js"></script>

<script src="/lib/cScan/cscan.min.js"></script>

</body>
</html>

ORDER OF INCLUSION

Make sure the configuration file is included before the library file so that it can be confidently accessed by the component with the CSS always at the top in the HEAD section of your HTML.

PDF SUPPORT

If you want PDF import support then you only need to include pdf.min.js as shown. The pdf.worker.min.js is dynamically loaded but must be in the same directory as pdf.min.js

Including via a CDN

PDF.js is hosted on several free CDNs:
https://www.jsdelivr.com/package/npm/pdfjs-dist
https://cdnjs.com/libraries/pdf.js
https://unpkg.com/pdfjs-dist/

Support for PDF is provided by the Mozilla PDF.js project.

Companion Application

The cScanTWAIN.exe is a small 32-bit Windows only executable application that is non-intrusive and generally does not require any special installation routines or administrative privileges. It can be copied to a directory of your choosing and then executed. This companion application is required and acts as a bridge between your web application and your TWAIN compliant scanner.

STANDALONE MODE

When executed as a standalone application then a small icon will appear in the system tray where right-clicking the icon will expose a few available menu options.

Standalone works great for those with little Windows knowledge or IT support and when there is only a single user that will log in to the computer at any one time. In this mode, organizations will often put a shortcut to the companion application in the users startup folder so that it is always available, or they will create a desktop shortcut to the application so that it is easily executed by the user.

SERVICE MODE

This mode runs the application as a Windows service and depending on your IT support requirements may be a good choice, especially when more than one user logs into the same workstation and the Windows "switch user" feature is being used.

To install and run as a Windows service ( may require administrative privileges ):
Get to a command prompt and change directories to where cScanTWAIN.exe is located and execute the following commands.

cScanTWAIN /install
net start cScanTWAIN

You can also do the similar to uninstall it.

net stop cScanTWAIN
cScanTWAIN /uninstall

Configuration

Configuration settings are in the cscanConfig.js file. To help simplify your life as a developer we have attempted to minimize required and optional configurations.

Required Settings

CSHARKS.PRODUCT_KEY = "TRIAL";

The product key will be provided upon purchase of our SDK. You are free to download, implement, and demo the SDK for as long as you wish without restriction. However, without a valid product key then a watermark will appear on each scanned image obtained by our SDK.

CSHARKS.CSCAN_PORT = 26813;

This is the default port that will be used by the SDK to communicate with the cScanTWAIN.exe companion application. Unless you experience a port conflict with another application then this setting would normally not need to be changed. In the event that you do need to change the port then the cScanTWAIN.exe application will need a .ini file that specifies said port. Otherwise, no .ini file is required and everything remains as simple as possible.

Sample cScanTWAIN.ini file ( only required if a different port is needed ):
[SYSTEM]
PORT=28855

CSHARKS.CSCAN_UPLOAD_URL = "/upload";

This will be the URL on your backend where the scanned documents will be uploaded. Further down in this guide is a sample code section that uses PHP as the backend.

CSHARKS.CSCAN_HEADERS = {};

Javascript Object Representing the Headers to send with the Fetch API call. cScanTWAIN utilizes the Javascript Fetch API for uploading and if this directive is set then it will be sent in the headers object. For example, this may be useful if you need to pass authentication headers to a storage API.

CSHARKS.CSCAN_UPLOAD_PREFIX = "DEMO_";

The resulting post variable during upload will be prefixed with this setting. You can override this setting in your on javascript which allows you to have a generic upload backend while being able to identify the data being uploaded. In your backend code just inspect the filename prefix.

File Naming Convention: CSHARKS.CSCAN_UPLOAD_PREFIX + cscanImage-pageNumber
Resulting example to be sent via POST request: DEMO_cscanImage-1

CSHARKS.CSCAN_UPLOAD_IMMEDIATELY = false;

When TRUE, uploads will occur immediately after a scan operation has completed.
If you set this to TRUE then you likely will set CSHARKS.CSCAN_DELETE_AFTER_UPLOAD to TRUE in order to prevent the user from uploading the same scan more than once.

CSHARKS.CSCAN_DELETE_AFTER_UPLOAD = true;

The viewer where the scanned document images are displayed can be immediately cleared once the upload completes. If you wish to have the document images remain in the viewer then set this to false. This setting is ignored when CSHARKS.CSCAN_CLOSE_AFTER_UPLOAD is TRUE because all images are deleted from the image viewer when the dialog is closed.

CSHARKS.CSCAN_CLOSE_AFTER_UPLOAD = false;

Close the scanner dialog after upload

CSHARKS.CSCAN_SCANNER_PIXELTYPE = "GRAY";

Pixel type represents the resulting image bit depth as follows:
(BW) Black & white (1 bit depth)
(GRAY) Gray scale (8 bit depth)
(RGB) Full RGB (24 bit depth)

Changing the pixel type can impact the resulting file size. It is recommended to perform your own testing to find a pixel type that works best for your specific use case scenario. In our testing we have found the "GRAY" pixel type to be a good choice for quality vs file size.

CSHARKS.CSCAN_SCANNER_DPI = 150;

The resolution of the scanner is the DPI. A higher DPI results in slower scanning speeds but usually higher image quality. Depending on your specific use case scenario, we have found that a DPI setting of 150 to be generally optimal. It is recommended to perform your own testing to find an acceptable DPI for your use case scenario.

CSHARKS.CSCAN_SCANNER_SHOWUI = false;

This will allow the default scanner driver UI to be displayed. This provides the end user with the most control over the scanning device as possible. If true, the cScanTWAIN interface settings button for simple brightness/contrast/ADF feeder control will not be available because these settings will be overwritten by the scanners default UI interface.

Optional Settings

The below settings are optional and can be commented out. When made available then these will be conveyed to the user when the cScanTWAIN.exe application is not detected to be running.

CSHARKS.CSCAN_DOWNLOAD_LINK = "/lib/cScan/cScanTWAIN.exe";

In larger corporate environments this setting may not be desired as they tend to have managed asset and software distribution channels. However, should you wish to allow your end user to download the cScanTWAIN.exe companion application then this is where you will specify the location of the file on your web server. Once downloaded then the user can execute the application and begin scanning.

CSHARKS.CSCAN_ADMIN_NOTICE = "If you need assistance then please contact your system Administrator.";

File Type - JPEG

The resulting file type will be a base64 encoded jpeg. Unlike other solutions that attempt to upload a multipage TIFF or PDF file, we selected the simplicity of the JPEG file type. There are a variety of libraries and tools available for most programming languages that manipulate both TIFF and PDF, however, these libraries are sometime cost prohibitive.

The JPEG file can generally be manipulated and managed natively and continues to offer a universal file format that is easy to work with and that remains performant from client to server.

When the image files are uploaded to the server they are sent as base64 via a multipart form POST request with the following file format:

CSHARKS.CSCAN_UPLOAD_PREFIX + "cscanImage-" + pageNumber

Example for a (3) page document:
DEMO_cscanImage-1
DEMO_cscanImage-2
DEMO_cscanImage-3
etc...

Sample Javascript Override and Callback

// cScanTWAIN overrides are useful for changing configuration properties. As in this example, lets say we have different web pages where we want the UPLOAD URL to be different from what is already configured in the cscanConfig.js file. We can easily override this from within our pages javascript.
$(() => {
CSHARKS.CSCAN_UPLOAD_URL = "/differentDestinationUrl";
});

// Callbacks - if the callback function is defined in your javascript then it will be called by cScanTWAIN.
function cScan_OnDialogClosed() {
console.log("Dialog has closed");
}

function cScan_OnUploadComplete(response) {
console.log(response);
console.log("Upload complete");
}

Sample Server Side PHP Code

This is the most basic code we could use to convey the upload process. You would obviously wish to handle any error conditions that may occur server side.

Uploading the scanned document images to the backend server is generally straight forward. The documents are sent using the POST method as base64 encoded files within a multipart form. This should be easily adaptable to most backend web development languages and frameworks.

Saving to PDF using the popular TCPDF library

public function upload()
{
$uploadDir = '/myUploads/';
$outputFileName = 'cScan_' . date('YmdHis') . '.pdf';

$pdf = new \TCPDF();
$pdf->SetMargins(0, 0);
foreach ($_POST as $v) {
$pdf->AddPage();
$pdf->Image('@'. base64_decode($v));
}
// Save the pdf
$pdf->Output($uploadDir . $outputFileName, 'F');

// JSON response to the client
echo '{ "status":"Success" }';
}

Saving to individual JPEG files

public function upload()
{
$uploadDir = '/myUploads/';
$outputFileName = 'cScan_' . date('YmdHis');

foreach ($_POST as $k => $v) {
// Extract page from key.
//In our demo app the key will be: DEMO_cscanImage-1 and so on.
$page = (int) filter_var($k, FILTER_SANITIZE_NUMBER_INT);
// Get the image and decode
$b64Image = $v;
$data = base64_decode($b64Image);
// Save to jpeg
file_put_contents($uploadDir . $outputFileName . '_' . $page . '.jpg', $data);
}

// JSON response to the client
echo '{ "status":"Success" }';
}

Hints & Troubleshooting

Windows Firewall

Windows may block the execution of the cScanTWAIN.exe companion application. Provided this setting works with your deployment, it is our recommendation to only allow your private network. Our application only needs to communicate with the browser from the localhost and does not need access to the internet. Please consult with your System Administrator.

Windows Firewall

Security with CORS and the Companion Application

By default the companion application has an ORIGIN ALLOW of "*" meaning that it does not restrict access for specific origins. We take security very serious and the companion application honors only specific request types. It will not respond to other requests, forged or otherwise, and specifically works as a bridge between your web application and your TWAIN device.

If CORS is still a concern to your organization then to mitigate Cross-Origin Resource Sharing (CORS), the ORIGIN ALLOW for the companion application can be further restricted by using a .ini file with the following directive.

Sample cScanTWAIN.ini file:
[SYSTEM]
ORIGIN_ALLOW="https://acme.com"

The above setting will only allow the companion application to respond to a request from the origin specified, otherwise it will be ignored.

TWAIN Compliant Scanner

We obviously cannot test every single scanner available, so what we have used the most basic scanner settings possible to cover a broad range of devices. Most modern scanners should work without issues but if you run across a specific problem then we would like to hear about it.

Customizing the Viewer

This can be done by overriding the basic CSS with your own CSS file. We do not recommend modifying the css file provided with the application as this could be overwritten with a future release.

Below is a sample override of the viewer and buttons default background-color. You can place this at the top of your HTML within the HEAD section. Make sure to place it after the inclusion of cscan.min.css and depending on where you put your custom CSS then you may need to use the !important property declarative.

HAPPY SCANNING...

Download a Trial