PixTools/Image Processing

Overview
Version 7.2

Pixel Translations makes no warranties, either expressed or implied, regarding the computer software described in this or other related documentation, including its merchantability, or its fitness for any particular purpose, except as explicitly stated in any enclosed product warranty. The exclusion of implied warranties is not permitted by some states. The above exclusion may not apply to you. This warranty provides you with specific legal rights. There may be other rights you may have which vary from state to state. Copyright 2005 Pixel Translations. All Rights Reserved. All information contained in this document is proprietary to Pixel Translations. No part of this document may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form without the prior consent, in writing, of Pixel Translations. The software described in this document is furnished under a contract and license agreement. The ISIS specification was developed by Pixel Translations, Inc., and is 1990-2005 Pixel Translations. Permission is hereby granted to make copies of and use the specification so long as the specification is not resold for profit, and so long as the original copyright notices are left intact. This manual describes the installation and use of copyrighted software. Said software is licensed to the purchaser for use only in strict accordance with the terms of the contract and license. PixTools, ISIS, and ScaleToGray are registered trademarks of Pixel Translations and Captiva Software Corporation. , , ScanAheadMultiStreamand QuickScanare trademarks of Pixel Translations, Inc. All other trademarks and registered trademarks are the property of their respective owners. Pixel Translations A Division of Captiva Software Corporation 25 Metro Drive, Suite 400 San Jose, CA 95110-1316 Tools Integration (technical support) Sales: Main: Fax email: Web site: (408) 441-2260 (408) 441-2280 (408) 441-2200 (408) 441-2201 support@pixtran.com sales@pixtran.com http://www.pixtran.com

Part number: ip2.pdf - 7.2 (MC 08-Feb-2005)

Contents
Chapter 1 About this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1 1 3 4 4

Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Product family . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standard directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Whats new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2

What is PixTools/IP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Overview of PixTools/IP Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 PixTools/IP filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 ImageFilters object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 BarcodeResult object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Result object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 3

Using PixTools/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Using PixTools/IP with Visual Studio.NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Using custom permissions files with Visual Studio.NET . . . . . . . . . . . . . . . . . . . . . . . . 15 Using PixTools/IP with Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Using custom permissions files with Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Using PixTools/IP with C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Developing with the Microsoft extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Developing without the Microsoft extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Using PixTools/IP with C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Using PixTools/IP with PixTools/EZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Image processing during a batch scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Using PixTools/IP with PixTools/Scan and PixTools/View . . . . . . . . . . . . . . . . . . . . . . . . . 20 Using pixip2.pxn as an ISIS driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Using AutoPipe to link to an ISIS pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Using ImageFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 4

Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Starting early . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 How permissions control works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Permissions files included with the toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Implementing permissions control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Creating your custom permissions files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Running MAKEPERM from the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Registering your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 VB.NET: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 C#: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Visual Basic: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 C and C++: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Registration for multiple toolkits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Distributing your custom permissions files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 5

Distributing your finished application . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Toolkit files to distribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Installing redistributable files using Install for Installer . . . . . . . . . . . . . . . . . . . . . . . . . 33 Installing redistributable files by modifying the Installer . . . . . . . . . . . . . . . . . . . . . . . . 35 Merge modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Using merge modules with a Visual Studio .NET Setup Project . . . . . . . . . . . . . . . . . . 36 Using merge modules with InstallShield Developer or Express . . . . . . . . . . . . . . . . . . 37 Install locations and files to include when using the flat directory tree . . . . . . . . . . . . . . . . . 39 Issues with other ISIS applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

1
About this guide
Intended audience
This guide discusses the PixTools/IP toolkit. Different chapters of this guide are designed for different audiences, as described below: What is PixTools/IP? on page 5 is intended for anybody who wants to know about PixTools/IP and how it works. This chapter provides an overview of the toolkits features and conceptual information about how it works. Using PixTools/IP on page 13 is intended for those responsible for developing image processing applications. It includes instructions for using the PixTools/IP toolkit with other PixTools toolkits. Permissions on page 23 is intended for those responsible for developing and distributing image processing applications. It includes information on licensing and permissions control. Distributing your finished application on page 33 is intended for those responsible for developing and distributing image processing applications. It includes information on toolkit files to distribute.

Product family
Pixel Translations sets the standard for imaging tools with a product line of toolkits for integrating quality document imaging functionality into your applications. Each toolkit can be used alone or with another PixTools product. In addition, since our toolkits use ISIS Pipes connectors, you can use them with ISIS compatible toolkits from other vendors like The Professional Developer's Kit for OCR from ScanSoft (formerly Caere Corporation.)

PixTools/IP Overview

The PixTools family of products includes the following: PixTools/IP PixTools/Image Processing is optimized for rapid analysis and modification (where appropriate) of images. PixTools/Image Processing is a full featured toolkit that provides different operations which can be applied to color and black and white images, alone, or in combination. These operations or filters, can be used to improve quality and readability, reduce file size, or both. Quality improvements can substantially enhance the accuracy of optical character recognition (OCR). PixTools/Image Processing also supports Barcode recognition! PixTools/EZ PixTools/EZ brings together the superior document imaging functions of both PixTools/Scan and PixTools/ View in a set of custom controls for ActiveX/OCX. While C developers can work with any of our toolkits, PixTools/ EZ may also be used by developers working in fourth generation languages (4GLs), like Microsoft Visual Basic. This makes for the fastest development time yet: just select, drag, drop and enable! PixTools/EZ offers over 260 properties, methods, and events, so you have tremendous flexibility in adding scan, view, annotate, and print functions to your application. PixTools/EZ also includes the PixTools/Annotations library. This library provides the functionality for creating, editing, and viewing annotation objects on an image.

Chapter 1 About this guide

PixTools/Scan

PixTools/Scan focuses on providing peak performance from every ISIS certified scanning device. It drives both SCSI and video scanners at or beyond rated speeds, over 400 images per minute! Features such as ScanAhead maintain maximum throughput by caching image data in the ISIS driver, even when an application temporarily cannot keep up with the scanner. PixTools/Scan can enable your application to work with over 300 ISIS certified scanners from makers like Bell & Howell, Canon, Fujitsu, Hewlett-Packard, Kodak, Panasonic, Ricoh, and many others.

PixTools/View

PixTools/View is a full featured API that provides all the image viewing and printing functions you need including image display, rotation, scaling, scale-to-gray, color, and annotation. PixTools/View uses in memory storage of compressed images, combined with superior decompression libraries. That means fast image display and minimal memory usage. Page images are also automatically cached and prefetched in the background, maximizing memory management and performance. PixTools/View optimizes operations like image rotation and annotation updates. PixTools/View also includes the PixTools/Annotations library. This library provides the functionality for creating, editing, and viewing annotation objects on an image.

QuickScan

Image scanning and viewing application based on PixTools/EZ and PixTools/IP. Sold by Pixel Translations with various levels of scanner support.

Document conventions
The following conventions are used throughout this manual to define syntax: Convention Bold text Meaning Denotes a term or character to be typed literally, such as a property name; for example: State. You must type these characters exactly as shown, although in most cases, the development system will correctly capitalize object names for you.

PixTools/IP Overview

Convention Italic text

Meaning Denotes a placeholder or variable: You must provide the actual value. For example: filter.Run(image) requires you to substitute values for filter and image. Denotes defined constants. Sets off code examples, filenames, and shows syntax spacing.

FULL CAPITALS monospace

Microsoft Windows comes in a variety of versions. In this manual, the terms Microsoft Windows and Windows generically refer to any or all supported WIN32 versions.

Standard directories
The following placeholders are used throughout this manual when discussing standard directories in Windows or when sample path names include standard directories: Placeholder <INSDIR> <WINDIR> <SYSDIR> <APPDIR> Meaning Substitutes for the directory where the toolkit is installed. Substitutes for the Windows directory. Substitutes for the Windows system directory. Substitutes for the application directory. The application directory is the directory on the users system where you install your applications executable.

Whats new
New UseChecksum property in the BinaryBarcodeDetectionV2 filter. Support for DataMatrix bar code type (Types property of BinaryBarcodeDetectionV2 filter). New Bottom, Top, Left, and Right properties in the BinaryHoleRemoval filter.

2
What is PixTools/IP?
PixTools/Image Processing (PixTools/IP) is a full-featured toolkit provided as a set of ISIS drivers, which utilize the well defined ISIS Pipes methodology for interconnecting imaging components with minimal code and effort. With the PixTools/IP toolkit, you can easily integrate powerful image processing features into your application to meet the most demanding user requirements. The toolkit provides filters that perform an array of common image processing tasks such as deskewing, thresholding, noise removal, and barcode recognition. You can use PixTools/IP as a stand-alone toolkit, or in conjunction with another PixTools product (PixTools/Scan, PixTools/View, or PixTools/EZ). Important The right to use PixTools development toolkits is granted by license agreement. Furthermore, the right to distribute an application based on PixTools libraries requires that you execute a redistribution license agreement and, in general, pay royalties based on the number of copies you ship. Before beginning application development, be sure that you understand the licensing requirements. More information can be found in Chapter 5, Distributing your finished application. The PixTools/IP toolkit enables you to add image processing capabilities to your applications or to create new image processing applications by using either of the following: Common Language Runtime (CLR) classes that can be used with your Microsoft .NET Framework (VB.NET, C#, and Managed C++) development platform. OLE Component Object Model (COM) objects that can be used with your COM development platform (Microsoft Visual Basic, C++, and C). PixTools/IP includes objects that make it easy to design applications that include common image processing tasks such as deskewing, noise removal, barcode recognition, sub-region definition, and the maintenance of lists of filter processes. PixTools/IP is designed to work with ISIS components in the PixTools family and also available from other sources.

PixTools/IP Overview

You can use PixTools/IP with your application either by manipulating some properties and methods of the CLR or COM object inside your application or by using the pixip2.pxn ISIS driver. By using the ISIS interface, your application can load, enable, and control the application of image processing filters without any knowledge of CLR or COM. For a description of the tags that enable you to control pixip2.pxn through its ISIS interface, see Using PixTools/IP with PixTools/Scan and PixTools/ View on page 20. If you want to enable your application to control PixTools/IP through its API and use its features at a programmatic level, then you must access it as a CLR or COM object to manipulate all of its properties and methods.

Overview of PixTools/IP Objects

The PixTools/IP toolkit includes a set of objects that make it easier to encapsulate concepts used in image processing and to maintain application-level parameters. For more information about each filter and its properties and methods, please refer to the PixTools/IP Programmers Reference online help system.

PixTools/IP filters
There are 21 PixTools/IP filters each performing a different image processing task. All filters have some properties and methods in common. In addition, there are individual properties and methods associated with most filters. Note Filters whose name begins with binary only operate on binary images. To process color images with these filters, you can set up a filter list and convert the non-binary images to binary images before running the binary filters. The PixTools/IP filters are: Filter object BlackOverscanRemoval BinaryBarcodeDetectionV2 BinaryBlankPageDetection BinaryBorderRemoval BinaryDilation Description Deletes the black border around an image. Detects standard barcodes, including PDF 417 and Datamatrix barcodes. Detects blank pages. Removes black edges that sometimes appear around an image during scanning or photocopying. Expands the area of black objects in an image which can improve image quality and legibility of text.

Chapter 2 What is PixTools/IP?

Filter object BinaryErosion BinaryHalftoneRemoval BinaryHoleRemoval BinaryInvert BinaryLineRemoval BinaryNoiseRemoval

Description Trims the area of black objects. Removes the background from an image or a graphics object on an image. Removes punch holes from the edges of an image. Inverts an image to its negative equivalent. Removes lines from or reconstructs lines on a form-based image. Removes noise from an image (despeckling). Noise can be picked up from carbon or dirt particles found in scanners, fax machines, or copiers. Detects and decodes patch codes on scanned images. Resizes an image while preserving the original aspect ratio. Reduces black objects in an image to one pixel thick skeletonized versions. Removes bumps and spurs that appear on text characters or graphic objects in an image. Detects the amount of color in an image. Removes specified color(s) from a color image. Sets image margins and removes white space around an image, including color images. Straightens binary and color images that shows a slant from its correct orientation. Performs image rotation in 90 degree increments on an image, including color images. Converts a 24-bit color image to a binary image. Detects standard barcodes. This filter has been included for backward compatibility. We strongly recommended that you use the BinaryBarcodeDetectionV2 filter instead.

BinaryPatchcodeDetection BinaryScaling BinarySkeleton BinarySmoothing ColorContentDetection ColorDropout Crop Deskew Rotation Threshold BinaryBarcodeDetection

PixTools/IP Overview

Filter object BinaryCrop

Description Sets image margins and removes white space around a binary image. This filter has been included for backward compatibility. We strongly recommended that you use the Crop filter instead. Not available under the .NET Framework.

BinaryDeskew

Straightens binary images that shows a slant from its correct orientation. This filter has been included for backward compatibility. We strongly recommended that you use the Deskew filter instead. Not available under the .NET Framework.

BinaryRotation

Performs image rotation in 90 degree increments on binary images. This filter has been included for backward compatibility. We strongly recommended that you use the Rotation filter instead. Not available under the .NET Framework.

Each filter has its own properties and methods. In addition, the following properties and methods are available and common to all filters: ModifiesImage This method indicates whether this filter modifies the image. Name This property stores a static string that can be used as an identifier for each filter type. Run This method executes the filter. Processes an image and returns the modified image. In the .NET Framework, Run is an overloaded method encompassing the functionality of the RunEx method (detailed below) that allows you to call the method with different parameter lists. RunEx Similar to the Run method, but RunEx allows you to set a flags parameter. If the flags parameter is set to runflagNone, the RunEx operates like the Run method. If the flags parameter is set to runflagAllowModify, the filter may process the image faster, but the source image may be destroyed during processing. This method is not available in the .NET Framework. Region This property specifies the image region to operate on.

Chapter 2 What is PixTools/IP?

Clone This property allows filters to be duplicated. It returns a new filter object that is an exact duplicate of this filter. This property has been replaced by the Clone function in the .NET Framework. ProcessedColorFormat This property tells a client the type of output to expect for a given input. PreferredColorFormat This property tells a client the ideal input type. State This property returns or sets all of the configurable properties on a filter. This property has been replaced by the State_Get and State_Set functions in the .NET Framework. CreateNativeImage This method returns an empty image in the preferred format for this filter. UserStorage Allows you to store information, such as comments about the filter. The information contained in this property is included when you serialize your filter object. UserMemory Allows you to store information, such as object, images, and comments (text strings) about the filter. The information contained in this property is not included when you serialize your filter object. CanProcessColorFormat Allows you to check whether or not a filter can process color. This method is available for use only in the .NET Framework.

ImageFilters object
The ImageFilters object was designed to simplify the handling of multiple filters to be used on the same image. For example, you might want to deskew, remove noise, remove borders, and halftone the same page. Rather than setting up the four filters separately and making sure that the data is propagated in the correct order, you can use the ImageFilters object to manage the group as a filter list. The ImageFilters object organizes its component filters in the order they are to be applied to the image data. Item This property returns the filter at a specified index location in the filter list. Add, Remove, and RemoveAll (Clear) These methods add, remove, and reorder filters in the list. The Clear method replaces the RemoveAll method in the .NET Framework. ModifiesImage This method indicates whether this set of filters modifies the image.

PixTools/IP Overview
Name This property stores a static string that can be used as an identifier for each filter type. For an ImageFilters object, this property returns collection. Run This method executes the filter. Processes an image and returns the modified image. In the .NET Framework, Run is an overloaded method encompassing the functionality of the RunEx method (detailed below) that allows you to call the method with different parameter lists. RunEx Similar to the Run method, but RunEx allows you to set a flags parameter. If the flags parameter is set to runflagNone, the RunEx operates like the Run method. If the flags parameter is set to runflagAllowModify, the filter may process the image faster, but the source image may be destroyed during processing. This method is not available in the .NET Framework. _NewEnum This property gets an enumeration object. This property is not available in the .NET Framework. Count This property returns the number of filters in the filter list. Region This property specifies the image region to operate on. Clone This property allows filters to be duplicated. It returns a new ImageFilters object that is an exact duplicate of this filter list. This property has been replaced by the Clone function in the .NET Framework. ProcessedColorFormat This property tells a client the type of output to expect for a given input. ColorConversionMode This property tells the filter list what to do when an image has a color format incompatible with a filter in the list. PreferredColorFormat This property tells a client the ideal input type. State This property of the filter list remembers the count and order of the filters in the list, as well as the values of all setable properties for each individual filter. This property has been replaced by the State_Get and State_Set functions in the .NET Framework. CreateNativeImage This method returns an empty image in the preferred format for this filter list. CanProcessColorFormat Allows you to check whether or not a filter can process color. This method is available for use only in the .NET Framework.

10

Chapter 2 What is PixTools/IP?

BarcodeResult object
The BarcodeResult object contains information about one detected barcode. The information includes the position on the image where the barcode was found, its type or symbology, and the text associated with that barcode symbol. Text This property returns the text of the barcode found. Type This property contains the barcode type or symbology and the recognized text or data contained in the barcode. Left This property holds the barcode position. This property has been replaced by Rectangle property in the .NET Framework. Top This property holds the barcode position. This property has been replaced by Rectangle property in the .NET Framework. Width This property returns the width of the barcode found. This property has been replaced by Rectangle property in the .NET Framework. Height This property returns the height of the barcode found. This property has been replaced by Rectangle property in the .NET Framework. Rectangle (.NET Framework only) This property returns the horizontal and vertical offset, width and height of the barcode found.

Result object
The Result object contains information returned by a filter. Value This property returns a value indicating the results returned by a filter. Key This property indicates the type of result for the Value property. Source This property returns the filter that added the result to the Result object. (This property is not available in the .NET Framework.)

Regions
Regions enable you to specify a sub-area on the page to which the filter will be applied. You may want to use regions to increase performance and processing accuracy or if you only want to use the filter on a part of the image. For example, using a region with the BinaryBarcodeDetectionV2 filter

11

PixTools/IP Overview

will reduce barcode search time. In the .NET Framework, the region is called the ImageRegion. In COM, the region is called the IRegion interface. Top, Left, Height, and Width These properties specify the region location and its dimensions. Enabled This property enables you to turn a region on or off when used with a filter. For example, if you are processing a batch of pages where the use of a region is appropriate for some but not all of the pages, then you can define the region once, and enable and disable it as needed. (This property is not available in the .NET Framework.) The PixTools/IP filters support the use of regions through the Region property. The filters that support the Region property include: BinaryBarcodeDetectionV2 BinaryDilation BinaryErosion BinaryHalftoneRemoval BinaryInvert BinaryLineRemoval BinaryNoiseRemoval BinarySkeleton BinarySmoothing

12

3
Using PixTools/IP
PixTools/IP is a set of either Common Language Runtime (CLR) classes (Microsoft .NET framework) or OLE Component Object Model (COM) objects (Microsoft Visual Basic, C++, and C) that can be incorporated into your application to perform image processing tasks. The CLR classes and the COM objects provide a set of image processing filters and auxiliary objects each with its own properties and methods. Each PixTools/IP filter performs one common image processing task such as deskewing, noise removal, or barcode detection. The auxiliary objects define helpful implementations such as regions and lists of filters. You can use PixTools/IP as a stand-alone toolkit, or you may use it in conjunction with other toolkits in the PixTools family, PixTools/Scan, PixTools/View, and PixTools/EZ. For users of other PixTools toolkits, PixTools/IP can be easily integrated into ISIS-compatible applications or programs that utilize ISIS Pipes technology. The basic steps in performing image processing are quite simple: 1 Set up the filter(s) you want to use with the desired parameters. 2 Obtain one or more images as input data, then process the pages. 3 Output the processed image data to its destination, such as a display screen, hard disk, or another software component such as an OCR engine or document management system. To set up filters and auxiliary objects with the proper parameters, use the properties and methods associated with each object. Important Because each user has different requirements for image processing and because processing jobs can involve many different document types, it is impossible to define or recommend an optimal set of parameters for each filter. Although PixTools/IP uses reasonable default values for the properties of each filter and auxiliary object, you should test

13

PixTools/IP Overview

with sample documents that approximate your working environment in order to determine the parameter settings best suited for your needs.

System requirements
The PixTools/IP toolkit has the following system requirements: A personal computer running Microsoft Windows 98, NT 4.0, Me, XP, or 2000. Adequate memory and disk space to support your development environment, plus 19 MB free space for the toolkit. A compatible development systems, such as one of the following: Microsoft Visual Studio .NET (for development using the PixTools/IP CLR classes) Microsoft Visual Basic version 6.0 or Microsoft Visual Studio 6.0 (for development using the PixTools/IP COM object)

Using PixTools/IP with Visual Studio.NET

You can access the PixTools/IP filters and auxiliary objects by adding two DLLs to your development system. These DLLs provide the development interface that you will use to create document imaging applications. Important When using the PixTools/EZ toolkit in the .NET Framework, do not use any PixTools/EZ COM components listed under the Customize Toolbox dialog's COM Components tab. Instead, use the .NET Framework componentslisted on the .NET Framework Components tabthat have been written specifically for the PixTools/EZ toolkit. PixTools/IP filters and objects are declared using the DIM command in the same way as standard Visual Basic objects, such as:
Dim Noise As New PixTools.IP.BinaryNoiseRemoval Dim FilterList As New PixTools.IP.ImageFilters Dim Region As PixTools.IP.ImageRegion

For C#, filters and objects are declared using different syntax, such as
PixTools.IP.BinaryNoiseRemoval Noise = New PixTools.IP.BinaryNoiseRemoval(); PixTools.IP.ImageFilters FilterList = New PixTools.IP.ImageFilters; PixTools.IP.ImageRegion Region;

14

Chapter 3 Using PixTools/IP

To access the properties and methods of an object: 1 In Visual Studio.NET, create a new project. 2 Choose either C# or Visual Basic. 3 Name your project. 4 Select Add Reference from the Project menu. The Add Reference dialog appears. 5 Click the Browse button and maneuver to the <INSDIR>\PIXTRAN\bin directory. 6 Select both PixTools.dll and PixTools.IP.dll. 7 Click the Open button. Both files should now appear in the Selected Components list on the Add Reference dialog. 8 Click the OK button to accept the addition of the two new references.

Using custom permissions files with Visual Studio.NET

If you create your custom permissions files using the Permissions Wizard during your development process, you should place the permissions files in your <WINDIR>\PIXTRAN directory while you are still actively testing and compiling your application from within Visual Studio.NET. Once you are ready to distribute your application, you should install the custom permissions files into the executable directory for your application on your users hard disk. For more information on the permissions control mechanism, the Permissions Wizard, and custom permissions files, please refer to Permissions on page 23.

Using PixTools/IP with Visual Basic

You can access the PixTools/IP filters and auxiliary objects like you would any other COM object in the Visual Basic development environment. Note Because the objects are not OCX controls, they cannot be dropped onto forms, they cannot draw themselves at run time, and they cannot be configured at design time with the property list or with property pages. Instead, they must be declared in and manipulated from your application code. PixTools/IP filters and objects are declared in the same way as standard Visual Basic objects with the DIM command, such as:
Dim Noise As New BinaryNoiseRemoval Dim FilterList As New ImageFilters Dim Region As IRegion

15

PixTools/IP Overview

To access the properties and methods of an object: 1 In Visual Basic, choose References from the Project menu to add the IP2 Library. The References dialog box appears. From the Available References list, select PixIP2 1.0 Type Library and click OK. 2 Declare a variable of that object type and instantiate it. This is done with the NEW command as shown in the DIM command example above. 3 After an object is created, access its properties and methods through the variable name (Noise, FilterList, and Region). For example:
Noise.MaxAreaPercent = 100 Call FilterList.Add(Noise, 1) IsEnabled = Region.Enabled

Because the Visual Basic development environment takes care of much of the necessary programmatic interactions with COM objects, you do not need to worry about implementing reference counting or other such COM paradigms when working with PixTools/IP filters and objects.

Using custom permissions files with Visual Basic

If you create your custom permissions files using the Permissions Wizard during your development process, you should place the permissions files in your <WINDIR>\PIXTRAN directory while you are still actively testing and compiling your application from within Visual Basic. Once you are ready to distribute your application, you should install the custom permissions files into the executable directory for your application on your users hard disk. For more information on the permissions control mechanism, the Permissions Wizard, and custom permissions files, please refer to Permissions on page 23.

Using PixTools/IP with C++

All of the C++ code samples included in the toolkit use syntax provided by a Microsoft extension available in Microsoft Developer Studio. This extension allows COM object properties and methods to be accessed like their Visual Basic counterparts. You do not have to use this extension or this syntax format to use PixTools/IP. This format was chosen for the toolkit sample code to maximize simplicity and clarity of presentation. All applications that use COM objects must initialize the Component Object library at the start of the program and uninitialize it at the end:
CoInitialize(NULL); CoUninitialize();

Each CoInitialize call must be matched with exactly one CoUninitialize call.

16

Chapter 3 Using PixTools/IP

Developing with the Microsoft extension

Once the Component Object library has been initialized, you can start to declare and instantiate PixTools/IP filters and objects. To instantiate an object: 1. 2. 3. Add #import <PixIP2.tlb> to the beginning of your code. Declare the object:
IBinaryNoiseRemovalPtr Noise;

Call the CreateInstance method with the class ID of the object. The class ID for PixTools/IP objects is the same as the name of the object.
Noise.CreateInstance(_uuidof(BinaryNoiseRemoval));

4.

Once the object you wish to use has been instantiated, you can access its properties and methods. You can access object properties directly:
MaxArea = Noise->MaxAreaPercent; Region->Enabled = 1;

5.

To call methods use:

FilterList->Add(Noise, 1);

Note You must use Try/Catch blocks to catch C++ exceptions which will be thrown if there is an error.

Developing without the Microsoft extension

Once the Component Object library has been initialized, you can start to declare and instantiate PixTools/IP filters and objects. To instantiate an object: 1. 2. 3. 4. 5. 6. Add #define CINTERFACE. Add #define COBJMACROS. Add #include <ip2.h>. Add #include <ip2_i.c>. Declare the object:
IBinaryNoiseRemoval *lpNoise;.

Call the CoCreateInstance function and specify the interface for the object as well as its class ID. The interface name for PixTools/IP objects is the name of the object prepended with the letter I.
CoCreateInstance(CLSID_BinaryNoiseRemoval, NULL, CLSCTX_INPROC, IID_IBinaryNoiseRemoval, (void **)&lpNoise);

17

PixTools/IP Overview

7.

Once the object you wish to use has been instantiated, you can access its properties and methods by doing one of the following: Using standard C++ syntax:
Noise->get_MaxAreaPercent(&MaxArea); Region->put_Enabled(1); FilterList->Add(lpNoise, 1);

Using the standard C syntax and specify the object as the first parameter of each function:
IBinaryNoiseRemoval_get_MaxAreaPercent(lpRegion, &MaxArea); IRegion_put_Enabled(lpRegion, 1); IFilterList_Add(FilterList, lpNoise, 1);

Errors are reported as HRESULT return values.

Using PixTools/IP with C

All applications that use COM objects must initialize the Component Object library at the start of the program and uninitialize it at the end. This initialization is included in the following helper functions in IP2CHelp:
IP2CHelpInitialize(); IP2CHelpDone();

Each IP2CHelpInitialize call must be matched with exactly one IP2CHelpDone. Once the Component Object library has been initialized, you can start to declare and instantiate the objects you want to use. To instantiate an object: 1. 2. 3. 4. 5. Add #include <ip2.h> to the beginning of your code. Add #include <ip2chelp.h> to the beginning of your code. Add ip2chelp.c to your project. Declare an interface pointer to the object, as in the following example:
LPIMAGEFILTER lpBarcode;

Call the CreateFilter() function, as in the following example:

CreateFilter(BinaryBarcodeDetectionV2, &lpBarcode);

Once the objects have been instantiated, they are ready to be used. To destroy a filter, call the following function:
DestroyFilter(lpBarcode);

Because the C language does not use an object-oriented paradigm, all of the C language versions of toolkit functions are associated with object classes rather than a particular instantiated object. Access to object class properties and methods is provided through their interfaces, and the specific

18

Chapter 3 Using PixTools/IP

instantiated object to which each function call is to be applied is specified in the first parameter to the function. Each function begins with the name of the object class interface followed by either the name of the method, or either _get_ or _put_ and the name of the property:
IImageFilters_Add(lpFilterList, lpNoise, 1); IBinaryNoiseRemoval_get_MaxAreaPercent(lpNoise, &iMaxArea); IRegion_put_Enabled(lpRegion, 1);

All PixTools/IP functions return errors and other result codes through the HRESULT return value.

Using PixTools/IP with PixTools/EZ

The Image property of the PixEzImage control is used to obtain an image object. Calling the Run method tells the filter or filter list to process the image and return the resulting image data. The resulting image can be assigned to the Image property of the PixEzImage control to replace the current page in the PixEzImage control. The image can also be used in a call to the ScanFromImage method of the PixEzImage control to create or add to the current document in the PixEzImage control. The following example shows how to get a page of image data from a PixEzImage control, process it using the noise removal filter, and then replace the page in the control for display:
Private Sub ProcessImageWithFilter(ez As PixEzImage, filter As Object) Dim image As IImage ' Get the image Set image = ez.image ' Process Image Set image = filter.Run(image) ' Put the processed image back into the EZ Set ez.image = image End Sub

Image processing during a batch scan

To set up image processing during a batch scan using PixTools/EZ: 1. 2. Declare and instantiate an ImageFilters object. Use the following during a ScanBatchControl Event:
Set EZImage.Image = FilterList.Run(EZImage.Image)

For an example of image processing during a batch scan, see the IPDuringScanVB sample in the Guide to Samples installed with the PixTools/IP toolkit.

19

PixTools/IP Overview

Using PixTools/IP with PixTools/Scan and PixTools/View

You can add image processing capabilities to your PixTools/Scan and PixTools/View applications in two ways: by loading, initializing, and linking pixip2.pxn as you would any ISIS driver (typically by using AutoPipe) or by using the LoadSourceDriver and LoadTargetDriver methods of the PixTools/IP IImage interface.

Using pixip2.pxn as an ISIS driver

To manually add image processing to your application using pixip2.pxn: 1. 2. 3. 4. 5. 6. Load pixip2.pxn. Initialize pixip2.pxn. Create an ImageFilters object. Add and configure filters in the list. Call the following function:
PixTagSetLong(lpDriver, TAG_IPIXIPFILTERLIST2, 0, lpImageFilters);

Link pixip2.pxn. Note The application or the user can change the filter list and/or the configuration of filters that are included in the list at any time images are not being scanned, without unlinking or unloading pixip2.pxn. The new filter list takes effect immediately.

Using AutoPipe to link to an ISIS pipe

The easiest way to integrate image processing into an application that also uses one or both of the PixTools/Scan and PixTools/View toolkits is to use AutoPipe. To integrate image processing using AutoPipe: 1. 2. Specify the filter list to use in the TagListStruct structure with
TAG_IPIXIPFILTERLIST2.

Call PixAutoPipeIsis to get the ISIS pipe. Note If you change your filter list, you must call AutoPipe again, unless you know that the output type (binary or color) has not changed.

3.

Load and initialize the pipe.

The following example shows how to set up image processing during a single-page scan using AutoPipe. It demonstrates how to get data from a scanner to the image processing driver. However, you can always substitute another image source driver, such as F_PIXIF if you are reading the

20

Chapter 3 Using PixTools/IP

image from a file, or FROMPIXM if you are getting data out of the PixTools/View main library. This example is included in the IPDuringScanC sample of the Guide to Samples installed with the toolkit.
/* /* /* /* /* Assume that ImageFilters *lpFilterList has already been declared, instantiated, and configured elsewhere. Also assume that a scanner driver, pPipe, has already been loaded and initialized. The resulting image will be returned in LPIMAGE. */ */ */ */ */

HRESULT ProcessPipeIsis(PixDrvHandlePtr pPipe, LPIMAGEFILTERS lpFilterList, LPIMAGE *pImage) { INT32 IsisError = S_OK; char szIsisPipe[128]; /*The contents of the pipe needed to convert data to the requested format */ PixDrvHandle hIsisPipe;/*A handle to the pipe */ char bufData[8192]; struct TagListStruct OutputTags = {1, { TAG_IPIXIPFILTERLIST2, (long)lpFilterList}}; /* We want the image to be processed with lpFilterList */ /* Clear the handle */ PixDrvInitHandle(&hIsisPipe); /* Use autopipe to generate the pipe needed to process the image */ IsisError = PixAutoPipeIsis(pPipe, &OutputTags, szIsisPipe); if (IsisError < 0) goto error_handler; /* Load and initialize the pipe */ IsisError = PixDrvLoadInitPipe(NULL, szIsisPipe, &hIsisPipe, 0); if (IsisError < 0) goto error_handler; /* Link the driver at the end of the pipe */ IsisError = PixDrvAppend(pPipe, &hIsisPipe); if (IsisError < 0) goto error_handler; /* Process a page */ IsisError = PixRunZone(pPipe, bufData, sizeof bufData); ImageFromPipe(pPipe, pImage);

21

PixTools/IP Overview

/* Remove the added driver */ PixDrvChopBeforeDriver(pPipe, &hIsisPipe); if (IsisError) goto error_handler; error_handler: if (PixDrvLoaded(&hIsisPipe)) { /* Unload the pipe */ PixDrvUnloadPipe(&hIsisPipe); } return IsisError; }

Using ImageFilters
You can control the ImageFilters State by using a configure dialog or by restoring a previously saved state. You can access the saved state of a filter list using the ImageFilters object. To save a state: 1. Configure a filter list exactly as you want it to be used. You can do this by using the ImageFilters object to add filters to the list. For an example, see the Guide to Samples installed with PixTools/IP toolkit. Make sure each filter you include in the filter list is configured as desired. Call the following function to retrieve the state:
IImageFilters_get_State(filterlist, &bstrState);

2. 3.

Store bstrState. The typical places to store configuration information such as this is either in an .ini file or the system registry.

Examples for restoring a state are included in the IPListStateC, IPListStateCPP, IPListStateVB, IPListStateCS, and IPListStateVBNET samples in the Guide to Samples installed with the PixTools/IP toolkit.

22

4
Permissions
PixTools toolkits use a permissions control mechanism to enforce licensing. This mechanism prevents the toolkit and applications built with the toolkit from operating with components for which they are not licensed. In addition to enforcing your license agreement, the permissions control mechanism also helps to prevent unauthorized third-party applications from using the PixTools libraries that are a part of your application. Important The right to use PixTools development toolkits is granted by license agreement. Furthermore, the right to distribute an application based on PixTools libraries requires that you execute a redistribution license agreement and, in general, pay royalties based on the number of copies you ship. Before beginning application development, be sure that you understand the licensing requirements.

Licensing
PixTools/IP redistributable libraries are supplied under a license agreement with Pixel Translations, and may be distributed only in accordance with the specifications and details of that license agreement. Certain tools and components of the toolkit are supplied for application development only and may not be distributed to end users under any circumstances. Pixel Translations offers a variety of ways to pay for runtime licenses, each designed to meet different distribution methods. Contact Pixel Translations for more information on how to setup a redistribution agreement.

23

PixTools/IP Overview

Starting early
Although it is easy to add the permissions control mechanism to your application, it does require that you contact Pixel Translations to obtain additional licensing information not included with the toolkit. In order to provide a smooth transition for your application from development to distribution, we recommend that you implement permissions control for your application at the start of the development process rather than just before you are ready to ship your program.

How permissions control works

Every application which uses PixTools toolkit components must be accompanied by at least one permissions file. A permissions file tells the PixTools libraries what toolkit functionality your application has licensed. Without a valid permissions file, the PixTools libraries may load but will not otherwise function, and the application will fail. PixTools permissions files have the extension .CHN. The PixTools/IP libraries check which features have been licensed for a program by searching in the application executable directory for all valid permissions files. The application executable directory is the directory in which you have installed the executable or EXE file for your application. Each permissions file is designed to unlock a specific set of features. If there are multiple permissions files in the application executable directory, their contents are combined so that all applicable permissions in all permissions files take effect. When the PixTools libraries check permissions (for example, when a PixTools/IP filter is loaded), every file having a .CHN extension that can be found is loaded. The libraries look through the permissions files, find the ones that were made for your company, and load those permissions. In summary, the permissions control mechanism is designed to do the following: Check an applications permissions when loading a driver or a library component to make sure that the application has the right to access that driver or component. Ensure that you have a valid license agreement in place.

Permissions files included with the toolkit

When you distribute your application, it must be shipped with a custom permissions file that is keyed specifically to your company. To create the custom permissions file, you must have a redistribution agreement in place with Pixel Translations. However, you will probably want to compile and test your program throughout the development cycle before you are ready to ship and before the agreement is set up. To make this part of the development process easier for you, PixTools/IP includes a special development-only permissions file, DEV2IP.CHN, in your <WINDIR>\PIXTRAN directory. The DEV2IP.CHN file allows you to run and test your application during the development process without having to create a custom permissions file first. When you

24

Chapter 4 Permissions

use DEV2IP.CHN to run your program, a friendly notification dialog will display once a day to remind you that you must create your own custom permissions file before distributing your application. Important Under no circumstances may you redistribute DEV2IP.CHN. Although the development-only permissions files are included for your convenience, we recommend that you implement permissions control and contact Pixel Translations to setup a redistribution agreement as soon as it is reasonable during your development process.

Implementing permissions control

Implementing permissions control is a two step process, which includes creating your own custom permissions files and registering your application.

Creating your custom permissions files

To create your own custom permissions files, follow these steps: 1 Contact Pixel Translations to obtain licensing information and to obtain a Customer ID and a Customer Key. Make careful note of this data and keep it in a safe place. You will use this information to create your custom permissions file for this and future update versions of the toolkit. Run MAKEPERM.EXE. This is a utility program provided with PixTools/IP. You can run it by choosing Permissions Wizard from the Utilities folder inside the PixTools Products program group. Note The MAKEPERM program will delete all .CHN files beginning with DEV2 in your <WINDIR>\PIXTRAN directory after the custom permissions files are created. If you wish to save these files for future development only use, you should copy them to another location before running MAKEPERM. You should not copy them to the <SYSDIR> directory, your applications build directory, or anywhere else in the system path.

25

PixTools/IP Overview

When you run MAKEPERM, the Create A Permissions File dialog appears:

In the upper edit box, enter the Customer ID that was issued by Pixel Translations. Note This entry is case-sensitive, so be careful to capitalize the entry exactly as it was given to you.

4 5 6

In the lower edit box, enter the Customer Key number that was issued by Pixel Translations. (Optional) Click Info to display a list of products for which you are licensed. If you are using the PixTools/Scan toolkit, select the following options, as necessary from the Scanner group box: I wish to enable Level 1 scanners in my application This option enables your application to scan with Level 1 scanners. I wish to enable Level 2 scanners in my application This option enables your application to scan with Level 2 scanners. I wish to enable Level 3 scanners in my application This option enables your application to scan with Level 3 scanners. These options are unavailable if you have not installed the PixTools/Scan toolkit.

26

Chapter 4 Permissions

From the Image Processing group box, click Select to choose image processing options that correspond to the image processing support you have licensed. The Image Processing dialog appears.

Select from the following options and click OK: I wish to enable Binary Image Processing in my application This option enables binary image processing features available with the PixTools/IP toolkit. I wish to enable Standard Barcode detection in my application This option enables barcode detection functionality available with the PixTools/IP toolkit. I wish to enable Color Image Processing in my application This option enables the color image processing features, such as the ColorContentDetection, ColorDropout, Deskew, and Threshold filters, available with the PixTools/IP toolkit. I wish to enable PDF 417 Barcode detection in my application This option enables PDF 417 barcode detection functionality available with the PixTools/IP toolkit. I wish to enable DataMatrix Barcode detection in my application This option enables DataMatrix barcode detection functionality available with the PixTools/IP toolkit. Important Additional licenses are required to enable the PDF 417 and DataMatrix barcode detection options. The Create A Permission File dialog reappears.

Click Create Permissions.

27

PixTools/IP Overview

If you entered a valid Customer ID and corresponding Customer Key, a message similar to the following will appear:

The MAKEPERM program creates these files: File Name nnnnnnnn.CHN CUSTOMER.ID File Type Custom Permissions Files Company Registration Information File Locations
<WINDIR>\PIXTRAN PIXTRAN\BIN <SYSDIR> PIXTRAN\BIN

The nnnnnnnn placeholder is the Customer Key number you entered. The custom permissions files (nnnnnnn.CHN for 32-bit Windows) must be distributed with your application and installed in the users path. It is strongly recommended that you install the permissions files in the application executable directory. Important Your application will not function properly if it cannot find a valid permissions file. You can rename your custom permissions files if desired. It can have any name except it must have the CHN extension, and it must not match the filename root of any of your applications executable modules, including EXE and DLL files. The CUSTOMER.ID file is not needed for PixTools/IP. It is used with other PixTools toolkits. Important Under no circumstances are you allowed to distribute the MAKEPERM.EXE program or the CUSTOMER.ID file. Note If you are using Visual Basic and create your custom permissions files during your development process, you should place the permissions files in your <WINDIR>\PIXTRAN directory while you are still actively testing and compiling your application from within Visual Basic.

28

Chapter 4 Permissions

Once you are ready to distribute your application, you should install the custom permissions files into the executable directory for your application on your users hard disk.

Running MAKEPERM from the command line

The Permissions Wizard can be run from the command line. This option is provided for those developers who wish to include permissions file creation as part of their build process. The standard windowed version of the Permissions Wizard is much easier to use and is recommended for most users. The following PixTools/IP related parameters are used with the command line version of MAKEPERM.EXE: Parameter /I /K /1 /2 /3 /IP /IPCOLOR /BARCODE /DATAMATRIX /PDF417 /S Type Mandatory Mandatory Optional Optional Optional Optional Optional Optional Optional Optional Optional Description Customer ID (quote marks are required). Example: /I"My Customer ID" Customer Key (quote marks are required). Example: /K"1234567" Enable Level 1 scanners. Enable Level 2 scanners. Enable Level 3 scanners. Enable Binary Image Processing. Enable Color Image Processing. Enable Standard Barcode Detection. Enable DataMatrix Barcode Detection. Enable PDF 417 Barcode Detection. Comma-separated list of permission constants (quote marks are required). These are the constants used by the MAKECHW.EXE program which was read from a .LIC file. Example: /S"PERM1, PERM2" Do not display error message boxes if the permission creation process failed. Do not automatically launch the windowed version of the Permissions Wizard if the command line version failed.

/NOERR /NOWIN

Optional Optional

The following sample command line would enable the full range of PixTools/IP functionality, including barcode detection, and specify that error messages should not be displayed:
MAKEPERM /I"My Customer ID" /K"1234567" /IP /BARCODE /NOERR

29

PixTools/IP Overview

Registering your application

In order for your application to be recognized by PixTools/IP and associated with your custom permissions files, it must enable permissions and be properly registered with the toolkit. To do so, you must call one of the registration methods listed below at the beginning of your program, before you access any other PixTools/IP filters or objects. These methods identify your application to the PixTools/IP libraries by your Customer ID.

VB.NET:
PixTools.Permissions.Register("Your Customer ID")

Example:
Private Sub btnRegister_Click() PixTools.Permissions.Register("Your Customer ID") MsgBox "Your application is now registered" End Sub

C#:
PixTools.Permissions.Register("Your Customer ID")

Example:
private void btnRegister_Click() { PixTools.Permissions.Register ("Your Customer ID"); MessageBox.Show("Your applciation is now registered"); }

Note .NET applications do not require Register() to be called, but it is strongly recommended. The more complicated the application, the more likely it will have permissions issues once it is deployed.

Visual Basic:
RegistrationFunctions.Register "Your Customer ID"

Example:
Private Sub btnRegister_Click() RegistrationFunctions.Register "Your Customer ID" MsgBox "Your application is now registered" End Sub

C and C++:
PixRegister("Your Customer ID")

30

Chapter 4 Permissions

Example:
#include <pixdflt.h> #include <stdio.h> int main(int argc, char* argv[]) { PixRegister("Your Customer ID"); printf("Your application is now registered\n"); return 0; }

Important Make sure you use the same exact string, including capitalization, to register and to create your custom permissions files with MAKEPERM.

Registration for multiple toolkits

If you are using another PixTools toolkit in conjunction with PixTools/IP in your application, you only need to register your application once. You can do so either by calling one of the methods listed in Registering your application on page 30 or by calling the registration function in the other toolkit. You can call both, but make sure you use exactly the same Customer ID string for both calls and for creating your custom permissions files using MAKEPERM. For PixTools/IP .NET you do not need to add any code if the automatic registration described for PixTools/EZ .NET is working. Otherwise, you can call the PixTools.Permissions.Register method.

Distributing your custom permissions files

Once you have implemented permissions control in your application by registering your program and creating your custom permissions files, you must distribute the custom permissions files with your application. We recommend that you install the custom permissions files into the same directory as your applications executable file. Important You should always distribute the 32-bit permissions file, nnnnnnn.CHN, created by the Permissions Wizard.

31

PixTools/IP Overview

32

5
Distributing your finished application
Toolkit files to distribute
PixTools/EZ is supplied with a setup program that allows you to install merge modules (see Merge modules on page 36) or a flat directory tree of files (see Install locations and files to include when using the flat directory tree on page 39) to help you redistribute to your users when youre building your own installer. The directory for the installation of the redistribution tree is C:\PIXTRAN\REDIST.

Installing redistributable files using Install for Installer

To install redistributable files using Install for Installer: 1 2. 3. 4. Run the Setup program on the PixTools CDROM and choose Custom when prompted to choose a setup type. Click Next. The Custom Setup dialog box appears. From the directory tree, expand Install for Installer, and then click the X icon next to PixTools/IP to enable the PixTools/IP Installer feature. From the Install for Installer > PixTools/IP drop-down list, choose This feature, and all sub-

33

PixTools/IP Overview

features, will be installed on local hard drive.

5. 6. 7.

The icon next to PixTools/IP changes to indicate that the selected component has been enabled. Repeat Step 3 for each scanner driver you want to install, if necessary. Click Next. The Ready to Install the Program dialog box appears. Click Install to begin installation. When setup completes, the REDIST directory is created in your installation directory. The default installation directory is C:\PIXTRAN\REDIST. The installation directory contains merge modules and a flat diretory tree of files you need to distribute along with your application. Use this directory structure and its contents when designing your applications setup program.

34

Chapter 5 Distributing your finished application

Installing redistributable files by modifying the Installer

To install redistributable files after the toolkit has been installed: 1 Open the Windows Control Panel and run Add/Remove Programs. The Add/Remove Programs dialog box appears. If necessary, choose the Change or Remove Programs button in the upper left corner to view a dialog box similar to the one below.

2. 3. 4. 5.

Locate and select PixTools version (where version is the version number of the toolkit you are modifying), then click Change. The PixTools InstallShield Wizard appears. Click Next to proceed. The Program Maintenance dialog box appears: Choose Modify, and then click Next. The Customer Information dialog box appears, prompting you to enter a serial number: You do not need a serial number to install the flat directory structure for PixTools/IP. (You only need to enter a serial number if you will be adding components which were not previously licensed.) Click Next without entering a serial number to proceed. A directory tree containing the PixTools/IP Installer appears. Repeat steps 3 through 7 of Installing redistributable files using Install for Installer on page 33.

6.

35

PixTools/IP Overview

Merge modules
Important Merge modules are currently only available for PixTools/EZ .NET based or PixTools/IP .NET based applications. Merge modules (*.MSM files) are a prevalent and convenient way to install the files needed by an application that is based on a third-party technology. Merge modules can be added to Setup Projects in .NET and to InstallShield projects. The PixTools installer installs the merge module files in C:\PIXTRAN\REDIST\Merge Modules. When you create an installer for your application, you will add PixTools merge module(s) to your installation project. If you are using both EZ .NET and IP .NET in your products, we recommend that you use the single EZIPNET.MSM instead of EZNET.MSM and IPNET.MSM combined.
Toolkit MSM Filename When to use

EZ .NET IP .NET EZ .NET & IP .NET

EZNET.MSM IPNET.MSM EZIPNET.MSM

When deploying just EZ .NET based apps When deploying just IP.NET based apps When deploying apps that are both EZ .NET and IP .NET based

For merge modules containing PixTools .NET DLLs (currently IPNET.MSM, EZNET.MSM and EZIPNET.MSM), the merge modules need to be configured with an installation directory for the PixTools .NET DLLs. This directory must match the directory where the application itself is installed. See Using merge modules with a Visual Studio .NET Setup Project on page 36 and Using merge modules with InstallShield Developer or Express on page 37 for additional information on specifying the correct directory.

Using merge modules with a Visual Studio .NET Setup Project

When adding an executable to a Microsoft .NET Setup Project, dependencies will be checked and any PixTools*.dll used by the executable will be automatically added to the project. Because the PixTools merge modules also contain the PixTools*.dll files, warnings will be generated with the Setup Project is built. We recommend you exclude the detected dependencies by right clicking on the PixTools*.dll files and selecting Exclude. Please note that PixTools.EZ.SampleDialogs.DLL should not be excluded, as it is not in any merge modules. Some files included with the toolkit are not included in the merge modules, either because they are rarely used or because they were only provided to support legacy applications. If an application requires any of the files in the list, those files will need to be added manually to a setup project (PIXNOTEN.DLL, PIXDFLT.DLL, PIXPERM.DLL, PIXLOC.DLL, PIXTHK32.DLL, and PIXTHK16.DLL).

36

Chapter 5 Distributing your finished application

To install merge modules from within .NET, right-click on your setup project, and then choose Add> Merge Module. In the Add Modules dialog, locate C:\PIXTRAN\REDIST\Merge Modules, choose the desired merge module (.MSM), and then click Open. The table on page 36 provides the MSM file names and when they should be used. You can configure the merge module installation directory by setting the Module Retargatable Folder property in the merge modules Properties window. The directory must match where the application itself is installed, usually Application Folder.

Using merge modules with InstallShield Developer or Express

When adding PixTools merge modules that contain .NET components to an InstallShield project, a destination directory must be specified in of the Merge Modules Properties dialog. This is often [INSTALLDIR]. (For InstallShield Express, click the Destination tab. For InstallShield Developer, go to the General tab.) The PixTools .NET DLLs will be copied to the specified directory, so the directory must be the directory of the PixTools .NET based application that is being installed. If a directory is not specified, the PixTools .NET DLLs will be copied to the system volume root directory, typically C:\.

37

PixTools/IP Overview

Important Do not set the destination in the Configurable values tab when using InstallShield Express. Be sure to use the Destination tab as seen in the following image:

Under certain circumstances, when adding a merge module to an InstallShield Express project, InstallShield Express will add all merge modules in the directory, even though only a subset of the merge modules present was being added. To avoid this, move or change the extensions of unneeded merge modules in the \PIXTRAN\REDIST\Merge Modules\ folder before adding any of those merge modules to an InstallShield Express project.

38

Chapter 5 Distributing your finished application

Install locations and files to include when using the flat directory tree
Use the C:\PIXTRAN\REDIST directory structure and its contents when designing your applications setup program. Each directory in the flat tree structure corresponds to a directory on your users hard disk. The three primary install locations are the <SYSDIR> directory, the <WINDIR>\PIXTRAN directory, and the application executable directory. Your setup program should install all of the files in the flat tree structure (except for the Merge Modules directory). For more information on these directories and their corresponding install locations, please refer to the document Redistributing Pixel Files in the How to release your product folder of the PixTools Products program group. The name of the file is REDIST.TXT, and it can be found in the PIXTRAN\DOC directory. If you want to know why each file needs to be included, please refer to the document PIXTRAN\DOC\RTEZ.TXT. Important Please remember you also need to install the custom permissions files you created for your application. It is recommended that they be installed in the application executable directory. You should always distribute the 32-bit permissions file, nnnnnnn.CHN, created by the Permissions Wizard. If your application supports scanning in Windows 98 and above and you wish to support older scanners that do not have 32-bit drivers (.PXN), you should also distribute the 16-bit permissions file, nnnnnnn.CHW. This is because scanning with 16-bit drivers in Windows 98 and above takes place within the 16-bit sub-system and must receive permissions from a 16-bit permissions file.

Issues with other ISIS applications

Microsoft Windows supports dynamic linking, which means that multiple applications can access the same components. On the surface, this is a good idea and gives users many benefits. However, it causes lots of problems for application developers and support personnel. These problems are not unique to ISIS applicationsthey exist for all types of applications. For example, what if your application is being installed on a computer that already contains another ISIS application that is two years old? In this case, the following issues become very important: Where does the other application store its DLLs? Where does the other application store its ISIS drivers? Are these other locations in the users path?

39

PixTools/IP Overview

By carefully following our installation instructions for your application, many problems are alleviated. For example: Loading the wrong version of a library Using the wrong version of a library that has already been loaded by another application. Loading the wrong version of a driver. Using the wrong version of a driver that has already been loaded by another application. Overwriting a driver or other system component that is required by another application.

There are no perfect solutions to these problems. The best preventive measure involves installing your applications files to their own directory, installing all DLLs to the <SYSDIR> directory, and all ISIS drivers to <WINDIR>\PIXTRAN, and doing version checking for all files you install. Important PixTools/IP supports loading libraries only from <SYSDIR> and drivers from <WINDIR>\PIXTRAN. Be aware that older ISIS applications may not follow these rules.

40

Index
Symbols
.msm 36 .NET setup project 36 _NewEnum property 10

C
C++, Microsoft extension for 16 CanProcessColorFormat 9, 10 character dilation, filter for 6 character erosion, filter for 7 Clone property 9, 10 CLR 13 color detecting, filter for 7 removing, filter for 7 color content detection, filter for 7 ColorContentDetection filter 7 ColorConversionMode property 10 ColorDropout filter 7 COM 5, 13 conventions, documentation 3 Count property 10 CreateInstance method 17 CreateNativeImage method 9, 10 Crop filter 7 cropping margins, filter for 7 Customer ID 25 Customer Key 25 CUSTOMER.ID file 28

A
Add method 9 APPDIR placeholder 4 application distributing 33 executable directory 24 registering 30 AutoPipe, using with PixTools/IP 20

B
barcode detection filter for 6 object for detected barcode 11 BarcodeResult object 11 BinaryBarcodeDetectionV2 filter 6 BinaryBlankPageDetection filter 6 BinaryBorderRemoval filter 6 BinaryDilation filter 6 BinaryErosion filter 7 BinaryHalftoneRemoval filter 7 BinaryHoleRemoval filter 7 BinaryInvert filter 7 BinaryLineRemoval filter 7 BinaryNoiseRemoval filter 7 BinaryPatchcodeDetection filter 7 BinaryScaling filter 7 BinarySkeleton filter 7 BinarySmoothing filter 7 BlackOverscanRemoval filter 6 blank page detection, filter for 6 border removal, filter for 6

D
default directory for flat installation 34 default values 13 Deskew filter 7 deskewing, filter for 7 despeckling, filter for 7 DEV2.CHN file 24 dialogs Permission Wizard (MAKEPERM) 26 dilating characters, filter for 6 DIM command for Visual Basic 14, 15 distributing custom permissions files 31

41

PixTools/IP Overview

distributing your application 33 document conventions 3

L
Left property 11, 12 license agreement 5, 23 licensing 23 line removal, filter for 7

E
Enabled property 12 eroding characters, filter for 7

M F
F_PIXIF driver 20 files to include when distributing an application 33 filter lists 9 filters, list of 6 flat toolkit installation 33 FROMPIXM driver 21 MAKEPERM program running from the command line 29 using 25 margin cropping, filter for 7 merge modules 36 methods Add 9 CreateInstance 17 CreateNativeImage 9, 10 ModifiesImage 8, 9 Remove 9 RemoveAll 9 Run 8, 10 RunEx 8, 10 Microsoft extension for C++ 16 ModifiesImage method 8, 9

H
halftone removal, filter for 7 Height property 11, 12 helper functions IP2CHelpDone 18 IP2CHelpInitialize 18 hole removal, filter for 7

I
image rotation, filter for 7 ImageFilters object 9 Install for Installer 33 installation installing toolkit to build an installer 33 installation directory, default for flat installation 34 installer, modifying 35 InstallShield Developer 37 InstallShield Express 37 inverting, filter for 7 IP2CHelp 18 ISIS drivers 5 ISIS Pipes technology 5, 13 ISIS Pipes technology 5, 13 Item property 9

N
Name property 8, 10 NEW command for Visual Basic 16 noise removal, filter for 7

O
objects BarcodeResult 11 ImageFilters 9 Result 11 overscan removal filter for 6

P
patch code detection, filter for 7 PDF 417 barcode detection, filter for 6 permissions application executable directory 24 distributing custom permissions files 31 issues with other ISIS applications 39

K
Key property 11

42

Index

registering your application 30 registration for multiple toolkits 31 using with Visual Basic 16 permissions file creating 25 discussed 24 included with toolkit 24 Permissions Wizard running from the command line 29 using 25 PixTools/EZ discussed 2 using PixTools/IP with 19 PixTools/Image Processing See PixTools/IP PixTools/IP auxiliary objects 6 discussed 5 filter list object 9 filters 6 PixTools/Scan discussed 3 using with PixTools/IP 20 PixTools/View discussed 3 using with PixTools/IP 20 PreferredColorFormat property 9, 10 ProcessedColorFormat property 9, 10 properties _NewEnum 10 Clone 9, 10 ColorConversionMode 10 Count 10 Enabled 12 Height 11, 12 Item 9 Key 11 Left 11, 12 Name 8, 10 PreferredColorFormat 9, 10 ProcessedColorFormat 9, 10 Region 8, 12 Source 11 State, IImageFilter interface 9 State, ImageFilters object 10 Text 11 Top 11, 12

Type 11 Value 11 Width 11, 12

R
Rectangle property 11 REDIST.TXT file 39 redistributable file, installing 33 redistributable files 33 redistribution agreement 5, 23 Region property 8, 12 Register() 30 registering your application 30 Remove method 9 RemoveAll method 9 removing borders, filter for 6 color, filter for 7 halftones, filter for 7 lines, filter for 7 noise, filter for 7 punch holes, filter for 7 requirements 14 resizing, filter for 7 Result object 11 Rotation filter 7 rotation, filter for 7 Run method IImageFilter interface 8 ImageFilters object 10 RunEx method IImageFilter interface 8 ImageFilter interface 10

S
scaling, filter for 7 skeletonization, filter for 7 smoothing, filter for 7 Source property 11 standard directories 4 State property IImageFilter interface 9 ImageFilters object 10 SYSDIR placeholder 4 system requirements 14

43

PixTools/IP Overview

T
TAG_IPIXIPFILTERLIST 20 TagListStruct structure 20 Text property 11 Threshold filter 7 thresholding, filter for 7 Top property 11, 12 Type property 11

V
Value property 11 Visual Basic DIM command 14, 15 NEW command 16 using PixTools/IP with 15 using with custom permissions files 16 Visual Basic.NET 15 Visual Studio.NET Using PixTools/IP with 14

U
UserMemory 9 UserStorage 9

W
Width property 11, 12 WINDIR placeholder 4

44