Screen Scraping Library

 

Screen Text Capture OCR Library

 

User’s Manual

 

Copyright © 1995-2016 Binary Valley, Inc

 

 

 

 

 

 

 

Screen Scraping Library support: support@ScreenScrapingLibrary.com

Screen Scraping Library on the web: http://www.ScreenScrapingLibrary.com/

 

 

 

This document describes Screen Scraping Library. The software is provided to you in accordance with your license agreement.

 

Screen Scraping Library allows grabbing text from Windows 98/95/NT/2000/XP screen, under the control of another program. Screen Scraping Library is a development tool in the form of DLL and EXE, which can be integrated by the software developer into another product or software solution.

 

Software QA departments can use Screen Scraping Library to grab text from testing applications and compare the captured text with intended screen content.

 

Screen Scraping Library is well suited for corporate environment as an application connectivity tool, to feed an application with text from another text "source" application. Screen Scraping Library is especially useful if this source application is a third-party; the source application cannot be changed or hard and time-wasting to change, and has no adequate embedded support for communication.

 

Screen Scraping Library can grab text from any part of any application, even from clipboard and OLE-unaware applications e.g.: from folder trees, file lists, database reports, text contents of messages and dialog boxes, menus, status lines, legacy systems. The technology is copyrighted 1995-2016 Binary Valley, Inc

 

Part of Screen Scraping Library, OCRSDKcl.EXE is a standalone console mode Win32 application with a simple, yet powerful, command line interface. OCRSDKcl.EXE can recognize text from the screen or a bitmap file and store it into a file in plain text, Rich Text Format (RTF) and proprietary binary and verbose text formats.

 

Another part of Screen Scraping Library, OCRSDK.DLL, has a simple API to call from programs that are written in C++, Visual Basic, Power Builder or any other DLL-aware programming language. You can use it as a building block of the whole product, which requires text capturing, like driving you proprietary hardware by text, captured from a legacy system. OCRSDK.DLL can store results into memory or into a file.

 

Screen Scraping Library contains an MFC example, which shows how to use all features of OCRSDK.DLL. This example is a great help for the developer to play with the DLL before implementing actual code. Screen Scraping Library also contains C++ console mode examples of the DLL use, which show the simplest possible form of use of each input and output mode. Both, MFC and console mode, examples are supplied with source texts and they are ready to use as compiled EXEs.

 

Screen Scraping Library also contains TxtrCtl, which is a 32-bit Windows DLL based ActiveX control OCROCX.DLL is written using ATL C++ language. TxtrCtl, which is built on COM-based technology, provides a convenient way of using all OCRSDK.DLL functionality. OCROCX.DLL is compatible with any environment that supports the use of ActiveX control, such as Visual C++, Visual Basic, Power Builder, etc.

 

There is a Visual Basic 5 example of using TxtrCtl ActiveX control.

 

You can order Screen Scraping Library Commercial online, by phone, fax, check, mail order or purchase order. Screen Scraping Library license includes 30 day money back guarantee.

Please visit Screen Scraping Library web page at http://www.ScreenScrapingLibrary.com/ to order Screen Scraping Library.

 

You can download Screen Scraping Library Trial for free from the Screen Scraping Library web page, valid for 45 days. You should also consider trying Scrape Text utility to evaluate the recognition quality and the speed of the technology. Scrape Text and Screen Scraping Library use the same technology engine for capturing text. Scrape Text Trial Version is included into Screen Scraping Library.

 

 

 

 

If you have any questions or comments please contact us: e-mail (preferred): support@ScreenScrapingLibrary.com, phone: 206-338-5863

Table of Contents:

 

Introduction. Screen Scraping Library purpose, scenario examples, contents, ordering

License agreement. Redistribution policy

Screen Scraping Library installation. Description of installed files

Screen Scraping Library Uninstall

Screen Scraping Library control flags and output formats

OCRSDKcl.EXE

      Context of use of OCRSDKcl.EXE

      Command line parameters

      Operational environment. Font database, INI

      Examples of command line use

OCRSDK.DLL

      Context of use of OCRSDK.DLL

      API description for each function

      Operational environment. Font database, INI file

      MFC example of OCRSDK.DLL use

            Interrelations between example dialog and Screen Scraping Library control flags

            How to control the example

            How to compile example

      Console mode examples

            Interrelations between examples and Screen Scraping Library control flags

            How to compile example

TxtrCtl ActiveX control (OCROCX.DLL)

      Installation/uninstallation of TxtrCtl

      Context of use of OCROCX.DLL

      TxtrCtl properties and methods reference

      Visual Basic example of TxtrCtl use

OCRSDK.INI file description

      General options

      Font database and capturing options

      Log file support options

      Debug options

License agreement. Redistribution policy

End-User License Agreement.

This End-User License Agreement (EULA) is a legal agreement between you (either an individual or a single entity) and Binary Valley, Inc for 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 Binary Valley, Inc 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 Binary Valley, Inc 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.

Screen Scraping Library Trial Edition License Agreement

You are granted the right to use the trial edition of this software, without any functional 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.

 

 

Screen Scraping Library Commercial Edition License Agreement

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 Binary Valley, Inc for any reason, please write us or email at support@ScreenScrapingLibrary.com

Screen Scraping Library installation. Description of installed files

Install Directory: Screen Scraping Library is installed into a specified folder (you’ll be asked to specify it at the beginning of the installation process.) No other files are installed elsewhere; no files are installed into \Windows and \Windows\System folders. All installed files are described below.

 

Capturing engine

OCRSDK.DLL - Text capture library in the form of a dynamic link library.

OCRSDKcl.EXE - Text capture module in the form of a Win32 console mode executable.

OCROCX.DLL - TxtrCtl ActiveX control.

OCRSDK.INI - An INI file to control DLL and EXE.

 

Development support

!Readme.Txt - A short description of the package.

OCRSDK.RTF - Screen Scraping Library user’s manual. (This document).

OCRSDK.H - A C/C++ header file, with API for OCRSDK.DLL.

OCRSDK.LIB - A stub library for C/C++ linker to link to OCRSDK.DLL.

ScrapeText.EXE – Scrape Text Trial Version, installation package. (Run to install).

 

MFC example for OCRSDK.DLL

ExGUI.EXE - A compiled example of DLL use, based on MFC.

ExGUI\ - A 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

 

Console mode simple examples for OCRSDK.DLL

For each example out of total 16, there is an executable (.EXE) compiled example in the root folder and sample source (.CPP) file, project (.DSP) file and make (.MAK) file in the ExSimple\ subfolder. Examples are described in OCRSDK.DLL section of this user’s manual.

 

Compiled example 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

ExSimple\ - source folder for these examples.

   ExSimple.dsp, ExSimple.dsw - project files.

   Xxx_Yyy_Zzz.Cpp, Xxx_Yyy_Zzz.Dsp, Xxx_Yyy_Zzz.Mak - C++ source file, project file and make file for each example.

   ExSimple.pl - perl script, that is used to generate .cpp, .dsp and .mak files for each example

   ExSimple.mpp - C++ pattern, used by ExSimple.pl to generate example .cpps

 

Visual Basic 5 example of TxtrCtl ActiveX control

VBTxtr.EXE - compiled VB5 example of TxtrCtl ActiveX control use

ExVB\ - source folder for the example

   frmVBTxtr.frm, frmVBTxtr.frx, OCRSDK.bas, frmSrcBmp.frm - source files

   VBTxtr.vbp - project file

Screen Scraping Library Uninstall

Screen Scraping Library installs all files into one folder and it’s subfolders. This folder is specified at installation time, the subfolders are described above.

To uninstall Screen Scraping Library, remove the installation folder, subfolders and all their files.

Screen Scraping Library control flags and output formats

OCRSDK.DLL and OCRSDKcl.EXE get the input image from a BMP file or from a specified screen rectangle (OCRSDK.DLL also supports getting the image from a specified window), then recognise the text from this image and then store the result in one out of 4 output data formats.

DLL can store the result into memory or into a file;

EXE can store the result only into a file.

 

This section describes output format details and associated control flags for this 5 formats:

1      plain text format - /ascii, dfText

2      RTF format - /rtf, dfRtf

3      verbose text format - /verbose, dfVerbose.
Flags to control verbose format:
/bol /eol /space /char /font /charhex /charfont /charcolor
dfBol dfEol dfSpace dfChar dfFont dfCharHex dfCharFont dfCharColor

4      binary format - /binary, dfBinary

5      bitmap format - /bmp, dfBmp

 

Plain text format

The result is a plain ASCII text. Terminated with trailing 0, if stored by DLL into memory. If the text is stored into a file the trailing 0 is absent. The text is properly spaced and divided into lines by CR/LF pairs (standard for Microsoft operating systems). Font face, pitch size, style, colour information and exact location of characters on the screen/bitmap aren’t present  in this format.

 

/ascii - command line parameter for OCRSDKcl.EXE.

dfText - a flag for OCRSDK.DLL format parameter of function OCR().

Xxx_Yyy_Ascii.Exe - console mode examples that show the use of this format.

 

RTF format

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

 

/rtf - command line parameter for OCRSDKcl.EXE.

dfRtf - a flag for OCRSDK.DLL format parameter of function OCR().

Xxx_Yyy_Rtf.Exe - console mode examples that show the use of this format.

 

Verbose text 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 this sequence of elements. Each line is terminated with CR/LF pair.

 

/verbose - command line parameter for OCRSDKcl.EXE.

dfVerbose - a flag for OCRSDK.DLL format parameter of function OCR().

Xxx_Yyy_Verbose.Exe - console mode examples, that demonstrate the use of this format.

 

Format of verbose output lines.

 

BOL <x> <y> - Begin Of the Line.

<x> and <y> are decimal specifiers of line position on the image, relative to the upper left corner.

 

EOL - End Of the Line.

 

CHAR <char> <hex> <x> <y> <pitch> <fontName> <color> - character description.

<char> - a character, as is.

<hex> - hexadecimal code of the character (e.g. 4B or 2E.)

<x> and <y> - offset of the character sign place relative to the upper left corner of the image.

<pitch> - pitch size of the font.

<fontName> - font face name. It can contain spaces in the name.

<color> - color of character in hex format %06X (RRGGBB).

 

SPACE <spacing> <e> - spacing in a line between characters.

<spacing> - decimal spacing between characters, measured in pixels.

<e> - EXACT if the spacing is proper in accordance with the space width for this font face/pitch. INEXACT if the spacing is not equal to the space width for this font face/pitch.

 

FONT <pitch> <fontName> - (is emitted if next character is a character of another font then previous one.) = this string is typed-out if  the next character is a character of another font then the current one.  Also typed-out before the first CHAR of the output.

<pitch> - pitch size of the font

<fontName> - font face name. It can contain spaces in the name.

 

The description above shows the full form of the output. Some output lines and/or fields can be switched off using  the following flags:

/xxx  - to control OCRSDKcl.EXE command lines

dfXxx - to control output format argument of Screen Scraping Library function of OCRSDK.DLL.

If the flag is present, then the function outputs ‘---‘; if not - omits.

/bol, dfBol - ‘BOL lines’

/eol, dfEol - ‘EOL lines’

/space, dfSpace - ‘SPACE lines’

/char, dfChar - ‘CHAR lines’

/font, dfFont - ‘FONT lines’

/charhex, dfCharHex - ‘<hex> fields of CHAR lines’

/charfont, dfCharFont - ‘<pitch> and <fontName> fields of CHAR lines’

/charcolor, dfCharColor - ‘<color> field of CHAR lines’

 

 

Binary format

The result is a binary format, which keeps all the information gathered on recognition step. Captured data is considered as a sequence of lines, which consists of characters and spaces. Binary output format is an array of structures, describing this sequence of elements.

 

/binary - command line parameter for OCRSDKcl.EXE.

dfBinary - a flag for OCRSDK.DLL format parameter of function OCR().

Xxx_Yyy_Binary.Exe - console mode examples that show the use of this format.

 

Output array consists of structures, defined in Screen Scraping Library.H as a class OCRItem.

 

class OCRItem {

 public:

  OCRItemType Type :8;

  short OffsetX, OffsetY;

  unsigned short FontIndex;

  const char *FontName;

  char Ch;

  long Color;

  unsigned char Pitch;

 

  short Spacing;

  int IsExactSpacing : 8;

};

 

OCRItemType Type :8; - type of the array item. It can be one of  the following: itChar, itSpace, itLineStart, itLineTerm, itFont.-  this corresponds to CHAR, SPACE, BOL, EOL and FONT lines of verbose text format, which is described above.

short OffsetX, OffsetY; - for itChar and itLineStart, specifies the offset of the character or line relative to the upper left corner of the image.

unsigned short FontIndex; - for itChar, index of the font, unique for this font face/style. It can be used to compare fonts of different characters for equivalence.

const char *FontName; - for itChar and itFont, font face/style name.

char Ch; - for itChar, the captured character.

long Color; - for itChar, colour of the captured character in RGB format.

unsigned char Pitch; - for itChar, font pitch size

short Spacing; - for itSpace, spacing between characters, measured in pixels.

int IsExactSpacing : 8; - for itSpace, 1 - if the spacing is proper in accordance with space width for this font face/pitch. 0 - if the spacing is not equal to the space width for this font face/pitch.

 

This description shows a full form of the output. Some output items can be omitted by means of the following flags:

/xxx - to control OCRSDKcl.EXE command line,

dfXxx - to control output format argument of Screen Scraping Library function of OCRSDK.DLL.

 

If the flag is present, then the function outputs ‘---‘; if not - omits.

/bol, dfBol - ‘BOL lines’

/eol, dfEol - ‘EOL lines’

/space, dfSpace - ‘SPACE lines’

/char, dfChar - ‘CHAR lines’

/font, dfFont - ‘FONT lines’

 

Bitmap format

The result is a bitmap file in true-colour 24 bits per pixel unpacked Windows BMP format. Recognition is not used in this format, this is just a pure bitmap capture. For Bitmap format the appropriate file name extension -“.bmp” - will be appended to the file name string if the extension is omitted. To prevent this  put “.” as a trailing symbol in the file name.

 

/bmp - command line parameter for OCRSDKcl.EXE.

dfBmp - a flag for OCRSDK.DLL format parameter of function OCR().

OCRSDKcl.EXE

Context of use of OCRSDKcl.EXE

OCRSDKcl.EXE is a 32-bit Windows console mode application which realize the recognition functionality.

 

Command line parameters

/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 OCRSDK.INI file, in section [Options] entry Database Path. If this is not specified, OCRSDKcl.EXE will build the base in a current folder, with the name OCRSDK.PAT, and will add the path and the name of this file to INI [Options] Database Path.

 

/capture <ax> <ay> <bx> <by> - captures rectangle from the screen, recognises the text and stores the results into an output file.

ax,ay - bx,by - rectangle location.

ax,ay - inclusive, bx,by - exclusive. All co-ordinates are decimal.

outputReportFile - name of an output file, where the results are stored. Default file extension is not added.

 

/recognize <inputBitmapFile> - recognizes the bitmap, specified in a command line.

inputBitmapFile - BMP file in the 1, 4, 16, 24, 32  bits per pixel unpacked as well as RLE-encoded. If the extension is not specified in the command line .BMP is added.

 

Output file name and output format flags must be specified, when using  /capture and /recognize modes.

/ascii - for plain text output mode

/rtf - for RTF output mode

/verbose - for verbose text output mode

/binary - for binary output mode

 

For verbose text output format /bol, /eol, /space, /char, /font, /charhex, /charfont and /charcolor may be used.

For binary output format /bol, /eol, /space, /char and /font may be used.

 

Operational environment. Font database, INI file

At the beginning OCRSDKcl.EXE searches for the OCRSDK.INI file to load parameters. OCRSDKcl.EXE searches for the following folders:

1      current folder.

2      folder where OCRSDKcl.EXE is located.

3      \Windows folder.

 

If OCRSDK.INI cannot be found, OCRSDKcl.EXE is terminated with the following error message: "File OCRSDK.INI not found".

 

For /capture and /recognize modes, OCRSDKcl.EXE loads the font database file, specified in INI [Options] Database Path =<path>\OCRSDK.PAT. If this file is not found, OCRSDKcl.EXE is terminated with: "Font database OCRSDK.PAT not found". If this file is found, but invalid, font database will be rebuild automatically, an error message will not appear.

 

Examples of command line use

OCRSDKcl /build

Builds or rebuilds the font database OCRSDK.PAT.

 

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

Captures the screen area at location (0, 0) to (800, 600) and stores the result into "whole.txt" in plain text format.

 

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

Captures the screen area at location (2, 580) to (798, 600) and stores the result into "taskbar.rtf" in RTF format.

 

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

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

 

 

OCRSDK.DLL

Context of use of OCRSDK.DLL

OCRSDK.DLL is a 32-bit Windows dynamic-link library (DLL) which provides the recognition functionality.

<to be written>

 

API description for each function

OCRSDK.DLL API is a header file OCRSDK.H.

 

OCRExport OCRSuccess OCRInit();

OCRExport OCRSuccess OCRTerm();

- Initialises and terminates the library: You have to call OCRInit() to use other functions of the library; call OCRTerm to clean up. Multiple OCRInit()/OCRTerm() is allowed during one session. Init preloads the font database, Term frees some resources.

 

OCRExport OCRSuccess OCRBuild();

- Builds the font databse. OCRBuild is a silent version (without user’s interface).

OCRExport OCRSuccess OCRBuildWithDialog();

- OCRBuildWithDialog opens the dialog box to ask the user about building the font database, and shows process progress.

 

typedef long OCRSuccess;

  // success returning code for Screen Scraping Library functions

 

enum { // value definitions for OCRSuccess

  tsOK = 0,

  ...

 

Each Screen Scraping Library function returns a success code. Each function specifies possible return codes.

 

tsOK is returned if a function has been done properly.

tsReject is returned if the user rejected the operation.

tsBadArgs  is returned if function arguments are incorrect

tsBadBitmap is returned if  the bitmap file format isn’t supported. Screen Scraping Library supports files in the 1, 4, 16, 24, 32  bits per pixel unpacked as well as RLE-encoded.

tsOutOfWindow is returned if the  co-ordinates of a specified screen area are out of the desktop window.

tsIniNotFound is returned if an INI file isn’t found.

tsBaseNotFound is returned if  a font pattern database file isn’t found.

tsBitmapNotFound is returned if a Bitmap (BMP) file isn’t  found.

tsInitFailed OCRInit() is returned if the call to OCRInit() failed.

tsTermFailed OCRTerm() is returned if the call to OCRTerm() failed.

tsFormat is returned in case of an incorrect file format.

tsNoAccess is returned when a file cannot be accessed for reading and/or writing.

tsCrash is returned if  a Screen Scraping Library internal error occurs.

 

OCRExport const char *OCRIniFileName();

OCRExport const char *OCRBaseFileName();

OCRExport const char *OCRBitmapFileName();

 

Return name of the file, corresponding to the last operation. Useful for making qualified error descriptions.

 

OCRExport OCRSuccess OCR(OCRSource&, OCRDest&, OCRDestFormat);

 

Text capturing and recognition.

OCRSource class reference defines where to get a source image for recognition. It can be a file or an area of the screen, see details below.

OCRDest class reference defines where to store the results of recognition. It can be memory area or a file with a specified name, see details below.

OCRDestFormat specifies output format with the use of format flags dfText, dfRtf, etc , which are described in "Screen Scraping Library control flags and output formats" section.

 

class OCRSource {

 public:

  OCRSource();

  OCRSource& BmpFile(const char *bmpFileName);

  OCRSource& Wnd(HWND);

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

  OCRSource& DesktopWnd();

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

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

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

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

  OCRSource& FindLargestWindow();

 

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

  HWND W; // used if != NULL

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

};

 

OCRSource& BmpFile(const char *bmpFileName);

 

Specifies the file name of a bitmap, designed for recognition.

 

OCRSource& Wnd(HWND);

 

Specifies the handle of a window, designed for recognition.

 

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

 

Specifies the screen area, designed for recognition.

ax,ay and bx,by are upper left (inclusive) and lower right (exclusive) corners of area.

 

OCRSource& DesktopWnd();

 

Specifies the desktop window as a window designed for recognition.

 

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

 

Specifies the top-level window, with windowClass as a window class name and windowText as a window caption (title) name.

 

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

 

Specifies the child window with a desktop window as a parent window, with windowClass as the window class name and windowText as the window caption (title) name.

 

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

 

Specifies the child window in any match of a tree, with W as a parent window, with windowClass as the window class name and windowText as the window caption (title) name.

 

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

 

Specifies the child window in any match of a tree, with W as a parent window with windowClass as the window class name and windowText as the window caption (title) name.

 

OCRSource& FindLargestWindow();

 

Specifies the largest child window of an active window as a window for recognition.

 

OCRSource is used to specify what to capture and what to recognise.

Typical uses are:

OCR(OCRSource().BmpFile("MyImage.Bmp") ... to recognise the text from a  bitmap, captured from the screen some other way.

OCR(OCRSource().Rect(0,0, 100,200) ... to grab text from  a rectangle, located at (0,0) - (100,200).

OCRCapture(OCRSource()

  .TopWnd(NULL, "Inbox - Outlook Express")

  .SubDeepWnd("SysTreeView32", "") ... to grab text from the visible area of a window (HWND) with the class name SysTreeView32, find anywhere in the child windows (HWNDs) of top level window with a title "Inbox - Outlook Express". Methods DesktopWnd, TopWnd and DeepWnd... are designed to work together to specify the required window with known accuracy.

OCR(OCRSource().FindLargestWindow() ... to catch the largest visible subwindow on the screen. It's useful to capture terminal emulator window.

 

class OCRDest {

 public:

  OCRDest(const char *destFileName);

  OCRDest();

 

  const char *FileName; // NULL if area specifeid, else dest file name

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

  int AreaSize;

};

OCRExport OCRSuccess OCRDestFree(OCRDest&);

 

OCRDest  - is used to specify where to save captured results.

Typical uses:

OCR(... , OCRDest("Results.Txt") ...  to save results in a specified file.

 

OCRDest dest;

OCR(... , dest, ...);

... use dest.Area of size dest.AreaSize ...

OCRDestFree(dest);

to use results in memory. OCRDestFree is used to free memory, allocated for results of recognition, if memory output mode is used.

 

enum OCRDestFormat {

enum OCRItemType { ...

class OCRItem { ...

 

Specifies output formats and layouts of binary (dfBinary) or verbose (dfVerbose) modes. They are all described in "Screen Scraping Library control flags and output formats" section.

 

Operational environment. Font database, INI

OCRInit() searches for the OCRSDK.INI file to load parameters, see OCRSDKcl.EXE description.

If OCRSDK.INI cannot be found, tsIniNotFound is returned.

 

OCRInit() loads the font database file, specified in INI

[Options]

Database Path =<path>\OCRSDK.PAT.

If this file is not found, OCRInit returns tsPatNotFound.

 

MFC example of OCRSDK.DLL use

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

 

1      Click "Build font pattern database" button to build the font database. It must be created before any recognition. Note, that the database could be created by either OCRSDK.DLL or OCRSDKcl.EXE. "Build" asks to confirm rebuilding the database and calls OCRBuildWithDialog() function.

 

2      Recognition use example consists of these simple 4 steps:

3      Adjust the recognition source to be a screen rectangle, a bitmap (BMP) file or a window, by “Rectange” / “Bitmap file” / “Window” radio buttons. Specify the screen rectangle’s coordinates,  BMP file name or a window. ax,ay are upper left corner co-ordinates, inclusive, bx,by stand  for the lower right corner, exclusive.

4      Adjust the  recognition destination by “Memory” / “File” radio buttons. Specify the file’s name if File option used.

5      Adjust the output format. Output formats are described in "Screen Scraping Library control flags and output formats" section. 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 generate. For Verbose format, also specify CharHex and CharFont by putting a check in the according box.

6      Click "Recognize" button to recognize the image in accordance with the specified source, destination and output format. ExGUI creates OCRSource class instance, OCRDest class instance and calls OCR() function of OCRSDK.DLL for the actual operation. DLL captures the image from the specified screen area, the specified window or loads it from the BMP file. Then it recognizes the image. After that it gives the result in the specified output format. Then it puts it into memory or writes it into a file, in accordance with specified destination. Then ExGUI converts the returned data into text human-readable format, writes it to temp file and shows it using Notepad, WordPad text editors or MSPaint. For Text, Binary and Verbose output formats Notepad is used. For Rtf format WordPad is used. For Bitmap MSPaint is used. See ExGUI code for details.

ExGUI processes the success code returned from OCR() function and shows the error message if function fails. Possible errors:

7      A "Rectangle is out of window" or "Incorrect arguments" occur if source is incorrect.

8      A ”Incorrect BMP file. Only 1, 4, 8, 16, 24, 32 bpp Windows BMP files are supported” occurs if specified unsupported format of bitmap file in case of file recognition.

9      A “Initialization failed" or "Termination failed" occur in case the unsuccessful calls of  OCRInit() and OCRTerm() functions.

10  A “File <full specified file name> not found” occurs if one of INI, font database or bitmap files not found.


ExGUI sources are located in ExGUI\ folder. Use ExGUI.DSW project file to compile the example and try it under the debugger. Make sure that OCRSDK.DLL is available for the system to load when you start ExGUI.EXE.

 

Console mode examples

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

11  Src is Bmp or Scr, stands for BMP source file or for capturing an image from the screen.

12  Dest is File or Memo, stands for whether the result is being output to a file or to memory.

13  Output is Acsii, Binary, Rtf or Verbose.

 

All other fine tuning is hard-coded into sources. You may change the sources to try any combination.

 

All sources are very simple for better understanding. Here is an example of one of them.

 

=== Scr_File_Verbose.Cpp ===

// 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 "../Screen Scraping Library.H"

 

bool errorIf(OCRSuccess 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", OCRIniFileName()); break;

      case tsBaseNotFound:

        printf("File %s not found\n", OCRBaseFileName()); break;

      case tsBitmapNotFound:

        printf("File %s not found\n", OCRBitmapFileName());break;

      case tsCrash: puts("Internal error"); break;

    }

    return false;

  } else

    return true;

}

 

int main(void){

  if(!errorIf(OCRInit()))

    return -1;

  if(!errorIf(OCR(

    OCRSource(0,0,200,100),

    OCRDest("test.dat"),

    OCRDestFormat(dfVerbose | dfBol | dfEol | dfSpace |

                       dfChar | dfFont | dfCharHex | dfCharFont)

  )))

    return -2;

  errorIf(OCRTerm());

  return 0;

}

============================

 

Building examples

To build examples, load ExSimple\ExSimple.DSW project file into MS VC++.

Or run NMAKE <selected_example.mak> from the command line.

 

TxtrCtl ActiveX control (OCROCX.DLL)

Context of use of TxtrCtl

TxtrCtl is a 32-bit Windows DLL based ActiveX control. OCROCX.DLL is written, using ATL C++ language. OCROCX.DLL may be used with any environment that supports the use of ActiveX controls such as Visual C++, Visual Basic, Power Builder and other. OCROCX.DLL is needed in OCRSDK.DLL for its work. TxtrCt must be properly installed before using.

 

Installation/uninstallation of TxtrCtl

To install/uninstall TxtrCtl ActiveX control you may use either regsvr32, or tstcon32 program to register the control.

To install TxtrCtl, using regsvr32, use the following command line: regsvr32 OCROCX.DLL.

To uninstall TxtrCtl, using regsvr32, use the following command line: regsvr32 /u OCROCX.DLL. This command will unregister TxtrCtl control.

 

TxtrCtl properties and methods reference

All properties and methods of TxtrCtl ActiveX control are described here using IDL.

Examples of usage in Visual Basic are also available.

 

[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 file (name) for the results of recognition. If this property contains an empty string, then the results of the recognition are saved in memory.

 

Examples of use in Visual Basic:

 

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

 

Sets a file named C:\results.dat for result of recognition.

 

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 setting or querying additional flags for Binary (dfBinary) or Verbose (dfVerbose) formats. Full list of these flags are available in “Screen Scraping Library control flags and output formats” section.

 

Examples of use in Visual Basic:

 

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);

 

Allows setting or inquiring an output format. For more information about formats see “Screen Scraping Library control flags and output formats” section.

 

Examples of use in Visual Basic:

 

TxtrCtl1.TextType = 3

 

Sets the Verbose format.

 

Dim Type As Long

Type = TxtrCtl1.TextType

 

Gets the type of an output data format.

 

[propget, id(4), helpstring("Output Text or RTF")) HRESULT Text((out, retval] BSTR *pVal);

 

Returns the result of recognition. This property is read only. One of the following methods ReadScreen, ReadFile, ReadDesktopWindow, ReadLargestWindow, ReadWindow, ReadTopWindow, ReadDeepWindow must be called before inquiring this property.

 

Example of use in Visual Basic:

 

Dim Res As String

Res = TxtrCtl1.Text

 

(id(5), helpstring("Initialize Screen Scraping Library")) HRESULT Init();

(id(6), helpstring("Terminate Screen Scraping Library")) HRESULT Term();

 

Initializes and terminates the recognition module of ActiveX control.

 

Examples of use in Visual Basic:

 

TxtrCtl1.Init

TxtrCtl1.Term

 

(id(7), helpstring("Build font dictionary")) HRESULT Build(long lWithDialog);

 

Builds the font database. If  lWithDialog == 0 then runs the building process without showing a dialog window, if 1WithDialog ¹ 0 - shows a dialog window.

 

Example of use in Visual Basic:

 

TxtrCtl1.Build 0

 

(id(8), helpstring("Recognize text from screen")) HRESULT ReadScreen(long Ax, long Ay, long Bx, long By);

 

Captures text from the screen rectangle with co-ordinates (Ax, Ay) - (Bx, By) and recognizes it.

 

Example of use in Visual Basic:

 

TxtrCtl1.ReadScreen 0 0 400 90

 

(id(9), helpstring("Recognize text from bitmap file")) HRESULT ReadFile(BSTR BitmapFileName);

 

Loads BMP file BitmapFileName and recognizes it’s contents.

 

Example of use in Visual Basic:

 

TxtrCtl1.BitmapFileName “example.bmp”

 

(id(10), helpstring("Recognize text from desktop window")) HRESULT ReadDesktopWindow();

 

Recognizes the text from a desktop window.

 

Example of use in Visual Basic:

 

TxtrCtl1.ReadDesktopWindown

 

(id(11), helpstring("Recognize text from largest window")) HRESULT ReadLargestWindow();

 

Recognizes the text from the largest child window.

 

Example of use in Visual Basic:

 

TxtrCtl1.ReadLargestWindow

 

(id(12), helpstring("Recognize text from window with specified handle")) HRESULT ReadWindow(long W);

 

Recognizes the text from a window with a specified handle.

 

Example of use in Visual Basic:

 

TxtrCtl1.ReadWindow 1044

 

(id(13), helpstring("Recognize text from top window with specified class name and caption")) HRESULT ReadTopWindow(BSTR WindowClass, BSTR WindowCaption);

(id(14), helpstring("Recognize text from deep window with specified class name and caption")) HRESULT ReadDeepWindow(BSTR WindowClass, BSTR WindowCaption);

 

Recognizes the text from a window with a specified class name and caption name.

 

Example of use in Visual Basic:

 

TxtrCtl1.ReadTopWindow “SciCalc” “Calculator”

 

Visual Basic example of TxtrCtl use

VBTxtr is a VB5 example of using TxtrCtl ActiveX control that allows you to try it. User’s interface of  this example is the same as in ExGUI example. (See “MFC example of OCRSDK.DLL use” section.)

 Exploring all functions is available in VTBxtr, as it is in ExGUI, except the Binary output format, because VTBxtr doesn’t have a decoder from binary to plain text..

 

VBTxtr catches error exceptions raised in TxtrCtl ActiveX control and shows an error message if a function fails. Possible errors:

14  A "Rectangle is out of window" or "Incorrect arguments" occur if the source is incorrect.

15  A ”Incorrect BMP file. Only 24bit per pixel Windows BMP files are supported” occurs in case of file recognition if the specified bitmap format is not supported.

16  A “Initialization failed" or "Termination failed" occur in case the calls to  OCRInit() and OCRTerm() functions are unsuccessful.

17  A “File <full specified file name> not found” occurs if  INI, font database or bitmap file(s) are not found.

 

VBTxtr sources are located in ExVB\ folder. Use VBTxtr.vbp project file to compile the example and try it under the debugger. Make sure that the TxtrCtl ActiveX control is installed. For description of the installation procedure see “Installation/uninstallation of TxtrCtl” section. You should have WordPad on your machine, so the data returned in Text is shown properly.

 

OCRSDK.INI file description

OCRSDK.INI file is used to define the configuration of OCRSDKcl.EXE and OCRSDK.DLL. It may be present in current folder, folder where OCRSDKcl.EXE or OCRSDK.DLL is located, or in WINDOWS system folder as it was described in “Operational environment, Font database, INI file” topic. OCRSDK.INI is a plain text file and it’s contents may be changed using any text editor. OCRSDK.INI is a set of sections and entries that have the following format:

 

[Section_name]

Entry_Name=Entry_Value

 

[Section_name] is a section name

Entry_Name is an entry name

Enrty_Value is an entry value. Must be a string or a number.

 

Each section can contain several entries that are separated by a newline symbol (“\n”).

OCRSDK.INI uses the following sections and entries:

 

[Options]

Language=%sE

Database Path=C:\Screen Scraping Library\OCRSDK.Pat

 

[Recognition]

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]

...

 

[Log]

...

 

[Debug]

...

 

Font database file name is defined by reading INI [Options] Database Path entry.

If the pass is not specified, the program uses a default pass: <location of OCRSDK.DLL or OCRSDKcl.EXE>\OCRSDK.PAT.

 

[Recognition], [Log], [Debug] sections are used by the Screen Scraping Library recognition module.

A set of fonts, that includes fonts in font pattern database by building font database process, is defined in  [Recognition] Include1 and Include2 entries (asterisk is possible). A set of excluding fonts is defined in  [Recognition] Exclude entry.

Whether there are italic, bold and underlined styles enabled in the font pattern database is defined by [Recognition] Italic, [Recognition] Bold and [Recognition] Underlined entries: 1 - enabled, 0 - disabled.

A set of font chars is defined in [Recognition] Chars entry, using hexadecimal codes of chars. Possible entries: \21,\22,\23 is equal to \21-\23.

The height of fonts, included in font pattern database, is defined in [Recognition] Sizes entry. Values of height are defined in logical units. Individual values and range of values are possible.