WEB DOCUMENT VIEWER WHITEPAPER

When creating a new application using the WebDocumentViewer, whether you are migrating from our older web control (WebImageViewer / WebAnnotationViewer), or you are starting a new web project from scratch, there are a few steps you will need in order to get the project up and running.

We will use this document to discuss the requirements of using the WebDocumentViewer, and then walk through its creation, step by step.

WDV HISTORY

WebDocumentViewer (and its companion Thumbnail Viewer, WebDocumentThumbnailer) is a modern HTML5 compatible web viewing control. It replaces WebAnnotationViewer (WebImageViewer) and WebDocumentThumbnailer replaces WebThumbnailViewer. These older controls are still supported, but are considered legacy controls with no new features being added.

As Microsoft further deprecates 'classic asp.net web apps', these legacy controls will become more and more difficult to maintain and support. Customers using WAV/WIV and WTV are encouraged to begin migration to WDV with or without WDT.

When creating a new application using the WebDocumentViewer, whether you are migrating from our older web control (WebImageViewer / WebAnnotationViewer), or you are starting a new web project from scratch, there are a few steps you will need in order to get the project up and running.

We will use this KB to discuss the requirements of using the WebDocumentViewer, and then walk through its creation, step by step.

TECHNICAL REQUIREMENTS

Development Tools/Environment

This document and our SDK assume that you're a developer familiar with basic use of Visual Studio, IIS Express or IIS, and general web application development practices using MS Visual Studio 2013 or later. The samples will be using an HTML 5 approach in a non-MVC application targeting .NET framework 4.5.2 in a 64 bit application and using Visual Studio's built in II

If you are developing an application using DotImage that works fine on your development machine with your SDK license installed, but throws an license exception similar to the following message, it's likely that the license files were not embedded properly in the applications resource file.

"System.ComponentModel.LicenseException: A license key could not be found at the location 'c:\windows\assembly\gac\atalasoft.dotimage\1.1.1538.39227__2b02b46f7326f73b\atalasoft.dotimage.lic'. Please purchase a license from www.atalasoft.com or request an evaluation key."

There could be two reasons for this problem.

1) The licenses.licx file is not located in the project root directory. This is required for WinForms applications. When dropping a DotImage control or component onto a form, this file will be automatically created. If you are using just the class library, you will have to manually create the file and it should look like the following:

Atalasoft.Imaging.AtalaImage, Atalasoft.dotImage

When using the various add-ons such as Barcode Reader, PDF Rasterizer, JPEG2000, and JBIG2 compression, the following entries must be included in the licenses.licx for each add-on that is referenced.

Atalasoft.Imaging.Codec.Jpeg2000.Jp2Decoder, Atalasoft.dotImage.Jpeg2000
Atalasoft.Imaging.Codec.Jbig2.Jb2Decoder, Atalasoft.dotImage.Jbig2
Atalasoft.Imaging.Codec.Pdf.PdfDecoder, Atalasoft.dotImage.PdfRasterizer
Atalasoft.Barcoding.BarcodeReader, Atalasoft.dotImage.BarcodeReader

The documentation explains the creating of the licenses.licx file in more detail.

2) The other reason this might be the problem is when creating a dll that references DotImage. In that case, the license file cannot be embedded. You will instead be required to place a reference to DotImage in the EXE that references this dll. Search the KB on Embedded Component Licens

When scanning through Citrix it's possible that the device ID will change between calls to open the source manager. This will cause the Device objects in Acquisition.Devices to fail when trying to connect.

To work around this, use the Acquisition.CreateDeviceSession method. It will create a new disposable Device object that can be used once and thrown away. For this to work, you must provide a parent for the Acquisition object and call Dispose on the Device when you're finished with the scan.

Attached to this article is an example project showing how to use CreateDeviceSession; both C# and VB projects are provided.

Some customers have reported difficulty downloading the example attached in this KB system, so here is a link to a dropbox hosted version:

CitrixScanning_v11.0.zip

Note: This information is specific to DotImage at the time it was written and may change slightly in future versions.

Every OcrEngine has different requirements in terms of how it is deployed. Atalasoft has tried to formalize this process as much as possible as well as to provide guidelines on the mechanism for deployment. Licensing is covered in another topic. This topic covers how to ensure that an OcrEngine will be able to start and will be able to find its own resources.

In your SDK installation, you will find a folder named "OcrResources". This folder is the general folder for all supported OCR engines. Within it you will see a structure like this:

EngineManufacturer1

<Files>

EngineManufacturer2

<Files>

...

EngineManufacturerN

...

In general, most of the handling of loading and locating resources is managed by Atalasoft or by the engine itself and does not require work by the client, but in custom situations, there may be work to be done by the client to handle this.

To sort this out, let's start with a few definitions:

engine resources folder - this is the folder which contains the OCR Engine's resource files
OCR resources folder - the top level folder of all OCR Engine resources, called "OcrResources"
application folder - the folder where your application is installed
assembly folder - the folder which contains the dotImage assembly files (ie, Atalasoft.dotImage.Ocr.dll), this ma

NOTE: This article was created as a means to provide links to the 10.6 versions of our legacy demos.

This was needed because in 10.7, we introduced OfficeDecoder to replace OfficeAdapterDecoder and it has some specific requirements. Also, in 10.7, we removed RecoStar OCR engine and added Abbyy OCR engine... these are the preserved versions of the demos meant to work with 10.6 as those changes would "break" DotImage for 10.6 users.

For version 10.7 compatible demos, please see the following article:

Q10449 - FAQ: Where Have all the 10.7 Demos Gone?

For the most current (11.0) demos please see:

Q10412 - FAQ: Where Have All The Demos Gone?

If you're a long-time user of DotImage, you may remember back to when we used to include a whole bunch of really nifty demos along with the installation of the SDK - full sources and compiled apps.

The problem we ran into was that the demos were causing the installer to get really big - they added about 100MiB to the download. So the decision was made to move them to an online Sample Application Gallery.

On May 1, 2015, we redesigned the web site and the sample application gallery was reduced to just a few key demos that were the most commonly asked for/used. However, over the years, Support and our customers have found many of those other demos to be useful.

So, without further delay: here is a list of links to those "Legacy Demos"

With the PdfRasterizer add-on, merging two Pdf files into one is a simple coding task. First combine the two file paths into one string array. Then use that array to construct a FileSystemImageSource object. Then using a PdfEncoder, call the Save method overload that takes an ImageSource.

C#

static Form1()

{

RegisteredDecoders.Decoders.Add(newPdfDecoder());

}

ASP.NET CORE WDV WHITEPAPER

SEE ALSO

Before we get started, it's important to note that this document is focusing only on the aspects of getting started with WDV in the context of ASP.NET Core web applications. We will discuss the differences between WDV / WDT in ASP.NET Core and standard ASP.NET, but we won't go into strenuous details about WDV and some of the more advanced things you can do with it.

This is because there is very little functional difference between WDV/WDT in ASP.NET Core versus ASP.NET. Herein we hope to give you the fundamentals you need to operate within the ASP.NET Core paradigm, and give you the tools to understand how to hook into the server side events and add server side code, but once you understand how to hook in / the analogy to what we call the "handler" in the ASP.NET version, Any of the implementation details are pretty much the same.

All of this means that you may want to have a look at our related papers/articles:

• WDV Whitepaper
• Wi

WINGSCAN WHITEPAPER: APPENDING

APPENDING ADDITIONAL SCANS

This Whitepaper is going to be "laser focused" on implementing one specific use case with WingScan: To allow one append the results of a second and subsequent scan to an existing document / previous scan present in the WebDocumentViewer / WebDocumentThumbnailer.

The "out of the box" experience with WingScan is that when you open or scan a document, you are replacing any existing document that is present. So if you have say 2 pages loaded and you begin a scan with page.. you will end up with just the new 1 page scan open and the former document is lost/closed. This then is about "what if I want to add more pages to the existing open document".

This is not a "getting started with WingScan" tutorial. For that, please see Q10462 - INFO: WingScan Whitepaper - Getting Started with Web Scanning.

For other White Papers please see the Whitepaper category on our knowledgebase.

TECHNICAL OVERVIEW

In some ways, the append versus open operation is a WebDocumentViewer / WebDocumentThumbnailer operation. We could easily write a KB on "appending a document in WDV" ... in fact, we may do that at a future date. We will be taking advantage of the WDV/WDT viewer.document.insertPages() feature. The difficulty is that in order to insert multiple pages, one must know how many pages one will be inserting. There is no "just insert all the pages in this document".. (An enhancement request for this is officially on file but has not yet been implemented).

An additional complication is that you don't necessarily know in advance before oyu scan how many pages will be part of the scan. If you are using blank page detection/removal (VRS License required) then the number of

Release Notes

The full official release notes for DotImage can be found below:

Release Notes Page

Individual releases

Initial Release (December 2018) - v11.1.0.0

http://www.atalasupport.net/downloads/v11.1/AtalasoftDotImageReleaseNotes_11.1.0_EN.pdf

Support has received many requests to make a more "search friendly" version of the release notes.

Your wish is our command:
Q10472 - INFO: 11.1 Full Release Notes

Breaking Changes

WebDocumentViewer DocumentSave File Extension Preservation

In all versions before 11.0, the DocumentSave (as well as DocumentStreamWritten and AnnotationStreamWritten) save events have provided the e.FileName as the original file name but with the extension stripped off. This led to a good deal of extra code having to be written to determine the proper file type to add an extension back in

In 11.1, this incorrect behavior is corrected. This will present as a BREAKING CHANGE to users who have WDV save events handled with any custom code that needed to compensate for the missing file extension.

example: Original file opened in WDV was "GettysburgAddress.tif"
11.0 and older behavior: DocumentSave event e.FileName in the handler would receive "GettysburgAddress" for the filename.. same with e.Filename in the AnnotationStreamWritten and DocumentStreamWritten events

in 11.1 and newer the e.FileName will be "GettysburgAddress.tif" so that combining the e.SaveFolder and e.FileName will provide the web relative path to the file without having to guess or append .tif

NOTE: This article is about the 11.0 specific versions of our legacy demos.. if you're looking for demos for our current version, please see
Q10412 - FAQ: Where Have All The Demos Gone?

11.0 removed our .NET 2.0 dlls and replaced them with .NET 3.5 dlls. Likewise, we removed our .NET 4.0 dlls and replaced them with .NET 4.5.2 dlls.

If you need 10.7-compatible versions of these demos, please see
Q10449 - FAQ: Where have all the 10.7 Demos Gone?

If you need 10.6-compatible versions of these demos, please see
Q10435 - FAQ: Where have all the 10.6 Demos Gone?

If you're a long-time user of DotImage, you may remember back to when we used to include a whole bunch of really nifty demos along with the installation of the SDK - full sources and compiled apps.

The problem we ran into was that the demos were causing the installer to get really big - they added about 100MiB to the download. So the decision was made to move them to an online Sample Application Gallery.

On May 1, 2015, we redesigned the web site and the sample application gallery was reduced to just a few key demos that were the most commonly asked for/used. However, over the years, Support and our customers have found many of those other demos to be useful.

So, without further delay: here is a list of links to those "Legacy Demos"

Google made a recent change with what types of certificates they will accept in the recent Chrome 58 update.

The result is that web based scanning with Google Chrome and our WebCaptureService over https may show an "INSECURE" warning. In many cases, web scanning won't even recognize that the service is installed. Other browsers (FireFox and IE were still working at the time, but we're seeing signs they're following Google's lead, so this could affect any browser.

UPDATE: FINAL
With the official inclusion of the fixed code in the regular build cycle, and multiple issues reported with applying the hotfixed resources to older builds, the official support answer is now that you must upgrade to at least 10.7.0.10. However, 10.7.0.13 is the final ever 10.7 build. If you can't update to the latest 11.0, the fix for this issue is to upgrade to 10.7.0.13

10.7.0.13.3777 can be downloaded here

DotTwain has tracing code added to it in order to help us debug a problem. You can enable tracing by adding an Application Configuration File (app.config) to your project. Then add the following code to create a TraceSwitch named "Atalasoft.Twain".

Atalasoft has an add-on component called "Forms Recognition" and it's important that we first discuss the definition/meaning of "Forms Recognition" in the context of Atalasoft.

Specifically: Our Forms Recognition components are Optical Mark Recognition (OMR) components.

Here is a list of our OMR (Forms Processing) demos and proofs of concept.

Keep in mind that none of them are meant as examples of "best practices" or production ready code.

They're meant to give programmers who intend to use our OMR engine a bit of insight into how various components of the OMR process work.

OMR Demo
This is a place to start ... you'll want to download the sample template listed below to get started
OMRDemo_11.0.zip

OMR Template Tool
This is a rough utility for showing how to generate a template. It's meant as a Proof of concept to show how to build a template programmatically… it is ~not~ meant to be your sole means of generating templates.
OMRTemplateTool_11.0.zip

OMR Diagnostic Tool
This is NOT feature complete, but lets you examine a template to see where the marks have been defined. You can use it for some template modification, but it's a bit "fiddly". It now has the ability to recognize marks and provides an excellent "stream of consciousness" logging of the OMR Recognition process in its Recognize

Note: The PdfDecoder class is part of our PdfReader (Formerly called PdfRasterizer) module, which is an add-on to DotImage. To use this class, you must add Atalasoft.dotImage.PdfReader.dll as a reference to your project, and you will need a license file for this module. You can request an evaluation license file for this module using the DotImage Activation Wizard.

You will also want to add a PdfDecoder to your RegisteredDecoders collection in a static constructor for your class:

[C#]

staic MyClass()

{

RegisteredDecoders.Decoders.Add(new PdfDecoder() { Resolution = 200 });

}

[VB.NET]

Shared Sub New

RegisteredDecoders.Decoders.Add(N

This article will cover a technical overview of the WingScan WebCapture Service used in 10.5.2 and newer. For information on migrating your application in general, please see:
Migrating a WingScan based app to 10.5.2

As of 10.5.2, our WingScan WebCapture browser plugins have been replaced by a new local service that will handle interaction with the scanner and uploading the scanned files to the web server.

Installation

Instead of a plugin, your users will need to run the installer msi:
Kofax.WebCapture.Installer.msi

This is shipped with DotImage and can be found in this location:

C:\Program Files (x86)\Atalasoft\DotImage 10.7\bin\2.0\x86\WebResources\WebCapture\

Many users will find that it works for them to just provide the MSI to users when the application detects that scanning is present, but the service is not installed. If a user with administrative privleges runs the .msi, then service will be isntalled and become immediately available for scanning.

However, for environments where users do not have administrative privledges, or enterprise environments where installation needs to be scripted and/or pushed from Group Policy, The install can be pushed silently:

Enterprise deployment – silent install

msiexec /i Kofax.WebCapture.Installer.msi /quiet

Install location

%PROGRAMDATA%\WebCapture

Permissions Required

OfficeAdapterDecoder Design Implications

NOTE before Proceeding:

As of 10.7 we introduced OfficeDecoder as a replacement for OfficeAdapterdecoder. Support STRONLGY recommends using it instead of OfficeAdapterDecoder.

However, he OfficeAdapterDecoder is still part of DotImage .. it is distinct from the newer OfficeDecoder.

OfficeDecoder: Present in 10.7 and newer

Uses the Perceptive filter objects

Does not require Office license

MAY NOT render pages precisely as Office shows them

Support STRONGLY recommends this be used

Please see Q10436 - INFO: Changes Introduced in 10.7 for OfficeDecoder details

From time to time, customers ask us for our "XML Schema" for our XMP/XML annotations.. the serialized annotation data saved out from our SDK

The short answer is that we do not provide one, and that furthermore, manual editing/ modification of serialized Atalasoft annotations is utterly unsupported.

The longer answer is as follows:
Our XML / XMP annotations which are saved out when exporting to XMP format is the direct result of serialization of our AnnotationData objects. Those objects can change without notice as they're internal to Atalasoft. We will not change our Public APIs without documentation/ notice and we work hard to ensure that our own components "round trip" read/write annotation data correctly... and that furthermore that our current components will properly understand older AnnotationData.

When a customer directly modifies our XMP or attempts to mimic our Annotation object creation/serialization making their own XML / XMP, we have no way of ensuring that it will properly round trip.. and worse yet, such manual creation/modification can introduce subtle errors/issues into the annotation data which could make for exceedingly difficult and time consuming troubleshooting/debugging and can consume huge amounts of Atalasoft support and engineering resources when customers report such bugs which are ultimately caused my manual modification of our XML

For those reasons, we can not and will not provide an XML Schema. Also, if we encounter an issue due to direct customer manipulation of our XML serialized annotations, the official reply is that such modification is utterly unsupported.

If you have a situation where you need to add custom data to annotations or are unsure of how to modify serialized annotation data in a way that is compliant with Atalasoft best practices, please feel free to create a support case

If you need to make alterations to annotations, please load your annotation data into an Ann

Atalasoft's implementation of AbbyyEngine OCR engine is tuned to try and avoid getting caught up in particularly "busy" images (when asked to OCR a document that contains not just text but pictures/images as well etc...

However, there are times when you have content you want to force it to read.

The fix is to use the PageLocation event to override AbbyyEngine

// creating new AbbyyEngine instance
AbbyyEngine engine = new AbbyyEngine();

// BEFORE calling engine.Initialize(), set up this handler
engine.PageLocation += engine_PageLocation;

// set any other pre-initialization code here

engine.Initialize();

// NOW you can use the AbbyyEngine as usual
... code here ...

// cleanup when done
engine.ShutDown();
engine.Dispose();

/// this is the engine_PageLocation handler that will convert OcrImageRegion regions into
/// AbbyyOcrTextRegion objects and allow recognition within those formerly ignored regions
private void engine_PageLocation(object sender, OcrPageLocationEventArgs e)
{
e.RegionsOut = new OcrRegionCollection();
foreach (OcrRegion ocrRegion in e.RegionsIn)
{
e.RegionsOut.Add(ocrRegion is OcrImageRegion
? new AbbyyOcrTextRegion(ocrRegion.PolygonBounds)
: ocrRegion);
}
}

This article goes over how to create a custom Web Document Viewer handler. This allows you to provide custom image sources to the Web Document Viewer, whether it is a document loaded from a database, a procedurally generated image or simply a stream that doesn't map directly to a file in the relative web path.

The first step is to make sure you have the relevant references in your project. Make sure you have Atalasoft.dotImage.dll, Atalasoft.dotImage.Lib.dll, Atalasoft.dotImage.WebControls.dll, Atalasoft.dotImage.Lib.dll and Atalasoft.Shared.dll added to your project. You will also need any additional libraries you may be using.

The next step is to either create or include a "Generic Handler" (an .ashx file.) It can be either C# or VB.Net. I've attached pre-made handlers for both C# and VB.Net to this KB, so you can skip most of this and jump straight to grabbing those .ashx files.

Once you have that added to your project, open it up and update the definition of the class. Instead of Implementing the IHttpHandler interface we're going to inherit from Atalasoft.Imaging.WebControls. WebDocumentRequestHandler

(Please note that from here on out, you will need to replace our default " Handler " with whatever class name you have chosen. Also, I'm not going to assume you've added the relevant using or Imports statements to your handler and will include the full class name of all the classes we're using. Feel free to add them and save yourself some space.)

C#
public class Handler : WebDocumentRequestHandler