Form recognition module. Supported on: Windows, Linux, Embedded Linux, Mac OS X. More...

Classes
struct	COMB_CELL_INFO
	Structure of a comb-cell in a comb. More...
Typedefs
typedef void *	HFORMTEMPLATEPAGE
	Handle of a form template page in memory.
typedef void *	HFORMTEMPLATECOLLECTION
	Handle of a Form Template Collection in memory.
typedef void *	FORMTEMPLATEMATCHINGID
	Id of a matching form template. This ID identifies a matching in Form Template Collection.
Enumerations
enum	ANCHORCONTENT { AC_TEXT, AC_BITMAP, AC_BARCODE, AC_LINE, AC_LETTERS }
	Content of the anchor zone. More...
enum	ANCHORTYPE { AT_POSITIONAL, AT_SELECTOR, AT_REFERENCE, AT_CHECK, AT_SIZE }
	Type of anchor zone. More...
enum	ANCHORFLAG { AF_REGEXP, AF_RECOGNIZE, AF_REGEXPDIDNTMATCH, AF_CHECKED }
	Flags of anchor zones. More...
enum	ANCHOR_REF_POINT { REF_AUTO, REF_CENTRE, REF_TOP_LEFT, REF_TOP_RIGHT, REF_BOTTOM_LEFT, REF_BOTTOM_RIGHT }
	Reference point of the anchor. More...
enum	REF_ANCHOR_MODE { REF_ANCHOR_0, REF_ANCHOR_1, REF_ANCHOR_2, REF_ANCHOR_4 }
	Zone attribute that specifies how the zone is anchored to reference anchors(s). More...
enum	COMB_SPLITTER_HEIGHT { HALF_HEIGHT, FULL_HEIGHT }
	comb attributes More...
Functions
RECERR RECAPIKRN	kRecCreateFormTemplate (int sid, HPAGE hPage)
	Creating form template for processing filled forms.
RECERR RECAPIKRN	kRecSaveFormTemplate (int sid, HPAGE hPage, LPCTSTR pTemplateFilename)
	Saving user zones in a form template file.
RECERR RECAPIKRN	kRecLoadFormTemplate (int sid, HFORMTEMPLATEPAGE *phFormTemplatePage, LPCTSTR pTemplateFilename)
	Loading a form template from a form template file.
RECERR RECAPIKRN	kRecApplyFormTemplate (int sid, HPAGE hPage, HFORMTEMPLATEPAGE hFormTemplatePage)
	Applying a form template - based on a preloaded form template.
RECERR RECAPIKRN	kRecFreeFormTemplate (HFORMTEMPLATEPAGE hFormTemplatePage)
	Removing a form template page.
RECERR RECAPIKRN	kRecApplyFormTemplateFile (int sid, HPAGE hPage, LPCTSTR pTemplateFilename)
	Applying a form template - directly based on a form template file.
RECERR RECAPIKRN	kRecSetZoneFormFieldName (HPAGE hPage, int nZone, LPCWSTR pFormFieldName)
	Changing the name of a form-field attached to a user-zone.
RECERR RECAPIKRN	kRecSetOCRZoneFormFieldName (HPAGE hPage, int nZone, LPCWSTR pFormFieldName)
	Changing the name of a form-field attached to an OCR-zone.
RECERR RECAPIKRN	kRecGetZoneFormFieldName (HPAGE hPage, int nZone, LPWSTR *ppFormFieldName)
	Querying the name of a user-zone.
RECERR RECAPIKRN	kRecGetOCRZoneFormFieldName (HPAGE hPage, int nZone, LPWSTR *ppFormFieldName)
	Querying the name of an OCR-zone.
RECERR RECAPIKRN	kRecSetZoneName (HPAGE hPage, int nZone, LPCTSTR pZoneName)
	Changing the name of a user-zone.
RECERR RECAPIKRN	kRecSetOCRZoneName (HPAGE hPage, int nZone, LPCTSTR pZoneName)
	Changing the name of an OCR-zone.
RECERR RECAPIKRN	kRecGetZoneName (HPAGE hPage, int nZone, LPTSTR *ppZoneName)
	Querying the name of a user-zone.
RECERR RECAPIKRN	kRecGetOCRZoneName (HPAGE hPage, int nZone, LPTSTR *ppZoneName)
	Querying the name of an OCR-zone.
RECERR RECAPIKRN	kRecGetNextZoneByName (HPAGE hPage, LPCTSTR pZoneName, int nPrevZone, int *nZone)
	Querying the next zone with the given name.
RECERR RECAPIKRN	kRecInsertAnchorZone (int sid, HPAGE hPage, ANCHORCONTENT aContent, ANCHORTYPE aType, int nZone)
	Inserting anchor zone.
RECERR RECAPIKRN	kRecUpdateAnchorZone (int sid, HPAGE hPage, IMAGEINDEX iiImg, LPCRECT pRect, int nZone)
	Updating anchor zone info.
RECERR RECAPIKRN	kRecGetAnchorInfo (HPAGE hPage, int nZone, ANCHORCONTENT aContent, ANCHORTYPE aType)
	Returning anchor content and type.
RECERR RECAPIKRN	kRecSetAnchorContent (HPAGE hPage, int nZone, ANCHORCONTENT aContent)
	Setting anchor content.
RECERR RECAPIKRN	kRecSetAnchorType (HPAGE hPage, int nZone, ANCHORTYPE aType)
	Setting anchor type.
RECERR RECAPIKRN	kRecSetAnchorFlag (HPAGE hPage, int nZone, ANCHORFLAG flag, INTBOOL value)
	Changing anchor zone flags.
RECERR RECAPIKRN	kRecGetAnchorFlag (HPAGE hPage, int nZone, ANCHORFLAG flag, INTBOOL *value)
	Getting anchor zone flag.
RECERR RECAPIKRN	kRecSetAnchorText (HPAGE hPage, int nZone, LPCWSTR pText)
	Setting the text attribute of text and barcode anchors.
RECERR RECAPIKRN	kRecGetAnchorText (HPAGE hPage, int nZone, LPWSTR *ppText)
	Getting the text attribute of text and barcode anchors.
RECERR RECAPIKRN	kRecSetAnchorRegExp (HPAGE hPage, int nZone, LPCWSTR pRegExp)
	Setting regular expression of text and barcode anchors.
RECERR RECAPIKRN	kRecGetAnchorRegExp (HPAGE hPage, int nZone, LPWSTR *ppRegExp)
	Getting regular expression of text and barcode anchors.
RECERR RECAPIKRN	kRecSetAnchorDrift (HPAGE hPage, IMAGEINDEX iiImg, int nZone, SIZE drift)
	Setting the drift area of text and barcode anchors.
RECERR RECAPIKRN	kRecGetAnchorDrift (HPAGE hPage, IMAGEINDEX iiImg, int nZone, SIZE *pDrift)
	Getting the drift area of text and barcode anchors.
RECERR RECAPIKRN	kRecSetZoneBarTypes (HPAGE hPage, int nZone, LPCBAR_ENA pBarEna, INTBOOL BarBinary)
	Enabling barcode types for a zone.
RECERR RECAPIKRN	kRecGetZoneBarTypes (int sid, HPAGE hPage, int nZone, LPBAR_ENA pBarEna, INTBOOL pBarBinary, INTBOOL pZoneLevel)
	Getting the enabled barcode types for a zone.
RECERR RECAPIKRN	kRecGetOCRZoneBarTypes (int sid, HPAGE hPage, int nZone, LPBAR_ENA pBarEna, INTBOOL pBarBinary, INTBOOL pZoneLevel)
	Getting the enabled barcode types for an OCR zone.
RECERR RECAPIKRN	kRecSetAnchorRefPoint (HPAGE hPage, int nZone, ANCHOR_REF_POINT ref)
	Setting the reference point of the anchor zone.
RECERR RECAPIKRN	kRecGetAnchorRefPoint (HPAGE hPage, int nZone, ANCHOR_REF_POINT *pref)
	Getting the reference point of the anchor zone.
RECERR RECAPIKRN	kRecInsertDropOutColorZone (HPAGE hPage, IMAGEINDEX iiImg, LPCRECT pRect, int nZone)
	Inserting dropout color zone.
RECERR RECAPIKRN	kRecGetDropOutColorZoneIndex (HPAGE hPage, int *pnZone)
	Getting the index of the dropout color zone.
RECERR RECAPIKRN	kRecSetFormTemplateName (HPAGE hPage, LPCTSTR pTemplateName)
	Setting the name of the form template.
RECERR RECAPIKRN	kRecGetFormTemplateName (HPAGE hPage, LPTSTR *pTemplateName)
	Getting the name of the form template.
RECERR RECAPIKRN	kRecCheckFormTemplate (int sid, HPAGE hPage)
	Checking the form template.
RECERR RECAPIKRN	kRecSetZoneRefAnchors (HPAGE hPage, int nZone, REF_ANCHOR_MODE mode, const int *refAnchors)
	Setting the reference anchor(s) of the zone.
RECERR RECAPIKRN	kRecGetZoneRefAnchors (HPAGE hPage, int nZone, REF_ANCHOR_MODE pmode, int refAnchors)
	Getting the reference anchor(s) of the zone.
RECERR RECAPIKRN	kRecSetTemplateAttribute (HPAGE hPage, LPCTSTR key, LPCTSTR value)
	Setting user defined attribute of a form template.
RECERR RECAPIKRN	kRecGetTemplateAttribute (HPAGE hPage, LPCTSTR key, LPTSTR *pValue)
	Getting user defined attribute of a form template.
RECERR RECAPIKRN	kRecGetNextTemplateAttribute (HPAGE hPage, LPCTSTR prevkey, LPTSTR key, LPTSTR value)
	Querying the names and the values of the user defined attributes of a form template.
RECERR RECAPIKRN	kRecSetZoneAttribute (HPAGE hPage, int nZone, LPCTSTR key, LPCTSTR value)
	Setting user defined attribute of a user zone.
RECERR RECAPIKRN	kRecGetZoneAttribute (HPAGE hPage, int nZone, LPCTSTR key, LPTSTR *pValue)
	Getting user defined attribute of a user zone.
RECERR RECAPIKRN	kRecGetOCRZoneAttribute (HPAGE hPage, int nZone, LPCTSTR key, LPTSTR *pValue)
	Getting user defined attribute of an OCR zone.
RECERR RECAPIKRN	kRecGetNextZoneAttribute (HPAGE hPage, int nZone, LPCTSTR prevkey, LPTSTR key, LPTSTR value)
	Querying the names and the values of the user defined attributes of a user zone.
RECERR RECAPIKRN	kRecGetNextOCRZoneAttribute (HPAGE hPage, int nZone, LPCTSTR prevkey, LPTSTR key, LPTSTR value)
	Querying the names and the values of the user defined attributes of an OCR zone.
RECERR RECAPIKRN	kRecSetZoneOrder (HPAGE hPage, const int *order)
	Changing the order of the user zones.
RECERR RECAPIKRN	kRecGetOCRZoneText (int sid, HPAGE hPage, int nZone, LPTSTR pBuffer, int len)
	Getting the recognized text in the given OCR zone.
RECERR RECAPIKRN	kRecGetOCRTableCellText (int sid, HPAGE hPage, int nZone, int nCellInd, LPTSTR pBuffer, int len)
	Getting the recognized text in the given cell of the given OCR zone.
RECERR RECAPIKRN	kRecLoadFormTemplateLibrary (int sid, LPCTSTR pTmplLib, INTBOOL bLoadSTS, HFORMTEMPLATEPAGE *pphFormTmplArray, int pLength)
	Loading form template library.
RECERR RECAPIKRN	kRecFreeFormTemplateArray (HFORMTEMPLATEPAGE *phFormTmplArray, int Length, INTBOOL bFreeArray)
	Freeing the array of form template handles.
RECERR RECAPIKRN	kRecGetFormTemplateInfo (HFORMTEMPLATEPAGE hFormTmpl, LPTSTR pFullName, LPTSTR pFormPath, int *pFormPage)
	Getting information about a form template.
RECERR RECAPIKRN	kRecFindFormTemplate (int sid, HPAGE hPage, HFORMTEMPLATEPAGE phFormTmplArray, int Length, LPCTSTR FormPath, int FirstPage, int LastPage, HFORMTEMPLATECOLLECTION phFormTmplCollection, FORMTEMPLATEMATCHINGID pBestMatchingId, int pConfidence, int *pnMatching)
	Finding the matching template(s).
RECERR RECAPIKRN	kRecGetFindFormTemplateInfo (HFORMTEMPLATECOLLECTION hFormTmplCollection, LPTSTR *pInfo)
	Getting info about the previous kRecFindFormTemplate call.
RECERR RECAPIKRN	kRecGetNextMatchingTemplate (FORMTEMPLATEMATCHINGID PrevMatchingId, FORMTEMPLATEMATCHINGID pNextMatchingId, int pConfidence)
	Querying the matching form templates.
RECERR RECAPIKRN	kRecGetMatchingInfo (FORMTEMPLATEMATCHINGID MatchId, LPTSTR pFullName, LPTSTR pName, int pPageNumber, int pPageCount)
	Getting information about a matching.
RECERR RECAPIKRN	kRecApplyFormTemplateEx (int sid, HPAGE hPage, FORMTEMPLATEMATCHINGID MatchingId)
	Applying form template - based on a previous kRecFindFormTemplate call.
RECERR RECAPIKRN	kRecFreeFormTemplateCollection (HFORMTEMPLATECOLLECTION hFormTmplCollection)
	Freeing a Form Template Collection.
RECERR RECAPIKRN	kRecLocateComb (int sid, HPAGE hPage, int xZone)
	Analyzing image and detecting comb cells.
RECERR RECAPIKRN	kRecCreateCombInfo (HPAGE hPage, int xZone, INTBOOL hasTopBorder, COMB_SPLITTER_HEIGHT splitterHeight)
	Creating comb info.
RECERR RECAPIKRN	kRecDeleteCombInfo (HPAGE hPage, int xZone)
	Deleting comb info.
RECERR RECAPIKRN	kRecIsComb (HPAGE hPage, int xZone, INTBOOL *isComb)
	Returning whether the zone has comb info.
RECERR RECAPIKRN	kRecGetCombCellCount (HPAGE hPage, int xZone, int *pnCells)
	Returning the number of cells in a comb.
RECERR RECAPIKRN	kRecSetCombInfo (HPAGE hPage, int xZone, INTBOOL hasTopBorder, COMB_SPLITTER_HEIGHT splitterHeight)
	Setting comb attributes.
RECERR RECAPIKRN	kRecGetCombInfo (HPAGE hPage, int xZone, INTBOOL hasTopBorder, COMB_SPLITTER_HEIGHT splitterHeight)
	Getting comb attributes.
RECERR RECAPIKRN	kRecSetCombCells (HPAGE hPage, IMAGEINDEX iiImg, int xZone, const COMB_CELL_INFO *pCells, int nCells)
	Setting the cells of a comb.
RECERR RECAPIKRN	kRecGetCombCells (HPAGE hPage, IMAGEINDEX iiImg, int xZone, COMB_CELL_INFO *ppCells, int pnCells)
	Getting the cells of a comb.

Detailed Description

Form recognition module. Supported on: Windows, Linux, Embedded Linux, Mac OS X.

The form recognition module supports two form processing workflows:

Analyzing empty non-filled forms and converting them into one of several active (fillable) digital form document formats.
Recognizing the contents of filled forms based on pre-constructed form templates and outputting the respondent data contents in some kind of digital format that can be easily processed.

Analysis and activation of empty forms

The current empty form recognition core is mainly based on the Logical Form Recognition™ (LFR) technology which was the backbone of OmniForm, and is now an integrated part of the OmniPage Capture SDK. LFR recognizes textual and non-textual elements in empty forms - like check boxes, circle texts, comb fields, tables/cells, graphics, lines and boxes. These detected form field zones cannot be modified programmatically, but the page can be viewed and modified in the Text Editor Visual control (TEC). (TEC cannot be accessed from the RecAPI layer of CSDK, it is a part of the Visual Toolbox. For more information, see the separated help system of the Visual Toolbox.)

The aim is to turn a form image into a fillable electronic form that can be distributed to respondents or posted on a website. The data in the returned forms can then be processed by any suitable means, outside the scope of the CSDK. It is expected that the filled form data will be returned electronically, so there is no need here for anchor zones.

Typical processing workflow:

Load a single-page image of a form.
Specify the whole page as a single form page (by setting the page descriptor flag LZ_FORM) or define one or more separate form type user zones (WT_FORM) manually.
Perform page decomposition. LFR will run inside the defined form zone(s), as part of the Zone Handling Module, auto-detecting form elements and creating active form controls. (kRecLocateZones, or implicitly during kRecRecognize)
Inspect the auto-detected form objects in the TEC visual control. Move, resize or delete them as required. Add new objects if needed. TEC also lets you view and modify form object attributes. As we mentioned above, these modifications cannot be performed through the RecAPI layer of CSDK.
Save the results to a format that supports active form elements: formatted XML, RTF (Microsoft Word) and PDF (optionally with Acro-Form-like fillable field definitions).
Form object attributes can also be modified in the target application.

Note:

When processing empty forms using a drop-out color, it is recommended to apply auto-deskewing (if desired) when the original image enters into the Engine’s responsibility, or at least before the OCR image is created. Typically with forms, auto-deskew relies on finding printed lines or text lines that are usually form labels. Precisely these elements are removed by applying a drop-out color, so calling auto-deskew when the OCR image is already created is liable to fail. A possible workaround may be the following:

Set drop-out color weights to default (77,150,29).
Detect skew (kRecDetectImgSkew)
Set drop-out color weights
Set slope and rotation (kRecSetImgDeskew, kRecSetImgSlope, kRecSetImgRotation)
Preprocess the image

Furthermore, it is not recommended to apply deskew (or kRecPreprocessImg) when the filled form is processed with kRecApplyFormTemplate, because this function itself performs the necessary image transformations (rotation, deskew, scaling in order to fit the image to the template).

Recognition of filled forms

The main steps of filled form recognition are:

Template definition step: define form template(s) with form-field and anchor zone placement and save the template(s) to form template file or form template library. Use the Form Template Editor (supported on: Windows) to create, edit and test form template libraries.
Processing step:
- template selection: The appropriate template for each scanned image is selected automatically during form processing. Template selection happens with the help of selector, positional and reference anchors.
- template registration/ application: The selected template is matched on the image. The image and/or the zones are deskewed, shifted, enlarged or compressed to match one another. This is also called form registration. Template matching happens with the help of positional and reference anchors.
- recognition of form contents, using the usual recognition tool-set.

The form template is a set of form-field zones (fill zones) and anchor definitions (anchor zones). Form-field zones are normal input zones with some additional layout information attached; they identify the areas where we require fill-in data on a specific form-page (e.g. fill-texts, combs, checkboxes). Anchor definitions are specified as ignore zones during template definition, and receive some additional information when the template is saved, to assist the matching of the template to incoming forms.

The form template library is a ZIP file that may contain one or more form templates in hierarchical directory structure.

The template library contains template files (*.zon), and may contain a setting file in the root directory (Settings.sts), the other files in the ZIP files are ignored by OPSDK.

The structure of the library can be arbitrary, but there are two proposed structures that are supported by Nuance Template Editor.

Library that contains templates of single-page forms. In this case each template is in the root of the ZIP file and the file does not contain more folders.
The typical structure of a single-page form template library is:
- Setting.sts
- TemplateA.zon
- TemplateB.zon
- ...
Library that contains templates of multi-page forms. In this case 2-level library is created: the ZIP file contains container folders, and the container folders contain the templates. The name of the templates contain the number of the page in the form: <name>.<page-number>.zon
The page-number of the first page is 0.
The typical structure of a multi-page form template library is:
- Setting.sts
- TemplateA
  - TemplateA.0.zon
  - TemplateA.1.zon
  - TemplateA.2.zon
  - ...
- TemplateB
  - TemplateB.0.zon
  - TemplateB.1.zon
  - TemplateB.2.zon
  - ...
- ...

Creating a form template definition file

The most convenient way is to use the Nuance Form Template Editor (supported on: Windows) for creating and editing form templates and form template libraries.

You can create and save form templates using the OPSDK API functions as well, but there is no OPSDK API for saving form template library.

Typical workflows to create a form template using OPSDK API functions (step two has four alternatives):

A single-page empty form image is loaded. (kRecLoadImg) If it is scanned, automatic deskewing is recommended. If from file, any supported image file format is acceptable, including any flavor of PDF – these are all treated as imaged input. The input can also be an active PDF form (see how it is handled under 2d). In all cases, the form should contain distinctive shapes (preferably four) to be used as anchors for incoming forms. These shapes should not be printed in a color that is to be dropped-out programmatically.
Form objects
1. Manual zoning
  User inserts flow text zones (kRecInsertZone, WT_FLOW) if their exact position on the page is known and also specifies up to four ignore zones (WT_IGNORE) that contain the shapes to be used as anchors.
2. Auto-detection of form objects
  User calls LFR to identify form objects (page descriptor is LZ_FORM, kRecLocateZones, or page descriptor is not LZ_FORM, one or some WT_FORM zones are drawn, kRecLocateZones), then calls the Create Template function to create user zones from the form objects (kRecCreateFormTemplate). This may also detect the anchor shapes and create ignore zones for them.
3. XML form object definition
  User loads the XML output from OmniPage 15 or later (kRecLoadZones), having used it to process the empty form, optionally having changed the LFR output in the OmniPage Text Editor and exported the page to XML output. This output contains information about form objects. The loading process parses the XML file and creates user zones and anchors based on the file.
4. Active PDF form
  User opens an active PDF form, containing suitable Acro-Form controls for both form objects and anchors. In this case LFR does not need to run, just call the Create Template function.
In all cases, User can access or modify the user zones before they are saved. This can be done in the Text Editor visual control as already described or by KernelAPI calls. In cases 2a-2c, the anchor zones may also be modified. In case 2d (active PDF forms) the anchor zones must not be modified. KernelAPI functions allow form-field identifiers and attributes to be attached to the user zones. These include restrictions to zone content from the checking subsystem – such as regular expressions, dictionaries, character filters like ‘numbers-only’, or other user-defined checking routines.
The Save Template function saves the zone set (kRecSaveFormTemplate), including the attached items and the anchor bitmaps into a template file. This is a standard CSDK zone file extended with anchor data.

Processing filled forms

Using form template library:

Load form template library (kRecLoadFormTemplateLibrary). An array of form template handles is returned.
For each filled form image:
1. Load the image (kRecLoadImg). An HPAGE is returned.
2. Preprocess the image (kRecPreprocessImg).
3. Find matching template (kRecFindFormTemplate). A Form Template Collection handle is returned.
4. Apply form template (kRecApplyFormTemplateEx)
5. Call recognition (kRecRecognize).
6. Query or export recognized text (kRecGetOCRZoneText, kRecGetLetters, kRecConvert2DTXT, ...)
7. Free Form Template Collection handle.
8. Free HPAGE (kRecFreeImg)
Free the array of form template handles (kRecFreeFormTemplateArray).

Using single form template:

User loads a filled form image (kRecLoadImg).
Preprocess the image (kRecPreprocessImg).
The function registers the form using anchor information (kRecApplyFormTemplate) from the template file (created by the steps above). The function transforms the image to fit to form objects and puts form zones on the image.
User calls recognition (kRecRecognize).
Recognition result
1. Hardcore form application gets the letters and processes them somehow (kRecGetLetters).
2. User exports the result into a CSV file (kRecConvert2DTXT).
3. User inserts the page into a RecAPIPlus document and later exports the page into a proper output (RecInsertPage).

Note:: The working of the Form Recognition Module can also be adjusted with settings in some points.; See also the topic Retrieved data format of kRecGetFindFormTemplateInfo

Tables in form templates

Starting with version 20.3, form template can contain table type zones as well. When defining a table with Form Template Editor, only the vertical splitters can be defined. When the form template is applied to the image, the horizontal rows will be determined and the horizontal splitters will be inserted into the table. The created table will be regular in the sense that each horizontal splitter lasts from the left to the right of the table and each vertical splitter lasts from the top to the bottom of the table. You can query the dimensions (the number of cell rows and columns) of the table with kRecGetTableDimensions and kRecGetOCRTableDimensions functions.

When defining the table cell names can be given. When the form template is applied to the image, the initial cells will be split, and each cell inherits the name of the initial cell. You can query the names of the cells with kRecGetCellName kRecGetOCRCellName.

Form Data Extraction

This form processing is based on Logical Form Recognition technology (LFR). CSDK 16 introduced a new method of extracting form data, called FDE (Form Data Extraction). It can be considered a simplified method for collating form data to the CSV format within a workflow. Please consult the RecAPIPlus module Form Data Extraction Module for a description of FDE and a comparison table on the advantages and limitations of FDE and LFR.

Enumeration Type Documentation

enum ANCHOR_REF_POINT

Reference point of the anchor.

Each anchor zone has a reference point. The reference point can be the center or a corner of the bounding box. The reference point is more relevant if the text length can vary (with regular expressions).

Enumerator:

REF_AUTO	if no regexp: centre, else top-left
REF_CENTRE	centre of the bounding box
REF_TOP_LEFT	top-left corner of the bounding box
REF_TOP_RIGHT	top-right corner of the bounding box
REF_BOTTOM_LEFT	bottom-left corner of the bounding box
REF_BOTTOM_RIGHT	bottom-right corner of the bounding box

enum ANCHORCONTENT

Content of the anchor zone.

Content determines what the actual information sought is.

Enumerator:

AC_TEXT	The anchor contains static text. It is word based with a bounding box. It may contain fixed text or regular expression filter. Text can be positional, reference, selector and check anchor.
AC_BITMAP	Anchor contains bitmap (deprecated).
AC_BARCODE	The anchor contains static barcode. The barcode type must be specified. It may contain fixed text or regular expression filter. Barcode can be positional, reference, selector and check anchor.
AC_LINE	Anchor contains rule line (for future realization).
AC_LETTERS	Anchor contains letters (deprecated).

enum ANCHORFLAG

Flags of anchor zones.

Enumerator:

AF_REGEXP	Use regular expression during matching (read only).
AF_RECOGNIZE	Recognize anchor zone.
AF_REGEXPDIDNTMATCH	Regexp did not match (read only).
AF_CHECKED	Anchor checked (read only).

enum ANCHORTYPE

Type of anchor zone.

Type defines what the anchor's function is in form recognition and template creation

Enumerator:

AT_POSITIONAL	Positional anchor: Use these anchor zones to align all zones on the page. Since images can get distorted (especially digital camera pictures of documents taken from a steep angle) using four of such anchors is recommended. It is a page-level operation.
AT_SELECTOR	Selector anchor: Selector anchors do not have role in form alignment and positioning; they are used only for selecting the template (whether the template matches the document or not). It is a template-level operation.
AT_REFERENCE	Reference anchor: Use reference anchors (or reference zones) to more precisely align the zones on the page. It is always preceded by the positional anchor alignment. A zone can have one, two or four reference anchors. It is a zone-level operation.
AT_CHECK	Check anchor: Check anchors are used for checking the form alignment. After positioning, it checks whether each setting is proper (texts not overflowing zones, and so on), otherwise it returns an error. It is a template-level operation.
AT_SIZE

enum COMB_SPLITTER_HEIGHT

comb attributes

It is used by comb handling functions (see also kRecCreateCombInfo)

Enumerator:

HALF_HEIGHT	heights of the splitters: half height of the zone
FULL_HEIGHT	heights of the splitters: same as height of the zone

enum REF_ANCHOR_MODE

Zone attribute that specifies how the zone is anchored to reference anchors(s).

Enumerator:

REF_ANCHOR_0	no reference anchor: the zone is not anchored to reference anchor
REF_ANCHOR_1	one reference anchor: the zone is anchored to the specified reference zone
REF_ANCHOR_2	two reference anchors: one for horizontal and one for vertical alignment
REF_ANCHOR_4	four reference anchors: left, top, right and bottom edges of the zone are aligned independently

Function Documentation

RECERR RECAPIKRN kRecApplyFormTemplate	(	int	sid,
		HPAGE	hPage,
		HFORMTEMPLATEPAGE	hFormTemplatePage
	)

Applying a form template - based on a preloaded form template.

The kRecApplyFormTemplate function applies a form template onto a filled form image. This is called form registration: the function uses the anchors defined by the preloaded form template to fit the loaded zones onto the current filled form. The image (hPage) can be a printed and scanned (filled) form or a filled PDF. It must contain the same form fields and layout that appears on the form the form template is created from. In order to fit the template zones onto the current image the function generally transforms the II_CURRENT image using the combination of shifting, scaling, deskewing and rotation. It may also need to transform the template zones using the combination of shifting and scaling. In certain cases, when deskew and rotation are not required (e.g. when hPage is loaded from a non-image-only PDF) only the zones are transformed (shifted and scaled) and not the II_CURRENT image. The function automatically rotates the image if the current IMG_ROTATE setting is ROT_AUTO (except if the image is non-image-only PDF), otherwise the image is not rotated. The function also creates a new II_BW image, and removes the horizontal and vertical rule lines from it. The function updates the user zone list. After calling this function the image can be recognized as usual, using the kRecRecognize function.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page which contains the filled form.
[in]	hFormTemplatePage	The handle of the form template.

Return values:

ZONE_SIZE_WARN	At least one zone was truncated, because it extends beyond the image.
ZONE_SIZE_ERR	At least one zone was not loaded, because it extends beyond the image.
IMG_ANCHOR_WARN	Some of the anchors were not found.
IMG_ANCHOR_NOT_FOUND	No anchor was found or the template does not contain anchor zones.
RECERR	Other errors.

Note:

The template may contain either bitmap or text anchors (see: ANCHORCONTENT), but cannot contain both.

The specification of this function in C# is:

 RECERR kRecApplyFormTemplate(int sid, IntPtr hPage, IntPtr hTemplate);

RECERR RECAPIKRN kRecApplyFormTemplateEx	(	int	sid,
		HPAGE	hPage,
		FORMTEMPLATEMATCHINGID	MatchingId
	)

Applying form template - based on a previous kRecFindFormTemplate call.

The kRecApplyFormTemplateEx function applies the given form template onto a filled form image.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.
[in]	MatchingId	The ID of the matched form template, returned by kRecFindFormTemplate or kRecGetNextMatchingTemplate.

Return values:

RECERR

Note:: kRecApplyFormTemplateEx can be called after kRecFindFormTemplate has found the matching form template(s) and has returned the matching ID. The function deletes user and OCR zone lists, and inserts the zones to the user zone list from the matched template. In order to fit the template zones onto the image the function generally transforms the II_CURRENT image and/or the template zones using geometric transformations. The function prepares the hPage for recognition: it creates a new II_BW image, removes the horizontal and vertical rule lines and the rule lines of the combs on it.; The zone type of the anchor zones is WT_IGNORE, unless AF_RECOGNIZE flag is set, in this case the zone type is WT_FLOW.

RECERR RECAPIKRN kRecApplyFormTemplateFile	(	int	sid,
		HPAGE	hPage,
		LPCTSTR	pTemplateFilename
	)

Applying a form template - directly based on a form template file.

The kRecApplyFormTemplateFile function applies a form template onto a filled form image. This is called form registration. The function loads the template file (saved by kRecSaveFormTemplate) and uses the anchors to fit the loaded zones onto the current filled form image. See also the comments on kRecApplyFormTemplate. The function updates the user zone list.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page which contains the filled form.
[in]	pTemplateFilename	Path to the form template file.

Return values:

RECERR

Note:

Calling kRecApplyFormTemplateFile is a single-step version of the following alternative workflow - if we do not want to re-use the loaded form template page in multiple kRecApplyFormTemplate calls:

    HFORMTEMPLATEPAGE hFormTemplatePage;
    HPAGE hPage;
    int sid = 0;
    LPSTR pTemplateFilename;
    ...
    kRecLoadFormTemplate(sid, &hFormTemplatePage, pTemplateFileName);
    kRecApplyFormTemplate(sid, hPage, hFormTemplate);
    ...
    kRecFreeFormTemplate(hFormTemplatePage);

The specification of this function in C# is:

 RECERR kRecApplyFormTemplateFile(int sid, IntPtr hPage, string pTemplateFilename);

RECERR RECAPIKRN kRecCheckFormTemplate	(	int	sid,
		HPAGE	hPage
	)

Checking the form template.

The kRecCheckFormTemplate checks the form template and creates a list of warnings and errors. It can be used during the template definition step.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.

Note:: After calling this function call kRecGetLastErrorEx to obtain the list of warnings and errors.; It is recommended to check the form template at the end of the definition phase.

RECERR RECAPIKRN kRecCreateCombInfo	(	HPAGE	hPage,
		int	xZone,
		INTBOOL	hasTopBorder,
		COMB_SPLITTER_HEIGHT	splitterHeight
	)

Creating comb info.

The kRecCreateCombInfo creates comb description for the given user zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	xZone	Index of the zone in the user zone list.
[in]	hasTopBorder	Specifies whether the comb has an upper border or not.
[in]	splitterHeight	Determines the splitter height of the comb.

Return values:

RECERR

Note:

Comb is a horizontal line and a set of vertical lines or a set of rectangles within a fill zone for separating the characters. If you want to recognize the text in a comb, you should define the structure of the comb, this helps to improve accuracy. Comb info is used by kRecApplyFormTemplate, kRecApplyFormTemplateEx and kRecRecognize. Comb info contains the following comb attributes:

whether the comb has a top line or not,
the height of the vertical splitters,
the left and right coordinates of the cells. Comb info is used during the processing of filled forms: kRecApplyFormTemplate and kRecApplyFormTemplateEx removes the comb lines from the II_BW image if comb info specified. Comb info helps kRecRecognize to detect spaces as well. Note that kRecRecognize does not take strict cell information: a cell may contain more characters and characters between cells may be recognized. Only zone of WT_FLOW type may contain comb info.

RECERR RECAPIKRN kRecCreateFormTemplate	(	int	sid,
		HPAGE	hPage
	)

Creating form template for processing filled forms.

A form template is a set of user zones, which contains process zones and anchor zones. Process zones in the form template contain a field name and may contain additional information about the field. Anchor zones are stored in the user zone list as ignore zones and are used by kRecApplyFormTemplate to adjust the filled form to the zone template. The usage of this function depends on the hPage origin type:

if the hPage is loaded from an active non-image-only PDF form: there is no need to perform any processing steps before calling this function: simply load the image and call kRecCreateFormTemplate, it can process the meta-data of the PDF directly, and creates process and anchor zones;
otherwise the image must be an empty form, in this case the form template should be created in the following way:
1. load the empty form image;
2. pre-process it as usual;
3. set PAGEDESCRIPTOR to LZ_FORM OR insert user zone(s) of type WT_FORM; Do not perform both of these!
4. call kRecLocateZones;
5. call kRecCreateFromTemplate: it creates process zones from the form objects detected by the previous kRecLocateZones, and creates anchor zones as well.

The function creates user zones from either the meta-data of the active PDF, or the form objects previously detected by kRecLocateZones. The function also creates anchor zones, used by kRecApplyFormTemplate to adjust the filled form to the zone template. Anchor zones are stored in the user zone list as ignore zones. Generally four anchor zones are created.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.

Return values:

RECERR

Note:

If the form template was created from an active PDF form, the anchor zones contain additional hidden information which is used by kRecApplyFormTemplate, therefore anchor zones should not be modified.

If a user manually creates a form template (inserts WT_FLOW and WT_IGNORE user zones for anchors), the function kRecSaveFormTemplate should be called instead of kRecCreateFormTemplate. See the notes under kRecSaveFormTemplate.

In order to use this form template for processing filled forms, first it must be saved by kRecSaveFormTemplate and then applied by kRecApplyFormTemplateFile or kRecApplyFormTemplate.

The specification of this function in C# is:

 RECERR kRecCreateFormTemplate(int sid, IntPtr hPage);

RECERR RECAPIKRN kRecDeleteCombInfo	(	HPAGE	hPage,
		int	xZone
	)

Deleting comb info.

The kRecDeleteCombInfo deletes comb description of the given user zone. About combs see: kRecCreateCombInfo.

Parameters:

[in]	hPage	Handle of the page.
[in]	xZone	Index of the zone in the user zone list.

Return values:

RECERR

RECERR RECAPIKRN kRecFindFormTemplate	(	int	sid,
		HPAGE	hPage,
		HFORMTEMPLATEPAGE *	phFormTmplArray,
		int	Length,
		LPCTSTR	FormPath,
		int	FirstPage,
		int	LastPage,
		HFORMTEMPLATECOLLECTION *	phFormTmplCollection,
		FORMTEMPLATEMATCHINGID *	pBestMatchingId,
		int *	pConfidence,
		int *	pnMatching
	)

Finding the matching template(s).

The kRecFindFormTemplate finds the matching templates in relevance from the given template set, if any.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.
[in]	phFormTmplArray	Array of form template handles.
[in]	Length	Length of the array.
[in]	FormPath	Optional filter for multi-page templates: only the templates below the FormPath folder are enabled. Set it to NULL if you do not want to specify it.
[in]	FirstPage	Optional filter for multi-page templates: only the templates between FirstPage and Lastpage are enabled. Set it to -1 if you do not want to specify it.
[in]	LastPage	Optional filter for multi-page templates: only the templates between FirstPage and Lastpage are enabled. Set it to -1 if you do not want to specify it.
[out]	phFormTmplCollection	Address of a variable to store the template collection handle. Note that template collection handle may be returned even if an error code is returned.
[out]	pBestMatchingId	Address of a variable to store the ID of the best matching template.
[out]	pConfidence	Address of a variable to store the confidence of the matching. The confidence is between 0 and 100. Greater value means higher confidence.
[out]	pnMatching	Address of a variable to store the number of successful matchings.

Return values:

RECERR

Note:

Input is an actual form page and an array of form template handles. The array of handles can be obtained by loading a form template library (kRecLoadFormTemplateLibrary).

The function uses the anchors defined in the form templates to fit the loaded zones onto the current filled form. This process is also called form registration. In the case of text and barcode anchors the regular expression filter works the following way:

If regular expression filter is not specified: The anchor is found if the Levenshtein distance (minimum number of single-character edits (insertion, deletion, substitution) required to change one word into the other) of the recognized text and the anchor text is less than a given threshold.
If regular expression filter is specified: The anchor is found if the recognized text matches the regular expression.

The matching of a particular template is successful when

each selector anchor is found, and
if the template contains positional anchor: at least one positional anchor is found, and
each reference anchor is found, and
each check anchor is found, and
the confidence value is greater than or equal to the threshold specified by Kernel.Form.MatchingConfidence setting.

The calculation of the confidence. The function finds all possible matchings, and calculates a confidence value for each one. The confidence value is between 0 and 100, 100 means the highest confidence. The matchings having confidence less than the actual value of the Kernel.Form.MatchingConfidence setting (default is 65) are dropped. The successful matchings are sorted by confidence. The calculation of the confidence value is based on the positional and on the reference anchors. If the template contains positional anchors, the (geometric) similarity between the polygon formed by the positional anchors found on the image and the polygon formed by the positional anchors on the template is measured. When not all positional anchors are found on the image, the confidence is reduced proportionately. If the template contains reference anchors as well, a confidence factor is calculated for each reference anchor based on the Levenshtein distance between the defined and the recognized text. The final confidence is the multiplication of the above values.

If HPAGE does not contain letters when the function is called, it recognizes those parts of the image, where anchors may occur (i.e. the union of the anchor locations including drifts). If HPAGE contains letters, the function does not recognize these image areas, but uses the existing letters instead (see Kernel.Form.UseLetters).

The form template handles (phFormTmplArray array) remain unchanged during the whole process. kRecFindFormTemplate creates a new object (called Form Template Collection), all the data collected by this function is stored internally in this object and the handle of this object (HFORMTEMPLATECOLLECTION) is returned. Each successful matching is identified by an ID called matching ID. The function returns the ID of the best matching as well. This ID is input parameter of the next processing step: kRecApplyFormTemplateEx. The function may return HFORMTEMPLATECOLLECTION handle even if an error code is returned! If the phFormTmplCollection output parameter contains a NULL value, a fatal error occurred. If the function returns an error but phFormTmplCollection is not NULL then further information can be asked by calling kRecGetFindFormTemplateInfo. The function also returns the the number of the successful matchings.

If none of the templates matched, the function returns IMG_TEMPLATENOTMATCHED_ERR error. The Form Template Collection stores an error code for each non-matching template, and kRecGetFindFormTemplateInfo can be called to query these individual error codes. kRecGetNextMatchingTemplate can be called on this collection handle to obtain (in relevance order) the additional registration results (ID and confidence of the matchings).

If the template collection handle is no longer needed, it should be freed by invoking the kRecFreeFormTemplateCollection function.

The given form template array may contain NULL handles, these elements are ignored.

The filter parameters (FormPath, FirstPage, LastPage) can be used to select a subset from the array of handles. They can be used when template library contains multi-page form templates (see: kRecLoadFormTemplateLibrary). In this case the name of the container folder can be specified in FormPath parameter, the first and last page can be specified in FirstPage and LastPage parameters.

The templates cannot contain bitmap anchors (ANCHORCONTENT). If any sample contains bitmap anchor the function returns IMG_ANCHOR_CONTENT_ERR error.

RECERR RECAPIKRN kRecFreeFormTemplate ( HFORMTEMPLATEPAGE hFormTemplatePage )

Removing a form template page.

The kRecFreeFormTemplate function removes a form template page from the form handling module.

Parameters:

[in] hFormTemplatePage Handle of the form template page to be removed.

Return values:

RECERR

Note:

The specification of this function in C# is:

 RECERR kRecFreeFormTemplate(IntPtr hTemplate);

RECERR RECAPIKRN kRecFreeFormTemplateArray	(	HFORMTEMPLATEPAGE *	phFormTmplArray,
		int	Length,
		INTBOOL	bFreeArray
	)

Freeing the array of form template handles.

The kRecFreeFormTemplateArray frees the array of form template handles returned by kRecLoadFormTemplateLibrary

Parameters:

[in]	phFormTmplArray	Array of handles.
[in]	Length	Length of the array.
[in]	bFreeArray	The function frees the memory object the phFormTmplArray array points to, if this parameter is TRUE, otherwise it is not freed.

Return values:

RECERR

Note:: This function can free both the HFORMTEMPLATEPAGE handles in the given array and the memory object the phFormTmplArray points to. If phFormTmplArray has been returned by kRecLoadFormTemplateLibrary, it should also be freed (bFreeArray = TRUE). The given array may contain NULL handles, this does not result in error.

RECERR RECAPIKRN kRecFreeFormTemplateCollection ( HFORMTEMPLATECOLLECTION hFormTmplCollection )

Freeing a Form Template Collection.

The kRecFreeFormTemplateCollection frees the given Form Template Collection.

Parameters:

[in] hFormTmplCollection Handle of the Form Template Collection returned by a previous kRecFindFormTemplate.

Return values:

RECERR

Note:: kRecFreeFormTemplateCollection frees all data collected by the previous kRecFindFormTemplate call. The matching IDs stored in this collection handle becomes invalid.

RECERR RECAPIKRN kRecGetAnchorDrift	(	HPAGE	hPage,
		IMAGEINDEX	iiImg,
		int	nZone,
		SIZE *	pDrift
	)

Getting the drift area of text and barcode anchors.

The kRecGetAnchorDrift returns the drift area of text and barcode anchors.

Parameters:

[in]	hPage	Handle of the page.
[in]	iiImg	Index of the image, where drift is specified.
[in]	nZone	Zone index.
[out]	pDrift	Address of a variable to return the drift.

Return values:

RECERR

Note:: The drift area specifies the environment where the anchor is searched. It is a rectangular area, the center of the area is the center of the zone, and the size of the rectangle is specified by the drift parameter. The drift area can be infinite: -1 means infinite area.

RECERR RECAPIKRN kRecGetAnchorFlag	(	HPAGE	hPage,
		int	nZone,
		ANCHORFLAG	flag,
		INTBOOL *	value
	)

Getting anchor zone flag.

The kRecGetAnchorFlag returns the current value of the specified anchor zone flag.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	flag	Flag to ask (ANCHORFLAG).
[out]	value	Address of a variable to store the current value of the flag.

Return values:

RECERR

RECERR RECAPIKRN kRecGetAnchorInfo	(	HPAGE	hPage,
		int	nZone,
		ANCHORCONTENT *	aContent,
		ANCHORTYPE *	aType
	)

Returning anchor content and type.

The kRecGetAnchorInfo returns the anchor content and anchor type property of the zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[out]	aContent	Address of a variable to store the content of the anchor zone (ANCHORCONTENT). If the zone is not an anchor zone, AC_SIZE is returned.
[out]	aType	Address of a variable to store the type of the anchor zone (ANCHORTYPE). If the zone is not an anchor zone, AT_SIZE is returned.

Return values:

RECERR

RECERR RECAPIKRN kRecGetAnchorRefPoint	(	HPAGE	hPage,
		int	nZone,
		ANCHOR_REF_POINT *	pref
	)

Getting the reference point of the anchor zone.

The kRecGetAnchorRefPoint returns the reference point of the anchor zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[out]	pref	Address of a variable to return the reference point.

Return values:

RECERR

Note:: Each anchor zone has a reference point. The reference point can be set by kRecSetAnchorRefPoint.

RECERR RECAPIKRN kRecGetAnchorRegExp	(	HPAGE	hPage,
		int	nZone,
		LPWSTR *	ppRegExp
	)

Getting regular expression of text and barcode anchors.

The kRecGetAnchorRegExp returns the regular expression of text and barcode anchors. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[out]	ppRegExp	Address of a pointer to a string which is allocated and filled by the API-call and contains the ppRegExp.

Return values:

RECERR

Note:: The memory allocated for *ppRegExp can be released using kRecFree.

RECERR RECAPIKRN kRecGetAnchorText	(	HPAGE	hPage,
		int	nZone,
		LPWSTR *	ppText
	)

Getting the text attribute of text and barcode anchors.

The kRecGetAnchorText returns the text attribute of text and barcode anchors.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[out]	ppText	Address of a pointer to a string which is allocated and filled by the API-call and contains the text.

Return values:

RECERR

Note:: The memory allocated for *ppText can be released using kRecFree.

RECERR RECAPIKRN kRecGetCombCellCount	(	HPAGE	hPage,
		int	xZone,
		int *	pnCells
	)

Returning the number of cells in a comb.

The kRecGetCombCellCount returns the number of cells in the comb. About combs see: kRecCreateCombInfo.

Parameters:

[in]	hPage	Handle of the page.
[in]	xZone	Index of the zone in the user zone list.
[out]	pnCells	Address of a variable to store number of cells.

Return values:

RECERR

RECERR RECAPIKRN kRecGetCombCells	(	HPAGE	hPage,
		IMAGEINDEX	iiImg,
		int	xZone,
		COMB_CELL_INFO **	ppCells,
		int *	pnCells
	)

Getting the cells of a comb.

The kRecGetCombCells returns the cells of a comb. About combs see: kRecCreateCombInfo.

Parameters:

[in]	hPage	Handle of the page.
[in]	iiImg	Index of the image, in which the coordinates of the cells are given.
[in]	xZone	Index of the zone in the user zone list.
[out]	ppCells	Address of a variable to return array of COMB_CELL_INFO structures containing the left and right coordinates of the cells.
[out]	pnCells	Address of a variable to return the length of pCells array.

Return values:

RECERR

Note:: The application should call kRecFree to free the returned array.

RECERR RECAPIKRN kRecGetCombInfo	(	HPAGE	hPage,
		int	xZone,
		INTBOOL *	hasTopBorder,
		COMB_SPLITTER_HEIGHT *	splitterHeight
	)

Getting comb attributes.

The kRecGetCombInfo returns the attributes of a comb. About combs see: kRecCreateCombInfo.

Parameters:

[in]	hPage	Handle of the page.
[in]	hPage	Handle of the page.
[in]	xZone	Index of the zone in the user zone list.
[out]	hasTopBorder	Address of a variable to return whether the comb has top border line.
[out]	splitterHeight	Address of a variable to return the height of the splitters.

Return values:

RECERR

RECERR RECAPIKRN kRecGetDropOutColorZoneIndex	(	HPAGE	hPage,
		int *	pnZone
	)

Getting the index of the dropout color zone.

The kRecGetDropOutColorZoneIndex returns the index of the dropout color zone.

Parameters:

[in]	hPage	Handle of the page.
[out]	pnZone	Variable to store the index of the dropout color zone. If the HPAGE does not contain a dropout color zone, the function returns -1.

Return values:

RECERR

Note:: HPAGE may contain only one dropout color zone. If the HPAGE does not contain a dropout color zone, the function returns ZONE_NOTFOUND_WARN; A dropout color zone can be created by kRecInsertDropOutColorZone function.

RECERR RECAPIKRN kRecGetFindFormTemplateInfo	(	HFORMTEMPLATECOLLECTION	hFormTmplCollection,
		LPTSTR *	pInfo
	)

Getting info about the previous kRecFindFormTemplate call.

The kRecGetFindFormTemplateInfo returns information about the previous kRecFindFormTemplate.

Parameters:

[in]	hFormTmplCollection	Handle of the Form Template Collection returned by a previous kRecFindFormTemplate.
[out]	pInfo	Address of a pointer to a string which is allocated and filled by the API-call and contains the information in XML format.

Return values:

RECERR

Note:: The memory allocated for *pInfo can be released using kRecFree.; See also the format of the data retrieved in pInfo.

RECERR RECAPIKRN kRecGetFormTemplateInfo	(	HFORMTEMPLATEPAGE	hFormTmpl,
		LPTSTR *	pFullName,
		LPTSTR *	pFormPath,
		int *	pFormPage
	)

Getting information about a form template.

The kRecGetFormTemplateInfo returns the name and the page number of a form template.

Parameters:

[in]	hFormTmpl	Handle of form template.
[out]	pFullName	Address of a pointer to a string which is allocated and filled by the API-call and contains the full name (name including container folder and page-number as well) of the form template. (The string is terminated with a null character.)
[out]	pFormPath	Address of a pointer to a string which is allocated and filled by the API-call and contains the name of the form template. (The string is terminated with a null character.)
[out]	pFormPage	Address of a pointer for returning the page-number of a template of a multi-page form.

Return values:

RECERR

Note:: Form templates have name and page number attributes. These attributes can be specified during the form template definition.

RECERR RECAPIKRN kRecGetFormTemplateName	(	HPAGE	hPage,
		LPTSTR *	pTemplateName
	)

Getting the name of the form template.

The kRecGetFormTemplateName returns the name of the form template.

Parameters:

[in]	hPage	Handle of the page.
[out]	pTemplateName	Address of a pointer to a string which will be allocated and filled by the API-call and will contain the name of the template. (The string will be terminated with a wide-character zero.)

Return values:

RECERR

Note:: The memory allocated for *pTemplateName can be released using kRecFree.

RECERR RECAPIKRN kRecGetMatchingInfo	(	FORMTEMPLATEMATCHINGID	MatchId,
		LPTSTR *	pFullName,
		LPTSTR *	pName,
		int *	pPageNumber,
		int *	pPageCount
	)

Getting information about a matching.

The kRecGetMatchingInfo returns information about a matching.

Parameters:

[in]	MatchId	ID of the matching returned by kRecFindFormTemplate or kRecGetNextMatchingTemplate.
[out]	pFullName	Address of a pointer to a string which is allocated and filled by the API-call and contains the full name (name including container folder and page-number as well) of the form template. (The string is terminated with a null character.) Can be NULL.
[out]	pName	Address of a pointer to a string which is allocated and filled by the API-call and contains the name of the form template. (The string is terminated with a null character.) Can be NULL.
[out]	pPageNumber	Address of a variable to hold the page-number of the multi-page template. Can be NULL.
[out]	pPageCount	Address of a variable to hold the total number of pages of the multi-page template. Can be NULL.

Return values:

RECERR

Note:: The memory allocated for *pFullName and *pName can be released using kRecFree.

RECERR RECAPIKRN kRecGetNextMatchingTemplate	(	FORMTEMPLATEMATCHINGID	PrevMatchingId,
		FORMTEMPLATEMATCHINGID *	pNextMatchingId,
		int *	pConfidence
	)

Querying the matching form templates.

The kRecGetNextMatchingTemplate returns the ID of the next matching form template.

Parameters:

[in]	PrevMatchingId	Previous matching ID returned by kRecFindFormTemplate or kRecGetNextMatchingTemplate..
[out]	pNextMatchingId	Address of a variable to hold the ID of the next matching template.
[out]	pConfidence	Address of a variable to store the matching confidence. The confidence is between 0 and 100. Greater value means higher confidence.

Return values:

RECERR

Note:: This function can be called after invoking kRecFindFormTemplate. kRecFindFormTemplate finds all possible matchings and sorts them by their confidence. Each matching is identified by an ID called matching ID. kRecFindFormTemplate also returns the ID of the best matching. You can query the IDs of the matchings by calling kRecGetNextMatchingTemplate.

RECERR RECAPIKRN kRecGetNextOCRZoneAttribute	(	HPAGE	hPage,
		int	nZone,
		LPCTSTR	prevkey,
		LPTSTR *	key,
		LPTSTR *	value
	)

Querying the names and the values of the user defined attributes of an OCR zone.

The kRecGetNextOCRZoneAttribute returns the name and the value of the next user defined attribute of a zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	prevkey	Pointer to a string containing the name of the previous attribute. (The string is terminated with a null character.)
[out]	key	Address of a pointer to a string which is allocated and filled by the API-call and contains the name of the next attribute. (The string is terminated with a null character.)
[out]	value	Address of a pointer to a string which is allocated and filled by the API-call and contains the value of the next attribute. (The string will be terminated with a wide-character zero.)

Return values:

RECERR

Note:: User-defined zone attributes are a set of dynamic named values assigned to the zones and maintained by the Engine. Each zone can have a list of user defined attributes. Use this function to query the attributes of a user zone. If prevkey is NULL, the function returns the name and value of the first attribute, otherwise it returns the name and value of the next attribute in the list.; The index of the first zone in the zone list is zero (0).; The memory allocated for *key and *value can be released using kRecFree.

RECERR RECAPIKRN kRecGetNextTemplateAttribute	(	HPAGE	hPage,
		LPCTSTR	prevkey,
		LPTSTR *	key,
		LPTSTR *	value
	)

Querying the names and the values of the user defined attributes of a form template.

The kRecGetNextTemplateAttribute returns the name and the value of the next user defined attribute of a form template.

Parameters:

[in]	hPage	Handle of the page.
[in]	prevkey	Pointer to a string containing the name of the previous attribute. (The string is terminated with a null character.)
[out]	key	Address of a pointer to a string which is allocated and filled by the API-call and contains the name of the next attribute. (The string is terminated with a null character.)
[out]	value	Address of a pointer to a string which is allocated and filled by the API-call and contains the value of the next attribute. (The string is terminated with a null character.)

Return values:

RECERR

Note:: User defined template attributes are a set of dynamic named values that are assigned to the template and maintained by the Engine. Each form template have a list of user defined attributes. Typically the attributes are set during the template definition step, and can be queried during the form processing step. You can query the attributes of a user zone by this function. If prevkey is NULL, the function returns the name and value of the first attribute, otherwise it returns the name and value of the next attribute in the list.; The memory allocated for *key and *value can be released using kRecFree.; If the attribute list does not contain more attributes, *key and *value are set to NULL.

RECERR RECAPIKRN kRecGetNextZoneAttribute	(	HPAGE	hPage,
		int	nZone,
		LPCTSTR	prevkey,
		LPTSTR *	key,
		LPTSTR *	value
	)

Querying the names and the values of the user defined attributes of a user zone.

The kRecGetNextZoneAttribute returns the name and the value of the next user defined attribute of a zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	prevkey	Pointer to a string containing the name of the previous attribute. (The string is terminated with a null character.)
[out]	key	Address of a pointer to a string which is allocated and filled by the API-call and contains the name of the next attribute. (The string is terminated with a null character.)
[out]	value	Address of a pointer to a string which is allocated and filled by the API-call and contains the value of the next attribute. (The string is terminated with a null character.)

Return values:

RECERR

Note:: User-defined zone attributes are a set of dynamic named values assigned to the zones and maintained by the Engine. Each zone can have a list of user defined attributes. Use this function to query the attributes of a user zone. If prevkey is NULL, the function returns the name and value of the first attribute, otherwise it returns the name and value of the next attribute in the list.; The index of the first zone in the zone list is zero (0).; The memory allocated for *key and *value can be released using kRecFree.; If the attribute list does not contain more attributes, *key and *value are set to NULL.

RECERR RECAPIKRN kRecGetNextZoneByName	(	HPAGE	hPage,
		LPCTSTR	pZoneName,
		int	nPrevZone,
		int *	nZone
	)

Querying the next zone with the given name.

The kRecGetNextZoneByName returns the index of the next zone having the given name.

Parameters:

[in]	hPage	Handle of the page.
[in]	pZoneName	Pointer to a string containing the name. (The string is terminated with a null character.)
[in]	nPrevZone	Specifies the start of the query. The function returns the index of the first zone with an index greater than nPrevZone. If nPrevZone < 0 the function returns the index of the first zone that has the given name.
[out]	nZone	Address of a variable to hold the index of the first zone with an index greater than nPrevZone and having the given name.

Return values:

RECERR

Note:: The zones can have a name. More zones can have the same name. You can query the indexes of the zones having the given name. If no such zone is found, the function returns IMG_NOMORE_WARN and *nZone is set to -1 .

RECERR RECAPIKRN kRecGetOCRTableCellText	(	int	sid,
		HPAGE	hPage,
		int	nZone,
		int	nCellInd,
		LPTSTR *	pBuffer,
		int *	len
	)

Getting the recognized text in the given cell of the given OCR zone.

The RecGetOCRTableCellText returns the text recognized in the given cell of the given OCR zone.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.
[in]	nZone	OCR zone index. The function returns error if the given zone is not a table (WT_TABLE) zone;
[in]	nCellInd	Cell index.
[out]	pBuffer	Address of a pointer to a string which is allocated and filled by the API-call and contains the recognized text. (The string is terminated with a null character.)
[out]	len	Address of a variable to hold the length of text.

Return values:

RECERR

Note:: The index of the first zone in the zone list is zero (0).; The returned buffer contains a null-terminated string, and len is the length of the string;; The memory allocated for *pBuffer can be released using kRecFree.

RECERR RECAPIKRN kRecGetOCRZoneAttribute	(	HPAGE	hPage,
		int	nZone,
		LPCTSTR	key,
		LPTSTR *	pValue
	)

Getting user defined attribute of an OCR zone.

The kRecGetZoneAttribute returns the value of a user defined attribute of the given OCR zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	key	Pointer to a string containing the name of the attribute. (The string is terminated with a null character.)
[out]	pValue	Address of a pointer to a string which is allocated and filled by the API-call and contains the value of the attribute. (The string is terminated with a null character.)

Return values:

RECERR

Note:: User-defined zone attributes are a set of dynamic named values assigned to the zones and maintained by the Engine, see also kRecSetZoneAttribute.; The index of the first zone in the zone list is zero (0).; The memory allocated for *pValue can be released using kRecFree.; The attributes of an OCR zone cannot be changed. They are set by the Engine when the OCR zone is created. OCR zones inherit the attribute(s) of the parent user zone.

RECERR RECAPIKRN kRecGetOCRZoneBarTypes	(	int	sid,
		HPAGE	hPage,
		int	nZone,
		LPBAR_ENA	pBarEna,
		INTBOOL *	pBarBinary,
		INTBOOL *	pZoneLevel
	)

Getting the enabled barcode types for an OCR zone.

The kRecGetOCRZoneBarTypes function inquires the barcode types enabled for recognition for the given zone.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[out]	pBarEna	Address of a buffer sized BAR_SIZE that receives the barcode type enable/disable array.
[out]	pBarBinary	Address of a variable to return whether the zone is recognized in binary mode.
[out]	pZoneLevel	Address of a variable to indicate whether the zone-level or the global settings are returned.

Return values:

RECERR

Note:: The only differences between this function and kRecGetZoneBarTypes is that the zone index at this function indexes the OCR zone array. The OCR zones inherit the bartype setting from their parent user zone. See also the notes at the kRecGetZoneBarTypes function.

RECERR RECAPIKRN kRecGetOCRZoneFormFieldName	(	HPAGE	hPage,
		int	nZone,
		LPWSTR *	ppFormFieldName
	)

Querying the name of an OCR-zone.

The kRecGetOCRZoneFormFieldName queries the name of an OCR-zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Index of the OCR-zone to be queried.
[out]	ppFormFieldName	Address of a pointer to a string which will be allocated and filled by the API-call and will contain the form-field name characters. (The string will be terminated with a wide-character zero.)

Return values:

RECERR

Note:

This function is deprecated, use kRecGetOCRZoneName instead.

The index of the first zone in the zone list is zero (0).

The memory allocated for *ppFormFieldName can be released using kRecFree.

The specification of this function in C# is:

 RECERR kRecGetOCRZoneFormFieldName(IntPtr hPage, int nZone, out string ppFormFieldName);

RECERR RECAPIKRN kRecGetOCRZoneName	(	HPAGE	hPage,
		int	nZone,
		LPTSTR *	ppZoneName
	)

Querying the name of an OCR-zone.

The kRecGetOCRZoneName queries the name of the OCR-zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Index of the OCR-zone to be queried.
[out]	ppZoneName	Address of a pointer to a string which will be allocated and filled by the API-call and will contain the name characters. (The string is terminated with a wide-character zero.)

Return values:

RECERR

Note:

The index of the first zone in the zone list is zero (0).

The memory allocated for *ppZoneName can be released using kRecFree.

The specification of this function in C# is:

 RECERR kRecGetOCRZoneName(IntPtr hPage, int nZone, out string ppZoneName);

RECERR RECAPIKRN kRecGetOCRZoneText	(	int	sid,
		HPAGE	hPage,
		int	nZone,
		LPTSTR *	pBuffer,
		int *	len
	)

Getting the recognized text in the given OCR zone.

The kRecGetOCRZoneText returns the text recognized in the given OCR zone.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.
[in]	nZone	OCR zone index.
[out]	pBuffer	Address of a pointer to a string which is allocated and filled by the API-call and contains the recognized text. (The string is terminated with a null character.)
[out]	len	Address of a variable to hold the length of text.

Return values:

RECERR

Note:: The index of the first zone in the zone list is zero (0).; The returned buffer contains a null-terminated string, and len is the length of the string;; If the zone is not a binary barcode zone (see: kRecSetZoneBarTypes) any character codes below 0x20 or between 0x7f and 0xa0 are converted to UNICODE_MISSING characters. (Note that normally such codes are not recognized.) If the zone is a binary barcode zone the character codes below 0x20 or between 0x7f and 0xa0 are converted to escape sequences of the form '\xnn' (nn: two hexadecimal characters). The '\' characters are converted to '\\'.; There is a new-line code (0x0a, '\n') after each line and at the end of a barcode's text. Note that a barcode may contain more than one line, too. Multiple barcodes in the same zone are separated with an extra 0x0c ('\f') code.; The memory allocated for *pBuffer can be released using kRecFree.

RECERR RECAPIKRN kRecGetTemplateAttribute	(	HPAGE	hPage,
		LPCTSTR	key,
		LPTSTR *	pValue
	)

Getting user defined attribute of a form template.

The kRecGetTemplateAttribute returns the value of a user defined attribute of the template. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	key	Pointer to a string containing the name of the attribute. (The string is terminated with a null character.)
[out]	pValue	Address of a pointer to a string which is allocated and filled by the API-call and contains the value of the attribute. (The string is terminated with a null character.) kRecSetZoneAttribute. Address of a pointer to a string which is allocated and filled by the API-call and contains the name characters. (The string is terminated with a null character.)

Return values:

RECERR

Note:: User defined template attributes are a set of dynamic named values that are assigned to the template and maintained by the Engine. Typically the attributes are set during the template definition step, and can be queried during the form processing step. The attributes are saved when the zone list of the HPAGE is saved into a zone file, and loaded when the zone file is loaded and the template is applied.; The memory allocated for *pValue can be released using kRecFree.

RECERR RECAPIKRN kRecGetZoneAttribute	(	HPAGE	hPage,
		int	nZone,
		LPCTSTR	key,
		LPTSTR *	pValue
	)

Getting user defined attribute of a user zone.

The kRecGetZoneAttribute returns the value of a user defined attribute of the given user zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	key	Pointer to a string containing the name of the attribute. (The string is terminated with a null character.)
[out]	pValue	Address of a pointer to a string which is allocated and filled by the API-call and will contain the value of the attribute. (The string is terminated with a null character.) kRecSetZoneAttribute. Address of a pointer to a string which is allocated and filled by the API-call and will contain the name characters. (The string is terminated with a null character.)

Return values:

RECERR

Note:: User-defined zone attributes are a set of dynamic named values assigned to the zones and maintained by the Engine.; The index of the first zone in the zone list is zero (0).; The memory allocated for *pValue can be released using kRecFree.

RECERR RECAPIKRN kRecGetZoneBarTypes	(	int	sid,
		HPAGE	hPage,
		int	nZone,
		LPBAR_ENA	pBarEna,
		INTBOOL *	pBarBinary,
		INTBOOL *	pZoneLevel
	)

Getting the enabled barcode types for a zone.

The kRecGetZoneBarTypes function inquires the barcode types enabled for recognition for the given zone.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[out]	pBarEna	Address of a buffer sized BAR_SIZE that receives the barcode type enable/disable array.
[out]	pBarBinary	Address of a variable to return whether the zone is recognized in binary mode.
[out]	pZoneLevel	Address of a variable to indicate whether the zone-level or the global settings are returned.

Return values:

RECERR

Note:: The enabled barcode types can be set globally (kRecSetBarTypes) and zone by zone (kRecSetZoneBarTypes). This function returns the barcode types enabled for the given zone whether zone-level setting has been set or not. If the zone-level setting has not been set, the function returns the globally enabled barcode types (kRecGetBarTypes) and the global binary mode (Kernel.OcrMgr.BarBinary setting), while sets *pZoneLevel to FALSE.

RECERR RECAPIKRN kRecGetZoneFormFieldName	(	HPAGE	hPage,
		int	nZone,
		LPWSTR *	ppFormFieldName
	)

Querying the name of a user-zone.

The kRecGetZoneFormFieldName queries the name of a user-zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Index of the user-zone to be queried.
[out]	ppFormFieldName	Address of a pointer to a UNICODE string which will be allocated and filled by the API-call and will contain the form-field name characters. (The string will be terminated with a wide-character zero.)

Return values:

RECERR

Note:

This function is deprecated, use kRecGetZoneName instead.

The index of the first zone in the zone list is zero (0).

The memory allocated for *ppFormFieldName can be released using kRecFree.

The specification of this function in C# is:

 RECERR kRecGetZoneFormFieldName(IntPtr hPage, int nZone, out string ppFormFieldName);

RECERR RECAPIKRN kRecGetZoneName	(	HPAGE	hPage,
		int	nZone,
		LPTSTR *	ppZoneName
	)

Querying the name of a user-zone.

The kRecGetZoneName queries the name of a user-zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Index of the user-zone to be queried.
[out]	ppZoneName	Address of a pointer to a string which will be allocated and filled by the API-call and will contain the name characters. (The string will be terminated with a wide-character zero.)

Return values:

RECERR

Note:

The index of the first zone in the zone list is zero (0).

The memory allocated for *ppZoneName can be released using kRecFree.

The specification of this function in C# is:

 RECERR kRecGetZoneName(IntPtr hPage, int nZone, out string ppZoneName);

RECERR RECAPIKRN kRecGetZoneRefAnchors	(	HPAGE	hPage,
		int	nZone,
		REF_ANCHOR_MODE *	pmode,
		int *	refAnchors
	)

Getting the reference anchor(s) of the zone.

The kRecGetZoneRefAnchors returns the reference anchor(s) of the zone. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[out]	pmode	Address of a variable to hold the number of the reference anchors.
[out]	refAnchors	Address of a four-element array to hold the indexes of the reference anchors. The index(es) of the reference anchors are returned here.

Return values:

RECERR

RECERR RECAPIKRN kRecInsertAnchorZone	(	int	sid,
		HPAGE	hPage,
		ANCHORCONTENT	aContent,
		ANCHORTYPE	aType,
		int	nZone
	)

Inserting anchor zone.

The kRecInsertAnchorZone inserts a new anchor zone in the user zone list of the page. It can be used during the template definition step.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.
[in]	aContent	Content of the anchor.
[in]	aType	Type of the anchor.
[in]	nZone	Index in the user zone list where the new zone should be inserted. Use zero (0) to insert the zone as the first element of the zone list. To insert a zone as the last element of the zone list, use -1.

Return values:

RECERR

Note:: Anchor zones are defined during template definition step and used during form processing step for template selection and form registration (ANCHORTYPE). Anchor zones are defined by their types and content. Types define what their function is in form recognition and template creation. Content determines what the actual information sought is. The anchor can be text, barcode, bitmap and letter anchor (see: ANCHORCONTENT). If the anchor is text, letter or barcode anchor, the image is recognized and the anchor value is searched in the recognized text. If the anchor is bitmap anchor, the bitmap attached to the anchor is searched using a template matching algorithm. Each anchor zone has a reference point (ANCHOR_REF_POINT). Anchor zones are ignore zones that have additional information for matching the template to the incoming forms. Additional attributes of the anchor zones can be specified later by kRecUpdateAnchorZone, kRecSetAnchorFlag, kRecSetAnchorText, kRecSetAnchorRegExp, kRecSetAnchorDrift, kRecSetZoneBarTypes, kRecSetAnchorRefPoint.

RECERR RECAPIKRN kRecInsertDropOutColorZone	(	HPAGE	hPage,
		IMAGEINDEX	iiImg,
		LPCRECT	pRect,
		int	nZone
	)

Inserting dropout color zone.

The kRecInsertDropOutColorZone inserts a dropout color zone. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	iiImg	Index of the image in the page whose coordinate system you used in defining the boundary box for the new zone. It is recommended to use II_CURRENT coordinates, if possible.
[in]	pRect	Pointer to the rectangle containing the bounding box of the zone.
[in]	nZone	Index in the user zone list where the new zone should be inserted. Use zero (0) to insert the zone as the first element of the zone list. To insert a zone as the last element of the zone list, use -1.

Return values:

RECERR

Note:: Dropout color zone is used by the form processing function kRecApplyFormTemplateEx. The type of the zone is WT_IGNORE. Internally the zone contains a flag which indicates that this zone must be processed by kRecApplyFormTemplateEx. HPAGE may contain only one dropout color zone. If it already contains a dropout color zone, the function returns API_PARAMETER_ERR. The index of the dropout color zone can be queried by kRecGetDropOutColorZoneIndex.

RECERR RECAPIKRN kRecIsComb	(	HPAGE	hPage,
		int	xZone,
		INTBOOL *	isComb
	)

Returning whether the zone has comb info.

The kRecIsComb returns whether the user zone has comb info. About combs see: kRecCreateCombInfo.

Parameters:

[in]	hPage	Handle of the page.
[in]	xZone	Index of the zone in the user zone list.
[out]	isComb	Address of a variable to return whether the zone has comb info.

Return values:

RECERR

RECERR RECAPIKRN kRecLoadFormTemplate	(	int	sid,
		HFORMTEMPLATEPAGE *	phFormTemplatePage,
		LPCTSTR	pTemplateFilename
	)

Loading a form template from a form template file.

The kRecLoadFormTemplate function loads a form template from a form template file into the form handling module and returns its handle. After loading the form template it can be applied on several pages without loading it from file again (see: kRecApplyFormTemplate).

Parameters:

[in]	sid	Settings Collection ID.
[in]	phFormTemplatePage	Address of a variable to store the handle of the created form template page.
[in]	pTemplateFilename	Path to the form template file.

Return values:

RECERR

Note:

The caller should free the returned HFORMTEMPLATEPAGE by kRecFreeFormTemplate.

The specification of this function in C# is:

 RECERR kRecLoadFormTemplate(int sid, out IntPtr hTemplate, string pTemplateFilename);

RECERR RECAPIKRN kRecLoadFormTemplateLibrary	(	int	sid,
		LPCTSTR	pTmplLib,
		INTBOOL	bLoadSTS,
		HFORMTEMPLATEPAGE **	pphFormTmplArray,
		int *	pLength
	)

Loading form template library.

The kRecLoadFormTemplateLibrary function loads a form template library from a form template library file and returns the array of form template handles. The returned array can be used to find the matching templates on several pages without loading it from file again (see: kRecFindFormTemplate).

Parameters:

[in]	sid	Settings Collection ID.
[in]	pTmplLib	Path to the form template library file.
[in]	bLoadSTS	If this parameter is TRUE, the function loads the settings from the form template library.
[out]	pphFormTmplArray	Address of a variable to store the handles of the created form templates.
[out]	pLength	Address of a variable to store the number of handles in the returned array.

Return values:

RECERR

Note:: The form template library contains a set of form templates. A form template library can be created using the Nuance Form Template Editor. The form template library is a ZIP file that may contain one or more form templates in hierarchical directory structure. Although the structure of the library can be arbitrary, there are two proposed structures supported by Nuance Form Template Editor: one for single-page forms and the other for multi-page forms. For single-page forms, a flat library can be created, which does not contain page numbers. In this case, the forms are identified by name. For multi-page forms, 2-level libraries can be created: the template library contains container folders, and the folders contain the templates. The folders are identified by name, and the templates are identified by page-numbers. The name and page-number of the loaded form templates can be queried by kRecGetFormTemplateInfo.; A form template library may contain a setting file (Settings.sts in the root). If bLoadSTS parameter is TRUE, the function loads this file from the form template library.; The function opens the library file, loads all files with .zon extension, and if the root contains a file named Setting.sts, it is loaded as well. The other files are ignored.; The templates cannot contain bitmap anchors (ANCHORCONTENT). If any sample contains bitmap anchor the function returns IMG_ANCHOR_CONTENT_ERR error.; The returned form template array is the input of the next processing step (kRecFindFormTemplate).; More images can be processed using the same form template array. If the form template array is no longer needed, it should be freed by invoking the kRecFreeFormTemplateArray function.

RECERR RECAPIKRN kRecLocateComb	(	int	sid,
		HPAGE	hPage,
		int	xZone
	)

Analyzing image and detecting comb cells.

The kRecLocateComb detects the comb cells within a user zone. It can be used during the template definition step. About combs see: kRecCreateCombInfo.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.
[in]	xZone	Index of the zone in the user zone list.

Return values:

RECERR

Note:: The function analyses the image area inside the given user zone. It detects whether it contains a comb, and if so, it creates comb info. The function may change the size of the user zone: the zone is applied to the comb. The comb info can be queried by calling kRecGetCombCellCount, kRecGetCombInfo, kRecGetCombCells.

RECERR RECAPIKRN kRecSaveFormTemplate	(	int	sid,
		HPAGE	hPage,
		LPCTSTR	pTemplateFilename
	)

Saving user zones in a form template file.

A form template file is a special zone file which contains additional information. It contains anchor information (anchor zones) and the process zones also contain additional zone information. The template file is used either by kRecLoadFormTemplate or kRecApplyFormTemplateFile.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.
[in]	pTemplateFilename	Path to the form template file.

Return values:

RECERR

Note:

There are several possibilities for creating form templates:

Manual form template creation:
- load an empty form image;
- use kRecInsertZone to insert process zones (type WT_FLOW) and anchor zones (the anchor zones can be inserted as WT_IGNORE zone types);
- save the form template with kRecSaveFormTemplate;
Automatic form template creation from a scanned form image:
- load an empty form image;
- set page descriptor to LZ_FORM (or insert one or more WT_FORM zones, but do not use LZ_FORM in this case);
- call kRecLocateZones;
- call kRecCreateFormTemplate;
- save the form template with kRecSaveFormTemplate;
Form template generation with OmniPage 20:
- load an empty form image into OmniPage 20;
- recognize it as a form. Modify the fields in the editor if necessary;
- save the output in XML format;
- load an empty form image into CSDK;
- load the OmniPage 20 XML output with the kRecLoadZones function;
- save the form template with kRecSaveFormTemplate;
Automatic form template creation from a fillable PDF Form:
- load an active non-image-only PDF form;
- call kRecCreateFormTemplate;
- save the form template with kRecSaveFormTemplate.

The User zone list must contain anchor zones. There is no distinct zone type for the anchor zones: their type is WT_IGNORE. Anchors are simply rectangles. Anchors can be placed on fix static texts which can be identified on the filled forms. It is recommended to define four anchors near the four corners of the page. kRecSaveFormTemplate also saves the bitmap inside the anchors. This information is used by kRecApplyFormTemplate and kRecApplyFormTemplateFile. When the form template is created from an active PDF form - differently from the previous - the anchor zones contain textual information and not a bitmap. Therefore anchor zones should not be modified before kRecSaveFormTemplate.

The specification of this function in C# is:

 RECERR kRecSaveFormTemplate(int sid, IntPtr hPage, string pTemplateFilename);

RECERR RECAPIKRN kRecSetAnchorContent	(	HPAGE	hPage,
		int	nZone,
		ANCHORCONTENT	aContent
	)

Setting anchor content.

The kRecSetAnchorContent sets the content of the anchor zone. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	aContent	Content of the anchor (ANCHORCONTENT).

Return values:

RECERR

RECERR RECAPIKRN kRecSetAnchorDrift	(	HPAGE	hPage,
		IMAGEINDEX	iiImg,
		int	nZone,
		SIZE	drift
	)

Setting the drift area of text and barcode anchors.

The kRecSetAnchorDrift sets the drift area of text and barcode anchors. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	iiImg	Index of the image, where drift is specified.
[in]	nZone	Zone index.
[in]	drift	Drift attribute.

Return values:

RECERR

Note:: The drift area specifies the environment where the anchor is searched. It is a rectangular area, the center of the area is the center of the zone, and the size of the rectangle is specified by the drift parameter. The drift area can be infinite: specify -1 in order to set an infinite area.

RECERR RECAPIKRN kRecSetAnchorFlag	(	HPAGE	hPage,
		int	nZone,
		ANCHORFLAG	flag,
		INTBOOL	value
	)

Changing anchor zone flags.

The kRecSetAnchorFlag sets or resets the given anchor zone flag. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	flag	Flag to set or reset (ANCHORFLAG).
[in]	value	The specified flag is set if its value is TRUE, otherwise it is reset. Read only flags cannot be changed.

Return values:

RECERR

RECERR RECAPIKRN kRecSetAnchorRefPoint	(	HPAGE	hPage,
		int	nZone,
		ANCHOR_REF_POINT	ref
	)

Setting the reference point of the anchor zone.

The kRecSetAnchorRefPoint sets the reference point of the anchor zone. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	ref	Reference point setting.

Return values:

RECERR

Note:

Each anchor zone has a reference point. The reference point can be:

the center of the bounding box,
top-left, top-right, bottom-left or bottom-right corner of the bounding box. The reference point is more relevant if the text length can vary (with regular expressions). The default is REF_AUTO: this means that the reference point is the center of the zone if regular expression is not specified, and the top-left of the zone if regular expression is specified.

RECERR RECAPIKRN kRecSetAnchorRegExp	(	HPAGE	hPage,
		int	nZone,
		LPCWSTR	pRegExp
	)

Setting regular expression of text and barcode anchors.

The kRecSetAnchorRegExp sets the regular expression of text and barcode anchors. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	pRegExp	The regular expression to set.

Return values:

RECERR

RECERR RECAPIKRN kRecSetAnchorText	(	HPAGE	hPage,
		int	nZone,
		LPCWSTR	pText
	)

Setting the text attribute of text and barcode anchors.

The kRecSetAnchorText sets the text attribute of text and barcode anchors. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	pText	Text attribute of the anchor zone.

Return values:

RECERR

Note:: If the anchor is not a text or bitmap anchor, the function returns an error.

RECERR RECAPIKRN kRecSetAnchorType	(	HPAGE	hPage,
		int	nZone,
		ANCHORTYPE	aType
	)

Setting anchor type.

The kRecSetAnchorType sets the type of the anchor zone. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	aType	Type of the anchor (ANCHORTYPE).

Return values:

RECERR

Note:: There are four anchor types both for text and barcode, see ANCHORTYPE.

RECERR RECAPIKRN kRecSetCombCells	(	HPAGE	hPage,
		IMAGEINDEX	iiImg,
		int	xZone,
		const COMB_CELL_INFO *	pCells,
		int	nCells
	)

Setting the cells of a comb.

The kRecSetCombCells sets the cells of a comb. About combs see: kRecCreateCombInfo.

Parameters:

[in]	hPage	Handle of the page.
[in]	iiImg	Index of the image, in which the coordinates of the cells are given.
[in]	xZone	Index of the zone in the user zone list.
[in]	pCells	Array of COMB_CELL_INFO structures containing the left and right coordinates of the cells.
[in]	nCells	Length of pCells array.

Return values:

RECERR

RECERR RECAPIKRN kRecSetCombInfo	(	HPAGE	hPage,
		int	xZone,
		INTBOOL	hasTopBorder,
		COMB_SPLITTER_HEIGHT	splitterHeight
	)

Setting comb attributes.

The kRecSetCombInfo sets the attributes of a comb. About combs see: kRecCreateCombInfo.

Parameters:

[in]	hPage	Handle of the page.
[in]	xZone	Index of the zone in the user zone list.
[in]	hasTopBorder	Specifies whether the comb has top border line.
[in]	splitterHeight	Specifies the height of the splitter lines.

Return values:

RECERR

RECERR RECAPIKRN kRecSetFormTemplateName	(	HPAGE	hPage,
		LPCTSTR	pTemplateName
	)

Setting the name of the form template.

The kRecSetFormTemplateName sets the name of the form template. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	pTemplateName	Name of the template.

Return values:

RECERR

RECERR RECAPIKRN kRecSetOCRZoneFormFieldName	(	HPAGE	hPage,
		int	nZone,
		LPCWSTR	pFormFieldName
	)

Changing the name of a form-field attached to an OCR-zone.

The kRecSetOCRZoneFormFieldName changes the name of an OCR-zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Index of the OCR-zone to be updated.
[in]	pFormFieldName	Pointer to a UNICODE string containing the name characters to be set. (The string is terminated with a wide-character zero.)

Return values:

RECERR

Note:

This function is deprecated, use kRecSetOCRZoneName instead.

The index of the first zone in the zone list is zero (0).

The specification of this function in C# is:

 RECERR kRecSetOCRZoneFormFieldName(IntPtr hPage, int nZone, string pFormFieldName);

RECERR RECAPIKRN kRecSetOCRZoneName	(	HPAGE	hPage,
		int	nZone,
		LPCTSTR	pZoneName
	)

Changing the name of an OCR-zone.

The kRecSetOCRZoneName changes the name of an OCR-zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Index of the OCR-zone to be updated.
[in]	pZoneName	Pointer to a string containing the name characters to be set. (The string is terminated with a null character.)

Return values:

RECERR

Note:

The zones can have a name. More zones can have the same name. When the OCR zones are created by the Engine, they inherit the name of the parent user zone.

The index of the first zone in the zone list is zero (0).

The specification of this function in C# is:

 RECERR kRecSetOCRZoneName(IntPtr hPage, int nZone, string pZoneName);

RECERR RECAPIKRN kRecSetTemplateAttribute	(	HPAGE	hPage,
		LPCTSTR	key,
		LPCTSTR	value
	)

Setting user defined attribute of a form template.

The kRecSetTemplateAttribute inserts, changes or deletes a user defined attribute of a form template. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	key	Pointer to a string containing the name of the attribute. (The string is terminated with a null character.) If the template does not have an attribute by that name, a new attribute is inserted. If the template already has an attribute with the same name and the value parameter is null or an empty string, the attribute is deleted; otherwise the value of the attribute is changed.
[in]	value	Pointer to a string containing the value of the attribute. (The string is terminated with a null character.) If value is NULL pointer or the given string is empty, the attribute is deleted.

Return values:

RECERR

Note:: User defined template attributes are a set of dynamic named values that are assigned to the template and maintained by the Engine. Typically the attributes are set during the template definition step, and can be queried during the form processing step. The attributes are saved when the zone list of the HPAGE is saved into a zone file, and loaded when the zone file is loaded and the template is applied.

RECERR RECAPIKRN kRecSetZoneAttribute	(	HPAGE	hPage,
		int	nZone,
		LPCTSTR	key,
		LPCTSTR	value
	)

Setting user defined attribute of a user zone.

The kRecSetZoneAttribute inserts, changes or deletes a user defined attribute of the given user zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	key	Pointer to a string containing the name of the attribute. (The string is terminated with a null character.) If the zone does not have an attribute by that name, a new attribute is inserted. If the zone already has attribute with the same name and the value parameter is null or an empty string, the attribute is deleted; otherwise, the value of the attribute is changed.
[in]	value	Pointer to a string containing the value of the attribute. (The string is terminated with a null character.) If value is NULL pointer or the given string is empty, the attribute is deleted.

Return values:

RECERR

Note:: User-defined zone attributes are a set of dynamic named values that are assigned to the zones and maintained by the Engine. Typically the attributes are set during the template definition step, and can be queried during the form processing step. The attributes are saved when the zone list of the HPAGE is saved into a zone file, and loaded when the zone file is loaded. The OCR zone inherits the attributes of the parent user zone.; The index of the first zone in the zone list is zero (0).

RECERR RECAPIKRN kRecSetZoneBarTypes	(	HPAGE	hPage,
		int	nZone,
		LPCBAR_ENA	pBarEna,
		INTBOOL	BarBinary
	)

Enabling barcode types for a zone.

The kRecSetZoneBarTypes function is used to specify the enabled barcode type(s) for the given zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	pBarEna	Pointer of a BAR_ENA type array having BAR_SIZE elements. Each element of this array variable corresponds to a BAR_TYPE barcode type, and their values represent the enabled/disabled status of the appropriate barcode type. It can be NULL pointer.
[in]	BarBinary	TRUE value forces the barcode modules to create binary output without any character conversion. See also Binary output.

Return values:

RECERR

Note:: The enabled barcode types can be set globally (kRecSetBarTypes) and zone by zone (this function). If pBarEna is NULL or all elements of the pBarEna array are BAR_DISABLED, the global setting will be used for this zone during recognition. This is the default setting of the zones, therefore in default mode the global setting is used for all zones. This function changes the zone-level enabled barcode types.; Not all barcode types are compatible. To check the barcode type combination you wish to enable, use the kRecCheckBarTypes function. See that function also for the list of incompatible barcode type combinations.; See also the module BAR.

RECERR RECAPIKRN kRecSetZoneFormFieldName	(	HPAGE	hPage,
		int	nZone,
		LPCWSTR	pFormFieldName
	)

Changing the name of a form-field attached to a user-zone.

The kRecSetZoneFormFieldName changes the name of a user-zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Index of the user-zone to be updated.
[in]	pFormFieldName	Pointer to a UNICODE string containing the name characters to be set. (The string is terminated with a wide-character zero.)

Return values:

RECERR

Note:

This function is deprecated, use kRecSetZoneName instead.

The index of the first zone in the zone list is zero (0).

The specification of this function in C# is:

 RECERR kRecSetZoneFormFieldName(IntPtr hPage, int nZone, string pFormFieldName);

RECERR RECAPIKRN kRecSetZoneName	(	HPAGE	hPage,
		int	nZone,
		LPCTSTR	pZoneName
	)

Changing the name of a user-zone.

The kRecSetZoneName changes the name of a user-zone.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Index of the user-zone to be updated.
[in]	pZoneName	Pointer to a string containing the name characters to be set. (The string is terminated with a null character.)

Return values:

RECERR

Note:

The zones can have a name. More zones can have the same name. When the OCR zones are created by the Engine, they inherit the name of the parent user zone.

The index of the first zone in the zone list is zero (0).

The specification of this function in C# is:

 RECERR kRecSetZoneName(IntPtr hPage, int nZone, string pZoneName);

RECERR RECAPIKRN kRecSetZoneOrder	(	HPAGE	hPage,
		const int *	order
	)

Changing the order of the user zones.

The kRecSetZoneOrder changes the order of the user zones in a HPAGE.

Parameters:

[in]	hPage	Handle of the page.
[in]	order	An array containing key values. The array must contain as many elements as the number of zones included in the user zone list.

Return values:

RECERR

Note:: The function uses the given array as keys. The zones are sorted in ascending order of the given keys.

RECERR RECAPIKRN kRecSetZoneRefAnchors	(	HPAGE	hPage,
		int	nZone,
		REF_ANCHOR_MODE	mode,
		const int *	refAnchors
	)

Setting the reference anchor(s) of the zone.

The kRecSetZoneRefAnchors sets the reference anchor(s) of the zone. It can be used during the template definition step.

Parameters:

[in]	hPage	Handle of the page.
[in]	nZone	Zone index.
[in]	mode	Specifies the number of reference anchors.
[in]	refAnchors	The index(es) of the reference anchors. 0, 1, 2 or 4 indexes depending on the mode parameter.

Return values:

RECERR

RECERR RECAPIKRN kRecUpdateAnchorZone	(	int	sid,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		LPCRECT	pRect,
		int	nZone
	)

Updating anchor zone info.

The kRecUpdateAnchorZone updates the bounding box and the value (text value or bitmap) of the anchor zone. It can be used during the template definition step.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page.
[in]	iiImg	The index of the image whose coordinate system you used in defining the bounding rectangle of the zone.
[in]	pRect	Coordinates of the anchor zone.
[in]	nZone	Index of the zone to be updated in the user zone list.

Return values:

RECERR

Note:: The index of the first zone in the zone list is zero (0).; If the anchor zone is bitmap anchor, the bitmap attached to the zone is updated. If the anchor zone is text or barcode anchor, kRecUpdateAnchorZone performs recognition inside the given rectangle, and updates the text value of the anchor. The bounding box of the anchor is fitted to the text (or barcode).

Classes

Typedefs

Enumerations

Functions

Detailed Description

Analysis and activation of empty forms

Recognition of filled forms

Creating a form template definition file

Processing filled forms

Tables in form templates

Form Data Extraction

Enumeration Type Documentation

Function Documentation