TOCR API Reference
Version 5.1

Information in this document is subject to change without notice.  No part of this document may be reproduced or transmitted in any form or by any means without the express written permission of Transym Computer Services Ltd.

Copyright  2020 Transym Computer Services Ltd.  All rights reserved.

 1.	Introduction
This document provides reference information for the TOCR API.  The format of definitions used is Visual C. This document should be read in conjunction with other TOCR documentation.

The API provides the ability to pass TIFF, PDF or DIB files to a service process to be recognised.  DIBs may also be placed on the clipboard, or passed as a memory mapped file.  Whichever method is used the X and Y resolutions must either be zero or must be between (and not equal to) 25 and 2000 dots per inch.

New things in Version 5.0: TOCR now recognises many more characters (see section 3 Recognised Characters).
To accommodate these extra characters there is a new interface (_EG) which uses Unicode codepoints as well as codepoints internal to TOCR.  The internal characters between 33 and 255 are identical to V4.0 for compatibility reasons. The remaining internal characters 256 to 607 represent the Unicode characters required for all the European languages including Greek and Cyrillic and further Latin characters for mainly eastern European countries + Turkey.

Version 5 is able to return font information (face or family name, italic or underline).

TOCR can now return the bitmap used for recognition, as a memory mapped file.  To support this there are new routines TOCRExtraInfGetMMF and TOCRGetJobStatusEx2.

Please see document “TOCR PDF API Reference” for information on facilities for PDF files.

The user may also choose one of nine algorithms for converting colour images to monochrome prior to OCRing.

New things in Version 4.0: TOCR is now x64 compatible.  This has required a new function TOCRDoJob2  and structure TOCRJOBINFO2.  The interface is backwards compatible for x86 however some methods are deprecated in x86 and will not work in x64 (and may not be supported in the future).  These are: TOCRDoJob used to pass a memory mapped file handle (use TOCRDOJOB2), TOCRSetConfig & TOCRGetConfig to pass as string (use TOCRSetConfigStr & TOCRGetConfigStr).

New things in Version 3.2: TOCRSetConfig and TOCRGetConfig have been extended.  Thread safety has been enhanced.  An AutoLex feature has been added.  When set TOCR will decide whether Lex processing should be applied to the image. Four speed options have added to allow the user to choose the speed/accuracy trade-off.  See the Remarks section of TOCRPROCESSOPTIONS for last two new features.

New things in Version 3.0: TWAIN scanner support has been added, all errors can be logged to a file, the OCR engine priority can be changed, the maximum image size is now 12,000 in X and Y regardless of resolution, conflicts when installing TOCR as a system service have been resolved.  Two new functions have been added TOCRSetConfig and TOCRGetConfig which allow some INI file configuration settings to be changed at run time.  A flag has been added to better process OCRB (at the expense of other fonts), see the Remarks section of TOCRPROCESSOPTIONS.

TOCRPROCESSOPTIONS_EG
The TOCRPROCESSOPTIONS_EG structure describes the options, which may be set for job processing.

typedef struct tagTOCRPROCESSOPTIONS_EG
	long		StructId;
	BYTE		InvertWholePage;
	BYTE		DeskewOff;
	BYTE		Orientation;
	BYTE		NoiseRemoveOff;
	BYTE		ReturnNoiseOn;
	BYTE		LineRemoveOff;
	BYTE		DeshadeOff;
	BYTE		InvertOff;
	BYTE		SectioningOn;
	BYTE		MergeBreakOff;
	BYTE		LineRejectOff;
	BYTE		CharacterRejectOff;
	BYTE		ResultsReference;
	BYTE		LexMode;
	BYTE		OCRBOnly;
	BYTE		Speed;
	BYTE		FonStyleInfoOff;
	BYTE		filler1[3];
	long		CCAlgorithm;
	float		CCThreshold;
	long		CGAlgorithm;
	long		ExtraInfFlags;
	LangStatusMap	DisableLangs;
	BYTE		filler2[2];
	CharStatusMap	DisableCharW;
 } TOCRPROCESSOPTIONS_EG;

Members
StructId
This should be 0.
InvertWholePage
If this flag is set (non-zero) the “Job” will be inverted prior to processing.
DeskewOff
If this flag is set (non-zero) no attempt will be made to deskew the job.
Orientation
This should be set to one of
TOCRJOBORIENT_AUTO	detect orientation and rotate automatically
TOCRJOBORIENT_OFF		don't rotate
TOCRJOBORIENT_90		 90 degrees clockwise rotation
TOCRJOBORIENT_180		180 degrees clockwise rotation
TOCRJOBORIENT_270		270 degrees clockwise rotation
NoiseRemoveOff
If this flag is set (non-zero) no attempt will be made to remove noise from the job.
ReturnNoiseON
	If this flag is set (non-zero) then characters rejected as noise will be returned and will be flagged as
	Noise 
LineRemoveOff
If this flag is set (non-zero) no attempt will be made to remove lines from the job.
DeshadeOff
If this flag is set (non-zero) no attempt will be made to remove shading from the job.
InvertOff
If this flag is set (non-zero) individual zones in a job will not be analysed for auto inversion.
SectioningOn
If this flag is set (non-zero) the page will be sectioned and results will be returned in “read order”.
MergeBreakOff
If this flag is set (non-zero) no attempt will be made to merge broken characters or break merged characters.
LineRejectOff
If this flag is set (non-zero) no attempt will be made to reject lines of noise.
CharacterRejectOff
If this flag is set (non-zero) no attempt will be made to reject characters that are very poor matches.
ResultsReference
This value should be one of
TOCRRESULTSREFERENCE_SELFREF
XPos and YPos are self-relative.  That is, they refer to the minimum found on the page after any rotation and deskewing (this is for backwards compatibility with previous Versions). 
TOCRRESULTSREFERENCE_BEFORE
XPos and YPos refer to the positions on the original page BEFORE any rotation or deskewing is performed (whether manual or automatic). 
TOCRRESULTSREFERENCE_BETWEEN
XPos and YPos refer to the positions on the original page AFTER any rotation is performed but before deskewing.
TOCRRESULTSREFERENCE_AFTER
XPos and YPos refer to the positions on the original page AFTER any rotation and deskewing is performed (see also TOCRExtraInfGetMMF).
LexMode
This value is now unused: TOCR decides automatically whether lex processing will help.
OCRBOnly
If this flag is set (non-zero) the OCR engine will assume the whole image is in the OCRB font and provide greater accuracy for this font (at the expense of other fonts). No character codes >= 256 will be recognised if the flag is set.
Speed
This value governs the speed/accuracy trade-off and should be one of 
TOCRJOBSPEED_SLOW
TOCRJOBSPEED_MEDIUM
TOCRJOBSPEED_FAST
TOCRJOBSPEED_EXPRESS
FontStyleInfoOff
If this flag is set (non-zero) TOCR will not return font style information in the results.  This will provide a speed saving.
Filler1
	Unused.
CCAlgorithm
This value should be one of the TOCRJOBCC_... values to select the algorithm to use to convert colour images to monochrome (see below).
CCThreshold
The threshold for the colour conversion algorithm, in the range 0 to 1, to apply as follows:
TOCRJOBCC_AVERAGE
	Set white if (R+G+B) >= Threshold * 255
TOCRJOBCC_LUMA_BT601
	Set white if  (0.299*R+0.587*G+0.114*B) >= Threshold * 255
TOCRJOBCC_LUMA_BT709
	Set white if  (0.2126*R+0.7152*G+0.0722*B) >= Threshold * 255
TOCRJOBCC_DESATURATION
	Set white if (max(R,G,B)+min(R,G,B))/2 >= Threshold * 255
TOCRJOBCC_DECOMPOSITION_MAX
	Set white if max(R,G,B) >= Threshold * 255
TOCRJOBCC_DECOMPOSITION_MIN
	Set white if min(R,G,B) >= Threshold * 255
TOCRJOBCC_RED
	Set white if R >= Threshold * 255
TOCRJOBCC_GREEN
	Set white if G >= Threshold * 255
TOCRJOBCC_BLUE
	Set white if B >= Threshold * 255
CGAlgorithm
This value should be one of the TOCRJOBCG_... values to select the algorithm to use to convert grey images to monochrome. For example, using TOCRJOBCG_HISTOGRAM.A histogram of the whole page is generated and the strongest signal is considered to be the background (white). No factors are available.
ExtraInfFlags
If this value is set to
	TOCREXTRAINF_RETURNBITMAP1
TOCR will create a bitmap that represents the OCR’d image (after deskewing, noise removal etc.).
This bitmap can be accessed by TOCRExtraInfGetMMF when it is available, see TOCRGetJobStatusEx2.
DisableLangs (0 to 45)
	This is an array of  TOCR recognisable languages to disable when recognition is performed.
The elements should be zero if the language is to be recognised. It has no effect on DisableCharW in this context.
Filler2
	Unused
DisableCharW(0 to 607)
This is an array of internal TOCR codepoints which are to be disabled when recognition is performed.
The elements should be zero if the character is to be recognised.
Remarks
If CCAlgorithm and CCThreshold are both zero, colour conversion reverts to previous versions of TOCR (which is CCAlgorithm = 0 and CCThreshold = 0.5).

TOCRRESULTSITEMEX_EG

The TOCRRESULTSITEMEX_EG structure describes variable information of returned results.

typedef  struct  tagTOCRRESULTSITEMEX_EG
{
	float		Confidence;
	unsigned short	StructId;
	unsigned short	OCRCharWUnicode;
	unsigned short	OCRCharWInternal;
	unsigned short	FontID;
	unsigned short	FontStyleInfo;
	unsigned short	XPos;
	unsigned short	YPos;
	unsigned short	XDim;
	unsigned short	YDim;
	unsigned short	YDimRef;
	unsigned short	Noise;
	TOCRRESULTSITEMEXALT_EG	Alt[5];
} TOCRRESULTSITEMEX_EG;
Members
StructId
This should be 0.
OCRCharWUnicode
The Unicode codepoint (UTF16) of a recognised character.
OCRCharWInternal
The TOCR internal code for the recognised character.
FontID
A TOCR font number (or zero if no font information has been requested or identified).
FontStyleInfo
Either
TOCRRESULTSFONT_NOTSET		character style is not specified
Or a combination of
TOCRRESULTSFONT_NORMAL		character is Normal
TOCRRESULTSFONT_ITALIC		character is Italic
Confidence
Confidence in the accuracy of the character (for non-space characters only).
XPos
The horizontal position of the character in pixels.
YPos
The vertical position of the character in pixels.
XDim
The width of the character in pixels.
YDim
The height of the character in pixels.
YDimref
The expected height of the character if it was an H.
Noise
	Set if normal noise removal would have removed this character.
Alt(0 To 4)
Up to 4 alternative characters plus the returned OCRCharW variants above.  See TOCRRESULTSITEMEXALT_EG.
Remarks
See the remarks section in TOCRRESULTSITEM_EG.  Alt(0 To 4) may contain up to 4 alternative characters to the chosen “best” OCRCharW variants specified above which will always be in element zero (Alt(0)). This is provided so that its factor can be compared to the alternatives.

 2.	Acknowledgements
Transym Computer Services Ltd acknowledge the use of Sam Leffler’s libtiff library. The corresponding copyright notice is included below.

Copyright (c) 1988-1996 Sam Leffler
Copyright (c) 1991-1996 Silicon Graphics, Inc.

Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that (i) the above copyright notices and this permission notice appear in all copies of the software and related documentation, and (ii) the names of Sam Leffler and Silicon Graphics may not be used in any advertising or publicity relating to the software without the specific, prior written permission of Sam Leffler and Silicon Graphics.

THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.