Capture Image Clips under Solution Control

The solution program has full control on all aspects of the capture process – clip definition/storage, timing, organization, transformation and destination.

Your solution uses the IClipHelper interface to capture clips off the current sheet during scanning events. The ScanEventArgs.ClipHelper property is the programmatic hub for capture related operations. Note that exactly one clip is appended to the specified clip destination per call to a capture method.

How to choose the clip capture/graybox evaluation method to suit your need:

1. Do you want to write the captured image to a file immediately?

• If not, go to step 2.
• If yes, use one of the WriteClipToFile overloads per the following table:

2. Do you want to request a new stream object with the captured clip?

• If not, go to step 4.
• If yes, use one of the GetClipAsStream overloads per the following table:

3. Do you want to write the captured image to a file immediately?

• If not, go to step 2.
• If yes, use one of the WriteClipToFile overloads per the following table:

4. Do you want to request a new Clip object? To display the clip, build a collection of clips and/or write it to a file/stream at a later time?

• If not, go to step 5.
• If yes, use one of the GetClip overloads per the following table:

5. Do you want to write the captured image to a file immediately?

• If not, go to step 2.
• If yes, use one of the WriteClipToFile overloads per the following table:

Input of Clip metadata

Create and populate a ClipRegion or ClipAttributes structure to specify the clip. This process accomplishes the same results as using the Clip Attributes dialog in the ScanTools Plus application. Scripting clients that do not have the concept of a structure may find it difficult or unable to use either the ClipRegion or ClipAttribute based methods.

Clip Region

Use ClipRegion-based methods if you do not intend to deviate from the sheet-level application definition settings i.e. all clips for a sheet share the same attributes as the sheet. You will typically use ClipRegion if the only clip attributes that vary for your situation is the clip location and size.

Declare a ClipRegion structure

Populate the structure using location and size known to you. To obtain a full page image, only specify the side; set all other members to 0. The capture method will populate these members upon return.

Clip Attributes

Use ClipAttributes-based methods if you have set different attributes for different clips within the application definition and want to reuse these settings instead of the sheet-level settings. Methods that take the ClipAttributes structure as an input overwrite these properties and these values stay in effect until another such call or the next FormIdentified event. It is also possible to directly write to these properties.

After you decide to use ClipAttributes, at least two choices follow: load settings from the Data Services CLIPS schema rowset or create a new set of values. Another variation is where you load from the CLIPS schema rowset but override a value or two say CombineWithForm.

Declare a ClipAttributes structure

1. Specify the coordinate system/units – ClipCoordinateSpace and UnitOfMeasure
2. Populate its ClipRegion member using location and size known to you. To obtain a full page image, only specify the side; set all other members to 0. The capture method will populate these members upon return.
3. Specify a valid combination of bit depth and compression – ClipDepth and CompressionMethod
4. Qualify bitone clips – BitoneThresholdType and BitoneEdgeContrastEnhancement
5. Qualify manual bitone threshold type - ManualBitoneThreshold
6. Qualify grayscale clips - EnableBackgroundOffset and BackgroundOffset
7. Specify image transformation – ClipRotation and CombineWithForm
8. Specify information for solution use – Tag and Archive

CAUTION: Specify -1 or 0 for the members BitoneEdgeContrastEnhancement and EnableBackgroundOffset. These members are Booleans in spirit but unfortunately .Net marshals these as System.Int16.

For .Net code, see the handler for the ScanningManager’s Clip event in the Scanning Sample - .NET.

NOTE:For languages that can not handle a structure, ClipHelper also has the following methods available that provide the same functionality as the ClipAttributes structure:

• ClipHelper.GetClip3 method
• ClipHelper.GetClip4 method
• ClipHelper.WriteClipToFile3 method

Storage and Retrieval of Clip metadata

Typically your clips are defined in the ScanTools Plus application and thus reside in the .StxAppDef file. However, you can choose to define and store the metadata in an XML file or database as you like. This is possible because the storage and input of metadata are decoupled from each other. Metadata is presented to the IClipHelper clip capture methods at scan-time.

Use the CLIPS schema rowset to retrieve clip metadata from the application definition file. Create and populate a ClipAttributes structure with this information. You may choose to modify this information as needed before presentation to the IClipHelper clip capture methods.

Timing

In principle, clips may be captured at any of the following events although we recommend using only the Clip event:

Organization

You organize your clips the way you want – one file per document, one file per clip. Additionally, file names are specified by the solution program. Recall that the traditional ScanTools Plus capture method limits you to one file (master TIFF file) for the entire batch.

Single vs Multi-frame TIFF Layout

Single frame and multi-frame TIFF layouts are possible.

To build a single frame image, ensure that the stream you pass in is empty to begin with. Or call the GetClipAsStream or GetClipAsStream2 methods which will create new streams.

To build a multi-frame image, pass an empty stream when the capture of the first clip. To capture subsequent clips, pass the same stream without disturbing the stream pointer or contents.

Destination and Transformation

The IClipHelper interface offsers a greater choice of clip destinations than the traditional ScanTools Plus method. Primary destinations are IClip objects, unmanaged binary streams (IStream) and disk files. Final destinations obviously depend upon your solution needs and can include database columns, optical storage media and so on.

For maximum flexibility, we recommend capturing to IClip objects. These objects make available the clip image as a standard OLE Picture object as well as support saving the clip to a stream or file. Upon acquisition, IClip objects can outlive the scanning session and their object lifetime is entirely controlled by the solution.

Transformation means combining with the form background image and rotating the image from the scanned orientation. Tranformation is processor intensive and affects scanner and image transfer thruput. It also increases database/disk space requirements. It is usually best to transform as late as possible for example just before displaying the clip to an operator.

If you decide to transform while scanning, you can use one of these IClipHelper methods to capture the clip:

If you decide to defer the transformation, use one of these IClipHelper methods to capture the clip:

When you are ready to save the clip, use the following code snippet:

IClip.TransformOnWrite=false

IClip.WriteToStream (or IClip.WriteToFile)