Recognition Data Handling Module

Letter handling tools. More...

Topics
	LETTER::fontAttrib field elements
	Possible values of LETTER::fontAttrib field.
	LETTER::info field macros
	Macros can be used with LETTER::info field.
	Info field bits
	Possible flags of LETTER::info field.
	LETTER::makeup field elements
	Flags of end-position LETTERs (see usage of them in the table) and direction/orientation flags (see also the section about vertical text support).
	Space type values
	Possible space types (LSPC).
	Macros of alternatives of the LETTER
	Macros can be used for processing the alternatives of each LETTER. See also usage of usage of alternatives.
	Defines of confidence handling of the LETTER
	See confidence handling and LETTER::err.

Classes
struct	LSPC
	Additional information about the space character. More...
struct	LETTER
	The LETTER structure. More...

Typedefs
typedef LETTER *	LPLETTER
	Pointer to a structure LETTER.
typedef const LETTER *	LPCLETTER
	Const pointer to a structure LETTER.

Enumerations
enum	LETTERSTRENGTH {   LTS_FINAL ,   LTS_STRONG ,   LTS_MEDIUM ,   LTS_WEAK ,   LTS_SIZE }
	Possible places where letter array is to be copied to. More...

Functions
RECERR RECAPIKRN	kRecGetLetters (HPAGE hPage, IMAGEINDEX iiImage, LPLETTER *ppLetter, LPLONG pLettersLength)
	Getting recognition result.
RECERR RECAPIKRN	kRecGetLetterPalette (HPAGE hPage, REC_COLOR **ppColours, LPLONG pNum)
	Getting palette of recognition data.
RECERR RECAPIKRN	kRecGetChoiceStr (HPAGE hPage, WCHAR **ppChoices, LPLONG pLength)
	Getting choices.
RECERR RECAPIKRN	kRecGetSuggestionStr (HPAGE hPage, WCHAR **ppSuggestions, LPLONG pLength)
	Getting suggestions.
RECERR RECAPIKRN	kRecGetFontFaceStr (HPAGE hPage, char **ppFontFaces, LPLONG pLength)
	Getting font faces.
RECERR RECAPIKRN	kRecSetLetters (LETTERSTRENGTH towhere, HPAGE hPage, IMAGEINDEX iiImage, LPCLETTER pLetter, LONG LettersLength)
	Putting a letter buffer onto the input of the PLUS2W and PLUS3W engines or the selected output converter.
RECERR RECAPIKRN	kRecFreeRecognitionData (HPAGE hPage)
	Freeing recognition data.

Detailed Description

Letter handling tools.

Recognized data is stored in the current HPAGE and it is available as an array of LETTER structures providing significantly more information than the character code itself. This type of output offers the most detailed information on recognition. The information stored in a LETTER structure may belong to the character itself (character code, position, size, confidence level, font attributes, font face, choices, color) or to the word containing the character (suggestions, languages). Word-level information is set in the first LETTER of the word.

NOTE: In both the SDK and its documentation, coordinates refer to grid-coordinates - i.e. the top or left borders of pixels. Thus a rectangle does not contain the pixels according to its right and bottom coordinates.

Handling of spaces

Spaces have a special role in the text, thus their handling is also special. There are two kinds of spaces in the recognition result.

One of them is the space-like character. It really appears in the original text and it is represented with a LETTER having a space character in its code field and an LSPC structure containing information about this character. The SPACE and TAB characters and the leaders belong to this type. The spcCount field of LSPC cotains the number of characters encoded as this single "space" code. Note that spcCount can be 0 also, meaning an unspecified number of spaces. (It could be treated as 1 space.)

The other kind of space is the dummy space. It does not appear in the original text, but it has an individual LETTER object. A special feature of this character is that its width is 0. This dummy space indicates the end of the line, the R_ENDOFLINE flag is added to this dummy character.

In rare cases, there is no dummy character at the end of a line: it may happen only when the last character in the line is a hyphen. The lack of the dummy space indicates that the last word of this line and the first word of the next line should be logically combined to a single hyphenated word. The R_ENDOFLINE flag is placed on the hyphen in this case. (Note that the info field's RR_SOFTHYPHEN bit is true for such hyphens.)

Barcode module (BAR) has a special binary recognition mode, when the recognition result contains binary data (not a text). (See the setting Kernel.OcrMgr.BarBinary and binary output section for more information.) In this case the content of the barcode is logically one word in one line, but a dummy end-of-line space is appended even to that sequence.

The notion of word in CSDK

The last letter (maybe punctuation character or digit) of a word is the LETTER having an R_ENDOFWORD flag. The beginning of a word is the first non-space character after the previous word (or the very first item of the LETTER array). The flag R_ENDOFLINE does not play a role in determining word boundaries (e.g. hyphenation).

Special cases:

• Inside a word there may be spaces. In an expanded text all the letters are followed by a space.
• In some cases there are no spaces between two words. Examples are words connected with a dash (like Jean-Pierre or drag-and-drop). In such cases the middle R_ENDOFWORD flag is on the character before the dash. This kind of dash is not marked with RR_SOFTHYPHEN even if the dash is at end of line.
• Hyphenated words are treated as one, there is no R_ENDOFWORD before the hyphen. The hyphen's LETTER::info field has the RR_SOFTHYPHEN flag.

Word-related information (like the language of a word or RE_SUSPECT_WORD, etc.) is specified on all the characters of the word. The only exception is suggestion handling where suggestions are attached to the first character of the word only. (Note that suggestion handling uses a different word notion: space-separated words.)

End-position letters

The letters in ending positions are marked with particular flags. See above section for details about end of word. The end of line flag in a flowing text is generally on the above mentioned dummy space. However, if the last character of a line is a hyphen in a hyphenated word, the flag R_ENDOFLINE is placed on the hyphen and the dummy space is missing from this line.

In a table the situation of end-position flags is more difficult. The next figure shows all the possible situations of the R_ENDOFLINE (L), R_ENDOFCELL (C), R_ENDOFROW (R) and R_ENDOFZONE (Z) flags in a table.

text L,C	text L,C	text L,C,R
text L,C	more L lines in L a cell L,C,R
two-line L text L,C		text L,C,R
	last filled L cell L,C,R,Z

The R_ENDOFLINE_CR and R_ENDOFLINE_LF flags may supplement the R_ENDOFLINE flag. They are placed only on a barcode's end-position letters (that are dummy spaces) when the barcode has multiple lines. These flags indicate what kind of EOL code is encoded in the barcode at that position (CR: 0x0d, LF: 0x0a, or the CRLF: 0x0d 0x0a sequence).

Barcode data may also contain runs of EOL codes, i.e. empty lines. In the LETTER array it is implemented as multiple dummy spaces (in normal, non-binary mode). Each dummy space has the R_ENDOFLINE flag with the above supplementary CR and/or LF flags.

Usage of alternatives

The common name for LETTER choices and word suggestions is 'alternatives'. You can use different alternatives similarly. They can be accessed through special WCHAR typed arrays. Every single alternative is a special string with its size in its 0th WCHAR element and an ending zero WCHAR. You can get WCHAR arrays listing of all alternatives in the recognition data - one for choices and one for suggestions. Use the functions kRecGetChoiceStr, and kRecGetSuggestionStr, respectively.

One LETTER contains an index to the list of the alternatives that points to its first alternative and has a counter with the number of its alternatives. All LETTERs can have choices (LETTER::ndxChoices), but only the first LETTER of a word refers to the suggestions (LETTER::ndxSuggestions). The scope of such a suggestion is the space-terminated word. (Note that it can differ from the end of the word notion used by spelling.)

The alternatives of a LETTER can be enumerated using the macros GETFIRSTALTERN, GETNEXTALTERN and GETALTERNLENGTH. See the following sample code on how to use them:

RECERR err;
HPAGE hPage;
LETTER *pLetters;
WCHAR *pChoices;
LONG nLetters, choiceStrLen;
 
...
err = kRecGetLetters(hPage, II_CURRENT, &pLetters, &nLetters);
if (err != REC_OK)
    ... // Doing some error handling
...
err = kRecGetChoiceStr(hPage, &pChoices, &choiceStrLen);
if (err != REC_OK)
    ... // Doing some error handling
for (LONG lettn=0; lettn<nLetters; lettn++)
{
    ...
    const WCHAR *choice = GETFIRSTALTERN(pChoices, pLetters[lettn].ndxChoices);
    for (BYTE chon=0; chon<pLetters[lettn].cntChoices; chon++)
    {
        ... // Doing some choice handling
        choice = GETNEXTALTERN(choice);
    }
    ...
}
...

Consecutive words can have the same suggestion indices - that is, the given suggestions are common to the group of the given words. This is the case when the suggestion combines two space-separated words into a single one without the space.

Since the first LETTER of a word cannot be a space, spaces do not have suggestions, but they have space information (LSPC) in the same union type (see above for more information about space handling).

Font faces can be accessed in a string of C-type strings. The LETTER indexes into this string at the first character of its font face name.

Enumeration Type Documentation

LETTERSTRENGTH

enum LETTERSTRENGTH

Possible places where letter array is to be copied to.

Enumerator
LTS_FINAL	Letters are put directly onto the input of the output conversion step.
LTS_STRONG	Letters are put onto the strong input of the PLUS2W and PLUS3W engines.
LTS_MEDIUM	Letters are put onto the medium input of the PLUS2W and PLUS3W engines.
LTS_WEAK	Letters are put onto the weak input of the PLUS3W engine.
LTS_SIZE	Number of LETTER indices (for verifying index validity).

Function Documentation

kRecFreeRecognitionData()

RECERR RECAPIKRN kRecFreeRecognitionData

(

HPAGE

hPage

)

Freeing recognition data.

The kRecFreeRecognitionData function destroys the recognized data (memory object) belonging to the hPage page.

Parameters

[in]

hPage

Handle of the page having the data to be removed.

Return values

RECERR

Note

The effect of this call is the same as if the application had not called the kRecRecognize function.

The specification of this function in C# is:

RECERR kRecFreeRecognitionData(IntPtr hPage); 

The specification of this function in Java is:

int kRecFreeRecognitionData(HPAGE hPage) 

The specification of this function in Python is:

def kRecFreeRecognitionData(hPage: "HPAGE") -> int 

kRecGetChoiceStr()

RECERR RECAPIKRN kRecGetChoiceStr	(	HPAGE	hPage,
		WCHAR **	ppChoices,
		LPLONG	pLength )

Getting choices.

The kRecGetChoiceStr function makes the alternative letter choices data belonging to the hPage page available to the application by creating a new memory object. This function can be called after a successful kRecRecognize call. The retrieved data is available as an array of WCHAR structures. For more about its internal structure see the usage of alternatives. A LETTER contains the number of its choices and an index into this array on the first choice (LETTER::cntChoices, LETTER::ndxChoices).

Parameters

[in]	hPage	Handle of the page whose recognized data should be accessed.
[out]	ppChoices	Address of a pointer variable to get the array of the recognized alternative characters and ligatures.
[out]	pLength	Pointer to a variable to hold the length of recognized alternative characters.

Return values

RECERR

Note

Since this function creates a new memory object, the application should call the kRecFree function to free this memory area after evaluating the result.

The specification of this function in C# is:

RECERR kRecGetChoiceStr(IntPtr hPage, out char[] ppChoices); 

The specification of this function in Java is:

int kRecGetChoiceStr(HPAGE hPage, Choices ppChoices) 

The specification of this function in Python is:

def kRecGetChoiceStr(hPage: "HPAGE", ppChoices: "Choices") -> int 

kRecGetFontFaceStr()

RECERR RECAPIKRN kRecGetFontFaceStr	(	HPAGE	hPage,
		char **	ppFontFaces,
		LPLONG	pLength )

Getting font faces.

The kRecGetFontFaceStr function makes the font face data belonging to the hPage page available to the application by creating a new memory object. This function can be called after a successful kRecRecognize call. The retrieved data is available as an array of char strings. A LETTER contains an index into this array on its font face (LETTER::ndxFontFace).

Parameters

[in]	hPage	Handle of the page whose recognized data should be accessed.
[out]	ppFontFaces	Address of a pointer variable to get the UTF-8 string of the recognized font faces.
[out]	pLength	Pointer to a variable to hold the length of recognized font face string.

Return values

RECERR

Note

Font face information is available only at processing PDF files with accessible text layer.

Since this function creates a new memory object, after evaluating the result, the application should call the kRecFree function to free this memory area.

The specification of this function in C# is:

RECERR kRecGetFontFaceStr(IntPtr hPage, out char[] ppFontFaces); 

The specification of this function in Java is:

int kRecGetFontFaceStr(HPAGE hPage, FontFaces ppFontFaces) 

The specification of this function in Python is:

def kRecGetFontFaceStr(hPage: "HPAGE", ppFontFaces: "FontFaces") -> int 

kRecGetLetterPalette()

RECERR RECAPIKRN kRecGetLetterPalette	(	HPAGE	hPage,
		REC_COLOR **	ppColours,
		LPLONG	pNum )

Getting palette of recognition data.

This function makes the palette of the recognition data belonging to the hPage page available to the application by creating a new memory object. This function can be called after a successful kRecRecognize call. It contains both the foreground and background colors of the letters. The LETTER structure has indices into this array for foreground and background colors (LETTER::ndxFGColor, LETTER::ndxBGColor).

Parameters

[in]	hPage	Handle of the page whose recognized data should be accessed.
[out]	ppColours	Address of a pointer variable to get the address of the palette array.
[out]	pNum	Pointer to a variable to hold the number of colors in palette.

Return values

RECERR

Note

Palette can contain the special REC_COLOR values REC_DEFAULT_COLOR and REC_UNDEF_COLOR. Background color can be both, they mean white. Foreground color can be REC_DEFAULT_COLOR, which means black.

Since this function creates a new memory object, the application should call the kRecFree function to free this memory area after evaluating the result.

The specification of this function in C# is:

RECERR kRecGetLetterPalette(IntPtr hPage, out uint[] ppColours); 

The specification of this function in Java is:

int kRecGetLetterPalette(HPAGE hPage, RecColorArray ppColours) 

The specification of this function in Python is:

def kRecGetLetterPalette(hPage: "HPAGE") -> Tuple[int, "UIntArray"] 

kRecGetLetters()

RECERR RECAPIKRN kRecGetLetters	(	HPAGE	hPage,
		IMAGEINDEX	iiImage,
		LPLETTER *	ppLetter,
		LPLONG	pLettersLength )

Getting recognition result.

The kRecGetLetters function makes the recognition data belonging to the hPage page available to the application by creating a new memory object containing the recognized data. This function can be called after a successful kRecRecognize call. The recognized data is available as an array of LETTER structures.

Parameters

[in]	hPage	Handle of the page whose recognized data should be accessed.
[in]	iiImage	Index of the image in the page, in which the coordinates are needed to be given.
[out]	ppLetter	Address of a pointer variable to get the address of the recognized characters.
[out]	pLettersLength	Pointer to a variable to hold the number of recognized characters.

Return values

RECERR

Note

Since this function creates a new memory object containing the recognized data, the application should call the kRecFree function to free this memory area after evaluating the result.

The specification of this function in C# is:

RECERR kRecGetLetters(IntPtr hPage, IMAGEINDEX iiImage, out LETTER[] ppLetter); 

The specification of this function in Java is:

int kRecGetLetters(HPAGE hPage, IMAGEINDEX iiImage, LetterArray ppLetter) 

The specification of this function in Python is:

def kRecGetLetters(hPage: "HPAGE", iiImage: int) -> Tuple[int, "LetterArray"] 

kRecGetSuggestionStr()

RECERR RECAPIKRN kRecGetSuggestionStr	(	HPAGE	hPage,
		WCHAR **	ppSuggestions,
		LPLONG	pLength )

Getting suggestions.

The kRecGetSuggestionStr function makes the word suggestions data belonging to the hPage page available to the application by creating a new memory object. This function can be called after a successful kRecRecognize call. The retrieved data is available as an array of WCHAR structures. For more about its internal structure see the usage of alternatives. The first LETTER of a word contains the number of word choices and an index into this array on the first suggestion (LETTER::cntSuggestions, LETTER::ndxSuggestions).

Parameters

[in]	hPage	Handle of the page whose recognized data should be accessed.
[out]	ppSuggestions	Address of a pointer variable to get the array of the recognized suggestions.
[out]	pLength	Pointer to a variable to hold the length of recognized suggestions.

Return values

RECERR

Note

Since this function creates a new memory object, the application should call the kRecFree function to free this memory area after evaluating the result.

If the letter is a space, it does not have suggestions, but only space info (see LETTER::spcInfo and LSPC).

The specification of this function in C# is:

RECERR kRecGetSuggestionStr(IntPtr hPage, out char[] ppSuggestions); 

The specification of this function in Java is:

int kRecGetSuggestionStr(HPAGE hPage, Suggestions ppSuggestions) 

The specification of this function in Python is:

def kRecGetSuggestionStr(hPage: "HPAGE", ppSuggestions: "Suggestions") -> int 

kRecSetLetters()

RECERR RECAPIKRN kRecSetLetters	(	LETTERSTRENGTH	towhere,
		HPAGE	hPage,
		IMAGEINDEX	iiImage,
		LPCLETTER	pLetter,
		LONG	LettersLength )

Putting a letter buffer onto the input of the PLUS2W and PLUS3W engines or the selected output converter.

This function can affect the recognition results and/or the content of the output file. The PLUS modules are voting engines combining results of two or three other OCR engines. The voting method of RM_OMNIFONT_PLUS2W has strong and medium inputs, RM_OMNIFONT_PLUS3W uses an additional weak one as well. You can replace one input (parameter towhere) with your alternative engine result by calling the function kRecSetLetters. The voting method uses your letter buffer as it generates the final OCR result. Stronger input may have greater effect on the recognition result, so you should consider which level you select for your letter buffer.

Passing the letter buffer on the level LTS_FINAL the OCR method does not run, because in this level kRecSetLetters works similarly as in previous versions of CSDK, i.e. the letters are given directly to the input of the selected output converter.

Parameters

[in]	towhere	This parameter specifies one of the three possible inputs of the Voting Engine, on which the engine receives the letter buffer.
[in]	hPage	Handle of the HPAGE the Voting Engine works on.
[in]	iiImage	Index of the image in the page whose coordinate system you have used in defining the boundary box for LETTER.
[in]	pLetter	The letter buffer to be given to the engine.
[in]	LettersLength	Size of the letter buffer.

Return values

RECERR

Note

After putting letters on the selected levels (even on LTS_FINAL), you should call kRecRecognize.

More than one input way of the PLUS engines can be replaced with subsequent calls for kRecSetLetters. Even in such a case, kRecRecognize should be called only once.

The following fields of input LETTERs are unused during kRecRecognize: cntChoices, ndxChoices, cntSuggestions, ndxSuggestions, reserved_b, ndxFGColor, ndxBGColor, ndxFontFace, ndxExt and OCRENGINE bits (RH_OCRENGINE_MASK) of info. These fields are cleared and the original order of LETTERs may be altered after using this function.

The specification of this function in C# is:

RECERR kRecSetLetters(LETTERSTRENGTH towhere, IntPtr hPage, IMAGEINDEX iiImg, LETTER[] lpLetter); 

The specification of this function in Java is:

int kRecSetLetters(LETTERSTRENGTH towhere, HPAGE hPage, IMAGEINDEX iiImage, LETTER[] pLetter) 

The specification of this function in Python is:

def kRecSetLetters(towhere: "LETTERSTRENGTH", hPage: "HPAGE", iiImage: int, pLetter: "LETTER") -> int