Textract SDK User Manual

version 5.0

OCR Screen Text Capture Library for Window

Contents

About Textract

License agreement. Redistribution policy

Textract Installation Pack.

Textract Uninstall

Textract control flags and output formats

Format parameter for Textract() function from Textract.DLL.

Textra.EXE

– Command line parameters

– Operation environment. Font database, INI file

– Examples of command line.

Textract.DLL

– API description for each function

– Operational environment. Font database, INI file

– MFC example of Textract.DLL using

Interrelations between example dialog and Textract control flags

How to control the example

How to compile example

– Console mode examples

Interrelations between examples and Textract control flags

How to compile example

TxtrCtl ActiveX control (TxtrOCX.DLL)

– Install / uninstall of TxtrCtl

– TxtrCtl properties and methods reference

– Visual Basic example of TxtrCtl use

Textract.INI description. Fine Tuning of Font Database settings.

– General

– Font database and capturing options

– Log file support and options

– Debug options

Textract.NET (.NET Framework)

– Textract.NET API.

– Example of C# application that uses Textract.NET .

About Textract

Textract package provides functionality of capturing text from Windows XP – Windows 8 screen using Textract API. Distribution kit includes DLL and EXE to be integrated into a product or software solution.

Software QA departments use Textract to capture text from application that is being tested and compare captured text to intended screen content.

Textract is well suited for corporate environment as applications connectivity tool, to provide one application with text from another one – “source” application. It is especially useful if this source application is a third-party and it cannot be changed or it is hard and time wasting to change it, and there is no adequate embedded communication support.

Textract is based on the specific Optical Character Recognition (OCR) know-how for recognition of text characters from screen. Thus Textract can capture text from any part of any application even if there is no clipboard or OLE support. For example, text can be captured from folder trees, file lists, database reports, text contents of messages and dialog boxes, menus, status lines, legacy systems.

Textract.DLL with simple API can be incorporated into program written in C++, Visual Basic, Power Builder or any other DLL-aware language. It can be used as a block of the whole product that requires text capturing. Textract.DLL offers output into memory or into a file.

TxtrCtl is an ActiveX control based on a 32-bit Windows DLL – TxtrOCX.DLL. TxtrCtl is built on COM-based technology and provides a convenient way of using all functionality of Textract.DLL in any environment that supports ActiveX control, such as Visual C++, Visual Basic, Power Builder, etc.

Textra.EXE is a standalone console mode Win32 application with a simple and powerful command line interface. It can be used to recognize text from screen or a bitmap file and save it into a file in plain text, Rich Text Format (RTF), proprietary binary and verbose text format.

Textract Wizard builds the C++ or VB source code or a batch (.bat) file, requesting you step by step. Textract Wizard is also very recommended as a tool to quickly understand the core Textract API. It’s simpler to get through Textract Wizard than through this document.

Textract SDK contains MFC example that demonstrates usage of Textract.DLL. C++ console mode examples are included to show the simplest way of Textract.DLL usage for each input and output mode. Both MFC and console mode examples are supplied with their source code and compiled executable.

A Visual Basic 6 example of using TxtrCtl AxtiveX control is also included.

There are newest additions to Textract SDK – Scenario. It provides easy and convenient support for system tray icons and system-wide hot keys. They also introduce capture scenario concept and provides all required tools to create, manage and use capture scenario. See more details here: www.structurise.com/textract/scenario/documentation

Textract Commercial is offered online, by phone, fax, check, mail order or purchase order. 30 day money back guarantee is included into License terms.

To order Textract, please visit www.structurise.com/order

Free 40-day Textract Trial is available online at the Textract web page. To evaluate the recognition speed and accuracy, please try Kleptomania utility, based on the same technology. Kleptomania Trial is included into Textract Installation Pack.

License agreement. Redistribution policy

This End-User License Agreement (EULA) is a legal agreement between you (either an individual or a single entity) and StructuRisefor the software accompanying.

The software product and any related documentation is provided “as is”.

The entire risk arising out of use or performance of the software product remains with you.

In no event shall StructuRise or its suppliers be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or any other pecuniary loss arising out of the use of or inability to use this product, even if StructuRise has been advised of the possibility of such damages. Because some states/jurisdictions do not allow the exclusion or limitation of liability for consequential or incidental damages, the above limitation may not apply to you.

If you acquired this product in the United States, this EULA is governed by the laws of the United States. If this product was acquired outside the United States, then local laws may apply.

You are granted the right to use the trial edition of this software, without any time limitation.

You are granted the right to distribute the trial edition of this software, on the following conditions: the distribution package must not be changed and no fee must be charged for this package.

The information, code and executables provided are provided as is. By using this software, you are agreeing to the above terms.

You are granted the right to use this software on 1 (one) computer in private, government commercial, institutional and any other environment.

For the Pack license, you are granted the right to use this software on computers according to the number of licenses purchased.

You may not distribute the Commercial edition of this software.

You may not reverse engineer, decompile, disassemble and change this software.

The information, code and executables provided are provided as is. By using this software, you are agreeing to the above terms.

Should you have any questions concerning any of the License Agreements or if you desire to contact StructuRise for any reason, please write us or email.

Textract Installation Pack.

Installation Directory: Textract is installed into a folder that you specify during the installation. Textract.ini is installed into %AppData%\Structurise directory. In the same directory font database will be created. Language files are installed into %AppData%\Structurise\lng directory (new in version 4.0).

Installed files:

Textract.dll – Text capture library in the form of a dynamic link library.

TextractSmart.dll – Additional OCR engine dynamic link library (new in version 4.0).

Textra.exe – Text capture module in the form of a Win32 console mode executable.

TxtrOCX.dll – ActiveX control.

Textract.ini – An INI file to control DLL and EXE.

Textract.H – C/C++ header file, with API for Textract.DLL.

Textract.LIB – Library for C/C++ linker to link to Textract.DLL.

ExGUI.EXE – Compiled example of Textract.DLL use, based on MFC.

ExGUI\ – Source folder for the example.

ExGUI.cpp,

ExGUI.h,

ExGUIDlg.cpp,

ExGUIDlg.h,

strform.cpp,

strform.h,

StdAfx.cpp,

StdAfx.h,

resource.h,

ExGUI.rc – Source files.

ExGUI.dsp,

ExGUI.dsw,

ExGUI.clw,

ExGUI.mak – Project files

res\ ExGUI.ico,

ExGUI.rc2 – Resources

For each example (there are 16 console mode examples in the pack) there is a compiled executable (.EXE) in the Examples\Bin folder and sample source (.CPP) file, project (.DSP) file and make (.MAK) file in the Examples\Src\ subfolder. Examples are described in Textract.DLL section of this manual.

Compiled executables:

Bmp_File_Ascii.exe, Bmp_File_Binary.exe, Bmp_File_Rtf.exe, Bmp_File_Verbose.exe, Bmp_Memo_Ascii.exe, Bmp_Memo_Binary.exe, Bmp_Memo_Rtf.exe, Bmp_Memo_Verbose.exe, Scr_File_Ascii.exe, Scr_File_Binary.exe, Scr_File_Rtf.exe, Scr_File_Verbose.exe, Scr_Memo_Ascii.exe, Scr_Memo_Binary.exe, Scr_Memo_Rtf.exe, Scr_Memo_Verbose.exe

VBTxtr.EXE – compiled VB5 example of TxtrCtl ActiveX control using

ExVB\ – source folder for the example

Visual C++ example

ExGUI.EXE – compiled VC6 example of Textract.DLL using

ExGUI\ – source folder for the example

Textract Wizard.EXE – Wizard is designed to create appropriate parts of source code to use Textract functionality. Wizard has a mini-help inside.

Textract Uninstall

Textract installs all files into one folder and its subfolders. This folder is specified during the installation, the subfolders are described in the “Textract Installation pack” section of this manual.

Use Uninstall Textract shortcut in the Textract menu group to uninstall Textract.

Textract control flags and output formats

Textract.DLL and Textra.EXE get an image from BMP file or from specified screen rectangle (Textract.DLL also includes support for input from a specified by handle window). After text recognition the result can be saved in one of five output formats.

Control flags for output format types:

Output format	Textract.DLL	Textra.EXE	Examples name
Plain text	dfText	/ascii	Xxx_Yyy_Ascii.Exe
RTF (Rich Text Format)	dfRtf	/rtf	Xxx_Yyy_Rtf.Exe
Verbose text	dfVerbose	/verbose	Xxx_Yyy_Verbose.Exe
Binary	dfBinary	/binary	Xxx_Yyy_Binary.Exe
Bitmap	dfBmp	/bmp

Additional flags to control verbose and binary format (see below for details):

Textra.EXE: /bol /eol /space /char /font /charhex /charfont /charcolor

Textract.DLL: dfBol dfEol dfSpace dfChar dfFont dfCharHex dfCharFont dfCharColor

Xxx can be either SCR or BMP and specifies a text source.

Yyy can be either MEMO or FILE and specifies results output.

Textract.DLL saves results in memory or into a file;

Textra.EXE saves the result only into a file.

The result is a plain ASCII text terminated by trailing zero if it is stored by DLL into memory. If the text is stored into a file then there is no trailing zero. The text is properly spaced and divided into lines by CR/LF pairs (standard for Microsoft operating systems). Additional information such as font face and pitch, colour, exact location of characters on the screen/bitmap is not available in this format.

/ascii

Command line parameter for Textra.EXE.

dfText

Format parameter for Textract() function from Textract.DLL.

Xxx_Yyy_Ascii.Exe

Console mode examples that demonstrate using of this format.

The result is a Rich Text Format. Font face, pitch size, style, colour information are saved in RTF mode. Exact location of characters on the screen/bitmap is omitted.

/rtf

Command line parameter for Textra.EXE.

dfRtf

Format parameter for Textract() function from Textract.DLL.

Xxx_Yyy_Rtf.Exe

Console mode examples that demonstrate using of this format.

The result is a text format, which keeps all the information gathered on recognition step. Captured data is considered as a sequence of lines, which are composed from characters and spaces. Verbose output format consists of lines that describe captured elements sequence (see below for details). Each line is terminated with CR/LF pair.

/verbose

Command line parameter for Textra.EXE.

dfVerbose

Format parameter for Textract() function from Textract.DLL.

Xxx_Yyy_Verbose.Exe

Console mode examples that demonstrate using of this format.

BOL 8 6

FONT 12 Arial

CHAR W 57 8 6 FF00FF 12 Arial

CHAR e 65 27 6 FF00FF 12 Arial

CHAR l 6C 38 6 FF00FF 12 Arial

CHAR c 63 42 6 FF00FF 12 Arial

CHAR o 6F 52 6 FF00FF 12 Arial

CHAR m 6D 63 6 FF00FF 12 Arial

CHAR e 65 79 6 FF00FF 12 Arial

EOL

Output element	Description	Textract.DLL	Textra.EXE
BOL	Begin Of the Line	dfBol	/bol
EOL	End Of the Line	dfEol	/eol
CHAR	Character details	dfChar dfCharHex dfCharFont dfCharColor	/char /charhex /charfont /charcolor
SPACE	Spacing between characters	dfSpace	/space
FONT	Font details	dfFont	/font

Use flags from the corresponding column Textract.DLL or Textra.EXE to force the required output.

BOL <x> <y>

Specifies Begin Of the Line.

pixel coordinates of the line position on the image relative to the upper left corner of the image.

/bol, dfBol – turns on BOL output lines.

EOL

Specifies End Of the Line.

/eol, dfEol – turns on EOL output lines.

CHAR <char> <hex> <x> <y> <color> <pitch> <fontName>

Specifies recognized character details.

<char>

Recognized character, as is.

<hex>

Hexadecimal code of the character (e.g. 4B or 2E.)

Pixel coordinates of the character relative to the upper left corner of the image.

<color>

Character color in hex format RRGGBB (%06X).

<pitch>

Font pitch size.

Font face name. It can contain spaces in the name.

/char, dfChar – turns on CHAR output lines.

/charhex, dfCharHex – turns on <hex> field

/charcolor, dfCharColor – turns on <color> field

/charfont, dfCharFont – turns on <pitch> and <fontName> fields.

SPACE <spacing> <e>

Specifies spacing between characters.

Spacing between characters measured in pixels.

<e>

EXACT if the spacing corresponds to space width for this font face/pitch.

INEXACT if the spacing is not equal to the space width for this font face/pitch.

/space, dfSpace – turns on SPACE output lines.

FONT <pitch> <fontName>

Specifies font of character described in following CHAR line.

Emitted if character’s font differs from the previous one. Also it is typed-out before the first CHAR in the output.

<pitch>

Pitch size of the font

Font face name. It can contain spaces in the name.

/font, dfFont – turns on FONT output lines.

The result is a binary format that keeps all the information collected on recognition step. Captured data is considered as a sequence of lines that consist of characters and spaces. Output is an array of TextractItem structures that describe this sequence of elements.

/binary

Command line parameter for Textra.EXE.

dfBinary

Format parameter for Textract() function from Textract.DLL.

Xxx_Yyy_Binary.Exe

Console mode examples that demonstrate using of this format.

Output structure is defined in Textract.H as TextractItem class:

class TextractItem {

public:

TextractItemType Type :8;

short OffsetX, OffsetY;

unsigned short FontIndex;

const char *FontName;

char Ch;

long Color;

unsigned char Pitch;

short Spacing;

int IsExactSpacing : 8;

};

where

TextractItemType Type

Type of the item. It can be one of the following values:

Value	Verbose output	Textract.DLL	Textra.EXE
itChar	CHAR	dfBol	/bol
itSpace	SPACE	dfEol	/eol
itLineStart	BOL	dfChar dfCharHex dfCharFont dfCharColor	/char /charhex /charfont /charcolor
itLineTerm	EOL	dfSpace	/space
itFont	FONT	dfFont	/font

Use switches from the corresponding column Textract.DLL or Textra.EXE to force the required output.

OffsetX, OffsetY

Specifies pixel coordinates relative to the upper left corner of the image.

This member is valid for itChar and itLineStart.

FontIndex

This member is unique font index. It can be used to compare fonts of different characters for equivalence. It is valid for itChar.

FontName

Specifies font face/style name.

This member is valid for itChar and itFont.

Specifies the captured character.

This member is valid for itChar.

Color

Specifies color of the captured character in RGB format – RRGGBB.

This member is valid for itChar.

Pitch

Specifies font pitch size. This member is valid for itChar and itFont.

Spacing

Specifies spacing between characters, measured in pixels. This member is valid for itSpace.

IsExactSpacing

True if the spacing is proper in accordance with space width for this font face/pitch

False if the spacing is not equal to the space width for this font face/pitch.

This member is valid for itSpace.

This format can be used to capture source image and store it as a bitmap. There is no recognized text. Captured image is saved to a bitmap file. The bitmap is true-colour (24 bits per pixel) unpacked Windows BMP. If output file extension is missed then .bmp extension will be appended to the file name string. To prevent this – add dot ‘.’ as a trailing symbol to the file name.

/bmp

Command line parameter for Textra.EXE.

dfBmp

Format parameter for Textract() function from Textract.DLL.

Textra.EXE

Textra.EXE is a 32-bit Windows console mode application. It can be used with various command line parameters to build font database or recognize text from different sources and output it in required format.

/build

Builds the font database according to the INI file specification. If /build is specified, other options are not allowed.

Font database file name can be specified in Textract.INI file – Options section, Database Path entry. If it is not specified, Textra.EXE will build the base in the %AppData%\Structurise folder with the name Textract.PAT.

/capture <ax> <ay> <bx> <by> <output format flags> <outputFile>

Captures rectangle from the screen, recognises the text and stores the results into an output file.

Specifies the screen coordinates in pixels of the upper-left corner of the rectangle. These coordinates are included into the rectangle.

Specifies the screen coordinates in pixels of the lower-right corner of the rectangle. The rectangle extends up to, but does not include, the right and bottom coordinates.

The following parameters can be used to specify output format:

/ascii – for plain text output mode

/rtf – for RTF output mode

/verbose – for verbose text output mode

/binary – for binary output mode

Additional parameters for verbose text output format:

/bol, /eol, /space, /char, /font, /charhex, /charfont, /charcolor.

Additional parameters for binary output format:

/bol, /eol, /space, /char, /font.

Specifies path name of an output file. Default file extension is not appended.

/recognize <inputBitmapFile> <output format flags> <outputFile>

Recognizes the bitmap specified in a command line.

Input file is 1, 4, 16, 24, 32 bits per pixel unpacked BMP or RLE-encoded Windows bitmap. If the extension is not specified in the command line .BMP is appended.

The following parameters can be used to specify output format:

/ascii – for plain text output mode

/rtf – for RTF output mode

/verbose – for verbose text output mode

/binary – for binary output mode

Additional parameters for verbose text output format:

/bol, /eol, /space, /char, /font, /charhex, /charfont, /charcolor.

Additional parameters for binary output format:

/bol, /eol, /space, /char, /font.

Specifies path name of an output file. Default file extension is not appended.

At the start Textra.EXE searches Textract.INI file to load parameters. If Textract.INI cannot be found, Textra.EXE is terminated with the following error message: “File Texract.INI not found”.

For /capture and /recognize modes, Textra.EXE loads the font database file, specified in Texract.INI [Options] section under the entry Database Path =<path>\Textract.PAT. If the file is not found, Textra.EXE is terminated with error message: “Font database Textract.PAT not found”.

Textra /build

Builds or rebuilds the font database Textract.PAT.

Textra /capture 0 0 800 600 /ascii whole.txt

Captures the screen rectangle with coordinates (0, 0)- (800, 600) and stores the result into “whole.txt” in plain text format.

Textra /capture 2 580 798 600 /rtf taskbar.rtf

Captures the screen rectangle with coordinates (2, 580)- (798, 600) and stores the result into “taskbar.rtf” in RTF format.

Textra /recognize alphabet /verbose /font /char alphabet.txt

Recognizes “alphabet.BMP” file and saves the result to “alphabet.txt” in verbose text format, emitting only FONT and CHAR lines.

Textract.DLL

Textract.DLL is a 32-bit Windows dynamic-link library (DLL) that provides the text recognition functionality that can be accessed using simple API.

Textract.DLL API is defined in header file Textract.H.

Each Textract function returns TextractSuccessresult code. The possible values are defined as the following:

tsOK

Returned if the function has been completed successfully.

tsReject

Returned if user rejected the operation.

tsBadArgs

Returned if function arguments are incorrect

tsBadBitmap

Returned if the bitmap format is not supported. Textract supports bitmap files that are 1, 4, 16, 24, 32 bits per pixel unpacked or RLE-encoded Windows BMP.

tsOutOfWindow

Returned if the specified coordinates are out of the window.

tsIniNotFound

Returned if an INI file wasn’t found.

tsBaseNotFound

Returned if a font pattern database file wasn’t found.

tsBitmapNotFound

Returned if a Bitmap (BMP) file wasn’t found.

tsInitFailed

Returned by TextractInit() if it failed.

tsTermFailed

Returned by TextractTerm() if it failed.

tsFormat

Returned in case of an incorrect file format.

tsNoAccess

Returned when a file cannot be accessed for reading or writing.

tsCrash

Returned if some Textract internal error occurs.

The following two functions are used to initialise and terminate Textract.DLL:

TextractSuccess TextractInit();

TextractSuccess TextractTerm();

TextractInit() must be a first call to the library prior to using other functions of the library. TextractTerm() must be called at the end of library using to clean up. Be sure that all objects of class TextractDest are destroyed before calling to TextractTerm().

Multiple calls of TextractInit()/TextractTerm() are allowed during one session.

TextractSuccess TextractBuild();

Builds the font database. TextractBuild() is a silent version without user’s interface.

TextractSuccess TextractBuildWithDialog();

TextractBuildWithDialog() opens the dialog box to ask the user about building the font database and displays progress feedback.

const char *TextractIniFileName();

Returns initialisation file name.

const char *TextractBaseFileName();

Returns font database file name.

const char *TextractBitmapFileName();

Returns last bitmap file name.

The following function is the key of text capturing and recognition:

TextractSuccess Textract(

TextractSource& src,

TextractDest& dst,

TextractDestFormat fmt );

Parameters:

src

TextractSource defines a source image for recognition. It can be bitmap file or screen area. See details below.

dst

TextractDest defines recognition results destination. It can be a memory area or a file with a specified name. See details below.

fmt

TextractDestFormat specifies output format. It can be one of the values described in “Textract control flags and output formats” section of this manual: dfText, dfRtf, dfVerbose, dfBinary, dfBmp.

class TextractSource {

public:

TextractSource();

TextractSource& BmpFile(const char *bmpFileName);

TextractSource& Wnd(HWND);

TextractSource& Rect(int ax, int ay, int bx, int by);

TextractSource& DesktopWnd();

TextractSource& TopWnd(const char *windowClass, const char *windowText);

TextractSource& DeepWnd(const char *windowClass, const char *windowText);

TextractSource& SubWnd(const char *windowClass, const char *windowText);

TextractSource& SubDeepWnd(const char *windowClass, const char *windowText);

TextractSource& FindLargestWindow();

const char *BmpFileName; // used if != NULL

bool IsScrolling; // used if W != NULL

HWND W; // used if != NULL

int AX, AY, BX, BY; // used if BmpFileName == NULL and Wnd == NULL

};

TextractSource& BmpFile( const char *bmpFileName );

This function specifies source bitmap to capture text from.

bmpFileName

A string that is the path to the desired bitmap file. The path can be relative or absolute.

TextractSource& Rect(int ax, int ay, int bx, int by);

This function specifies the rectangle screen area to capture text from.

ax, ay

Specifies the screen coordinates in pixels of the upper-left corner of the rectangle. These coordinates are included into the rectangle.

bx, by

Specifies the screen coordinates in pixels of the lower-right corner of the rectangle. The rectangle extends up to, but does not include, the right and bottom coordinates.

TextractSource& Wnd( HWND hWnd );

This function specifies the handle of a window to capture text from.

hWnd

Handle to the window.

TextractSource& DesktopWnd();

This function specifies the desktop window as a window to capture text from.

TextractSource& TopWnd( const char *windowClass, const char *windowText );

This function defines that text will be captured from the top-level window with specified window class and caption (title).

windowClass

Pointer to a null-terminated string that defines window class name.

windowText

Pointer to a null-terminated string that defines window caption (title).

TextractSource& ScrollWnd( HWND hWnd );

This function defines that text will be captured from the entire window with vertical scrolling including hidden parts that are scrolled through.

Note that only vertical scrolling is performed. Horizontal scrolling is not supported.

TextractSource& DeepWnd(const char *windowClass, const char *windowText);

This function defines that text will be captured from the child window that has a desktop window as a parent window.

windowClass

Pointer to a null-terminated string that defines window class name.

windowText

Pointer to a null-terminated string that defines window caption (title).

TextractSource& SubWnd(const char *windowClass, const char *windowText);

This function defines that text will be captured from the first child window of the window that matches specified window class name and caption.

windowClass

Pointer to a null-terminated string that defines window class name.

windowText

Pointer to a null-terminated string that defines window caption (title).

TextractSource& SubDeepWnd(const char *windowClass, const char *windowText);

This function defines that text will be captured from the child window that matches specified window class name and caption.

windowClass

Pointer to a null-terminated string that defines window class name.

windowText

Pointer to a null-terminated string that defines window caption (title).

TextractSource& FindLargestWindow();

This function defines that text will be captured from the largest child window of an active window.

See source code examples of using TextractSource in the file /Src/ExGUI/ExGUIDlg.cpp

Textract( TextractSource().BmpFile(“MyImage.Bmp”) …

will recognise the text from a bitmap.

Textract( TextractSource().Rect (0,0, 100,200) …

will capture text from the screen rectangle area with (0,0) left-top and (100,200) right-bottom coordinate points.

TextractCapture(TextractSource()

.TopWnd( NULL, “Inbox – Outlook Express” )

.SubDeepWnd( “SysTreeView32″, “” ) …

will capture text from visible area of a window with the class name “SysTreeView32” that is a child window of top level window with caption/title “Inbox – Outlook Express”.

Methods DesktopWnd, TopWnd and DeepWnd are designed to work together to specify the required window with known accuracy.

Textract(TextractSource().FindLargestWindow() …

will find the largest visible subwindow on the screen. For instance, it can be used to capture terminal emulator window.

class TextractDest {

public:

TextractDest(const char *destFileName);

TextractDest();

const char *FileName; // NULL if Area specified, else destination file name

void *Area; // NULL if file name specified, else memory area

int AreaSize; // including trailing zero for string formats

};

TextractDest(const char *destFileName);

This function defines that output will be stored to the specified file.

destFileName

A string that is the path to output file. The path can be relative or absolute.

Area

If file name is not specified then output is placed into memory area and this member is pointer to this memory area. It is NULL if filename is specified.

AreaSize

Specifies memory area size.

TextractSuccess TextractDestFree( TextractDest& dst );

This function MUST be called to clean up when destination is memory area.

Textract(… , TextractDest(“Results.Txt”) …

will save results into the specified file.

TextractDest dest;

Textract(… , dest, …);

… use dest.Area of size dest.AreaSize …

TextractDestFree(dest); // for dest reuse

will store results in memory and return pointer to this memory in dest.Area member. Member dest.AreaSize specifies size of the allocated memory.

enum TextractDestFormat {

This enum type defines output format.

enum TextractItemType { …

class TextractItem { …

These items are used in binary (dfBinary) output.

See also “Textract control flags and output formats” section.

TextractInit() searches for Textract.INI file to load parameters (see Textra.EXE description).

1. If Textract.INI cannot be found then tsIniNotFound is returned.

2. TextractInit() loads the font database file specified in the INI file.

[Options]

Database Path =<path>\Textract.PAT.

If this file is not found then TextractInit returns tsPatNotFound.

ExGUI MFC-based application allows to test Textract.DLL functions step by step, manually, in any order.

“Build font pattern database” can be used to build/update the font database. Usually the font database is created upon Textract installation but you may want to update it if some fonts are installed or removed from the system. Note that either Textract.DLL (function TextractBuildWithDialog()) or Textra.EXE (command line /build) can create the font database.

The example consists of 4 simple steps:

1. Choose the recognition source. It can be a screen rectangle, a bitmap (BMP) file or a window. Use “Rectange” / “Bitmap file” / “Window” radio buttons to select desired text source. Then specify the coordinates of screen rectangle or BMP file name or a window. For rectangle area ax,ay are screen coordinates of upper-left corner (inclusive) and bx,by are screen coordinates of lower-right corner (exclusive).

2. Select where to save results by “Memory” or “File” radio buttons. Specify the filename if file output is selected.

3. Choose the output format. See description in Textract control flags and output formats section of this manual. Set Text, Rtf, Binary, Verbose or Bitmap format. For Binary and Verbose format, specify subset Bol, Eol, Space, Char and Font output data/lines to be generated.

4. Click “Recognize” button to process the image using specified source, destination and output format. Internally ExGUI creates TextractSource class instance, TextractDest class instance and calls Textract() function of Textract.DLL to perform text recognition. DLL captures the image from the specified source (screen area, window or BMP file). Then it recognizes text on the image. After that it outputs the result in the specified format and puts it into memory or writes into a file according to specified destination. After that ExGUI converts the returned data into text human-readable format, writes it to a temp file and displays it using Notepad, WordPad or Paint application. Results in Text, Binary and Verbose output format are displayed in Notepad. RTF result is displayed using WordPad. Captured bitmap displayed by Paint. See ExGUI source code for details.

Possible errors are:

· “Rectangle is out of window” or “Incorrect arguments” is returned if source definition is incorrect.

· ”Incorrect BMP file. Only 1, 4, 8, 16, 24, 32 bpp Windows BMP files are supported” is returned if specified bitmap file has unsupported format.

· “Initialization failed” or “Termination failed” is returned in case of unsuccessful calls to TextractInit() or TextractTerm() functions.

· “File <file name> not found” is returned if file could not be found.

ExGUI source code is in the Examples\Src\ExGUI\ subfolder.

There is an example for each combination of source type (BMP file or screen rectangle), destination type (file or memory) and output format (text, binary, RTF, verbose). Examples are named like Src_Dest_Output.EXE, where

Src – either Bmp that stands for BMP source file or Scr that stands for capturing of image from the screen.

Dest – either File that stands for output to a file or Memo that stands for storing the result to a memory.

Output – can be Acsii, Binary, Rtf or Verbose. It defines output format.

All other fine-tuning is available by source file modification.

All sources are made clear for easy adopting. The examples look like the one below:

// Scr_File_Verbose.Cpp

// Source of recognition: Captured rect of screen

// Destignation results of recognition: Output file

// Output format of recognition: Verbore

#include <memory.h>

#include <stdio.h>

#include “../Textract.H”

bool errorIf(TextractSuccess code){

if(code < 0){

switch(code){

case tsReject: puts(“User rejected the operation”); break;

case tsBadArgs: puts(“Incorrect argumens”); break;

case tsOutOfWindow: puts(“Rectangle is out of window”); break;

case tsIniNotFound:

printf(“File %s not found\n”, TextractIniFileName()); break;

case tsBaseNotFound:

printf(“File %s not found\n”, TextractBaseFileName()); break;

case tsBitmapNotFound:

printf(“File %s not found\n”, TextractBitmapFileName());break;

case tsCrash: puts(“Internal error”); break;

}

return false;

} else

return true;

}

int main(void){

if(!errorIf(TextractInit()))

return -1;

if(!errorIf(Textract(

TextractSource(0,0,200,100),

TextractDest(“test.dat”),

TextractDestFormat(dfVerbose | dfBol | dfEol | dfSpace |

dfChar | dfFont | dfCharHex | dfCharFont)

)))

return -2;

errorIf(TextractTerm());

return 0;

}

To build an example load Workspaces\ExSimple.DSW project file for MS VC++.

Another way is to run NMAKE <selected_example.mak> from the command line.

TxtrCtl ActiveX control (TxtrOCX.DLL)

To install/uninstall TxtrCtl ActiveX control you may use either regsvr32.exe or tstcon32.exe: regsvr32 TxtrOCX.DLL

This command line installs TxtrCtl.

regsvr32 /u TxtrOCX.DLL

This command line uninstalls(unregisters) TxtrCtl.

[propget, id(1), helpstring(“File name for recognition result. Empty for store result in memory”)] HRESULT Dest([out, retval] BSTR *pVal);

[propput, id(1), helpstring(“File name for recognition result. Empty for store result in memory”)] HRESULT Dest([in] BSTR newVal);

Allows to set or to inquire a filename for the recognition results. If it contains empty string the results are saved in memory.

Visual Basic example:

TxtrCtl1.Dest = “C:\results.dat”

Sets a file C:\results.dat for saving recognition results.

Dim L As String

L = TxtrCtl1.Dest

Returns a file name for the result of recognition.

[propget, id(2), helpstring(“Boolean values describing output format details”)] HRESULT Flags([out, retval] long *pVal);

[propput, id(2), helpstring(“Boolean values describing output format details”)] HRESULT Flags([in] long newVal);

Allows to set or inquire additional flags for Binary (dfBinary) or Verbose (dfVerbose) formats. Full list of flags see in Textract control flags and output formats section.

Visual Basic example:

TxtrCtl1.Flags = dfBol And dfEol and dfChar

Sets the dfBol, dfEol and dfChar flags for binary or verbose format.

Dim L As Long

L = TxtrCtl1.Flags

Returns flags for binary or verbose format

[propget, id(3), helpstring(“0-Text, 1-RTF, 2-Verbose 3-Binary,

4-Bmp”)] HRESULT TextType([out, retval] long *pVal);

[propput, id(3), helpstring(“0-Text, 1-RTF, 2-Verbose, 3-Binary,

4-Bmp”)] HRESULT TextType([in] long newVal);

Set or return output format. For more information about formats see Textract control flags and output formats section.

Visual Basic example:

TxtrCtl1.TextType = 3

Sets the Verbose format.

Dim Type As Long

Type = TxtrCtl1.TextType

Gets the type of an output data format.

[propget, id(15), helpstring(“Boolean values providing scroll for target window”)] HRESULT Scrolling([out, retval] BOOL *pVal);

[propput, id(15), helpstring(“Boolean values providing scroll for target window”)] HRESULT Scrolling([in] BOOL newVal);

Capture window with scrolling.

Visual Basic example:

If GetInt(Text_Handle, hHandleWnd) Then Exit Sub

TxtrCtl1.Scrolling = True

TxtrCtl1.ReadWindow hHandleWnd

Textract.INI description. Fine Tuning of Font Database settings.

Textract.INI file is used to configure Textra.EXE and Textract.DLL. It is located in %AppData%\Structurise folder. Textract.INI is an ASCII text file and it can be edited in any text editor. Textract.INI is divided into sections and entries:

[Section_name]

Entry_Name=Entry_Value

where Enrty_Value is a string or a number.

The sections and entries of Textract.INI are:

[Options]

Language=%sE

Database Path=C:\Textract\Textract.Pat

[Recognition]

;Recognition/RecognitionMode – 0-Auto, 1-ForceSmartMatch, 2-ForceExactMatch
RecognitionMode=0

;Recognition/NeverTurnOffClearType – 0 – turn off ClearType if needed, 1-Never turn off ClearType
NeverTurnOffClearType=0

;Recognition/RecognitionLanguage – English, German, Spanish etc.
RecognitionLanguage=English

Include1=MS Sans Serif,Arial*,Helv*,Times*,Courier*,MS Serif*,

Fixedsys, Terminal,System,Lucida*,Verdana,Tahoma

Include2=*

Exclude=* CE,Wingdings*,Webdings*,Marlett*,Algerian*,Brush Script*,

Matura MT Script*,MT Extra*,Playbill*,Symbol*,CommonBullets

Italic=0

Bold=1

Underlined=1

Chars=\21-\7F

Sizes=8-12,14

Multicolor=0

Multifont=0

Line align=10

[Textra]

Service data. Please do not edit!

[Log]

Service data. Please do not edit!

[Debug]

Service data. Please do not edit!

Font database filename is defined in [Options] Database Path entry.

[Recognition], [Log], [Debug] sections are used by Textract recognition module.

Fonts included in font pattern database are set in [Recognition] Include1 and Include2 entries (asterisk as option). A set of excluded fonts is defined in [Recognition] Exclude entry.

To include Italic, Bold and Underlined styles in font pattern database define them in [Recognition] Italic, [Recognition] Bold and [Recognition] Underlined entries: 1 – enabled, 0 – disabled.

A set of national font characters is defined in [Recognition] Chars entry by hexadecimal codes of chars. It is possible to specify individual values and range of values: \21,\22,\23 is equal to \21-\23.

The Font Sizes included in font database, is defined in [Recognition] Sizes entry. Values of height are defined in logical units. It is possible to specify individual values and range of values.

[Recognition] RecognitionMode (new in version 4.0) changes the OCR engine used by Texract. Zero mean both engines are used and the best result is send to the calling program. One forces use of the new flexible OCR engine capable to recognize smoothed (ClearType-ed) or non-Windows font. Two forces the use of old exact match engine which is faster and more accurate but not as flexible.

[Recognition] NeverTurnOffClearType disables ClearType turning off and on if set to one.

[Recognition] RecognitionLanguage specifies human language used by the smart/flexible OCR engine.

Textract.NET (.NET Framework)

TextractNET assembly exposes two classes NetTextract and NetTextractItem.

Class NetTextractItem is a storage for captured characters when Binary format is used. It contains the following public fields that completely corresponds to the TextractItem’s members:

Data Members
Type	Defines item type. It is the same as TextractItemType: itChar, itSpace, itLineStart, itLineTerm, itFont (enum NetTextractItemType).
OffsetX OffsetY	Cahracter offset relative to upper left corner of the source.
FontIndex	This member is unique font index. It can be used to compare fonts of different characters for equivalence. It is valid for itChar item.
FontName	Specifies font face/style name. This member is valid for itChar and itFont items.
Ch	Specifies the captured character. This member is valid for itChar item.
Color	Specifies color of the captured character in RGB format – RRGGBB. This member is valid for itChar item.
Pitch	Specifies font pitch size. This member is valid for itChar and itFont items.
Spacing	Specifies spacing between characters, measured in pixels. This member is valid for itSpace item.
IsExactSpacing	True if the spacing is proper in accordance with space width for this font face/pitch. False if the spacing is not equal to the space width for this font face/pitch. This member is valid for itSpace item.

Class NetTextract implements all the Textract functionality. The implementation has similar to Textract interface. The workflow with Textract.NET is the following:

1. Initialise Textract.NET by NetTextract.Init() before calling any other method.

2. Set source of text capturing using SetSource…() methods.

3. Capture text in desired format either to memory or file using Capture…() methods.

4. Perform steps 2,3 as many times as required.

5. Terminate Textract.NET by NetTextract.Term().

You can call any other NetTextract methods between steps 1 and 5 such as building font pattern database.

Class NetTextract has the following interface (using C# notation):

Initialisation

NetTextract()

Default constructor. Constructs a NetTextract object.

static Init()

Initialises Textract.DLL. It must be a first call to the class prior to using other functions of the library.

static Term()

Terminates Textract.DLL. It must be called at the end of library using to clean up.

static Build()

Builds the font database. Build() is a silent version without user’s interface.

static BuildWithDialog()

Builds the font database. BuildWithDialog() is a silent version without user’s interface.

Specifying source of text capture

void SetSourceBmpFile

( string bmpFileName )

This method specifies source bitmap to capture text from.

bmpFileName is a path to the desired bitmap file. The path can be relative or absolute.

void SetSourceRect

( intl, intt, intr, int b )

This method specifies the rectangle screen area to capture text from.

l, t, r, b– are left, top, right and bottom screen coordinates in pixels of the rectangle.

void SetSourceWnd

( IntPtr hwnd )

This method specifies the handle of a window to capture text from.

hwnd– is Windows API handle to the window.

void SetSourceScrollWnd

( IntPtr hwnd )

This method defines that text will be captured from the entire window with vertical scrolling including hidden parts that are scrolled through.

hwnd– is Windows API handle to the window.

void SetSourceDesktopWnd()

This method specifies the desktop window as a window to capture text from.

void SetSourceTopWnd

(string class, string title )

This method defines that text will be captured from the top-level window with specified window class and caption (title).

class

is a string that defines window class name.

title

is a string that defines window caption (title).

void SetSourceDeepWnd

(string class, string title )

This method defines that text will be captured from the child window that has a desktop window as a parent window.

class

is a string that defines window class name.

title

is a string that defines window caption (title).

void SetSourceSubWnd

(string class, string title )

This method defines that text will be captured from the first child window of the window that matches specified window class name and caption.

class

is a string that defines window class name.

title

is a string that defines window caption (title).

void SetSourceSubDeepWnd

(string class, string title )

This method defines that text will be captured from the child window that matches specified window class name and caption.

class

is a string that defines window class name.

title

is a string that defines window caption (title).

void SetSourceFindLargestWindow()

This method defines that text will be captured from the largest child window of an active window.

Text capture methods (store results to memory)

CaptureText

(refstring strRes )

Captures plain text and puts it to the strRes.

Returns NetTextractSuccess error code.

CaptureRtf

(refstring strRes )

Captures RTF text and puts it to the strRes.

Returns NetTextractSuccess error code.

CaptureVerbose

(refstring strRes,

NetTextractDestFormat fmt )

Captures text in verbose format and puts it to the strRes.

fmt

is a NetTextractDestFormat that specifies output format. It can be any combination of the format flags: dfBol dfEol dfSpace dfChar dfFont dfCharHex dfCharFont dfCharColor.

Returns NetTextractSuccess error code.

CaptureBinary

(ref ArrayList TextractItems, NetTextractDestFormat fmt )

Captures text in binary format as array of NetTextractItems of and stores result to the TextractItems array.

fmt

is a NetTextractDestFormat that specifies output format. It can be any combination of the format flags: dfBol dfEol dfSpace dfChar dfFont dfCharHex dfCharFont dfCharColor.

Returns NetTextractSuccess error code.

Text capture methods (store results to a file)

CaptureTextToFile

(string file)

Captures plain text and stores it to the specified file.

file

is a string that specifies file path.

Returns NetTextractSuccess error code.

CaptureRtfToFile

(string file)

Captures RTF text and stores it to the specified file.

file

is a string that specifies file path.

Returns NetTextractSuccess error code.

CaptureVerboseToFile

(string file,

NetTextractDestFormat fmt )

Captures text in verbose format and stores it to the specified file.

file

is a string that specifies file path.

fmt

is a NetTextractDestFormat that specifies output format. It can be any combination of the format flags: dfBol dfEol dfSpace dfChar dfFont dfCharHex dfCharFont dfCharColor.

Returns NetTextractSuccess error code.

CaptureBinaryToFile

(string file,

NetTextractDestFormat fmt )

Captures text in binary format as array of NetTextractItems and stores them to the specified file.

file

is a string that specifies file path.

fmt

is a NetTextractDestFormat that specifies output format. It can be any combination of the format flags: dfBol dfEol dfSpace dfChar dfFont dfCharHex dfCharFont dfCharColor.

Returns NetTextractSuccess error code.

Helpers

staticstring IniFileName()

Returns initialisation file name.

staticstring BaseFileName()

Returns font database file name.

staticstring BitmapFileName()

Returns last bitmap file name.

staticstring GetErrorInfo

( NetTextractSuccess ts )

Returns error string for specified error code.

is an error code.

Example of using Scenario.NET in C# application is implemented in ScenarioTestNET application. The key code example is the following:

////////////////////////////////////////////////////////////////////////

using StructuRise;

// Initialize Textract.NET in Form’s constructor

public FormTextractTest()

{

. . .

NetTextract.Init()

}

// define source and capture text

void buttonCapture_Click(object sender, System.EventArgs e)

{

. . .

// create NetTextract Object

NetTextract textr = new NetTextract();

. . .

// set capture source

textr.SetSourceRect( left, top, right, bottom );

. . .

// capture text to a string and display it

string strRes = string.Empty;

if (textr.CaptureText( ref strRes ) == NetTextractSuccess.tsOK)

DisplayResult( strRes );

. . .

}

// Terminate Textract.NET in overridden OnClosing()

override void OnClosing( CancelEventArgs e )

{

NetTextract.Term();

}

////////////////////////////////////////////////////////////////////////

Textract SDK User Manual

version 5.0

About Textract

License agreement. Redistribution policy

Textract Installation Pack.

Textract Uninstall

Textract control flags and output formats

Textract.DLL

Description

Textract.DLL

Textract.DLL

Textra.EXE

Textract.DLL

TxtrCtl ActiveX control (TxtrOCX.DLL)

Textract.INI description. Fine Tuning of Font Database settings.

Textract.NET (.NET Framework)