vvEngAPI Class Reference
[Ocrxtrapi_public]

Optical Character Recognition Engine API Class. More...

#include <vvxtrAPI.h>

List of all members.

Public Member Functions

virtual ~vvEngAPI ()

Destructor.

virtual vvxtrStatus vvKill ()=0

Kill the engine.

virtual vvxtrStatus vvInitInstance ()=0

Initialize OCR engine instance.

virtual vvxtrStatus vvEndInstance ()=0

End OCR engine instance.

virtual vvxtrStatus vvStartOCRSes ()=0

Start an OCR session.

virtual vvxtrStatus vvEndOCRSes ()=0

End an OCR session.

virtual vvxtrStatus vvStartDoc ()=0

Start an output document.

vvxtrStatus vvStartDoc (int fileFormat)

Start an output document.

virtual vvxtrStatus vvSpoolDoc ()=0

Spool recognized data to the output doc.

virtual vvxtrStatus vvEndDoc ()=0

End the output document.

virtual vvxtrStatus vvAcquireDocMemory (void *memPtr, int bufsize)=0

Get the document output through memory.

virtual vvxtrStatus vvAcquireDocFile (const char *filename)=0

Get the document output as a file.

virtual vvxtrStatus vvCaptureSubimage ()=0

Capture a subimage.

vvxtrStatus vvCaptureSubimage (int regionID)

Capture a subimage.

virtual vvxtrStatus vvAcquireSubimageMemory (void *memPtr, int bufsize)=0

Get the image output through memory.

virtual vvxtrStatus vvAcquireSubimageFile (const char *filename)=0

Write the image output to a file.

virtual vvxtrStatus vvOpenImageFile ()=0

Open an input image document in the OCR engine.

vvxtrStatus vvOpenImageFile (const char *fileName)

Open the input image file passed as a parameter.

virtual vvxtrStatus vvCloseImageFile ()=0

Close the input image file currently open in the OCR engine.

virtual vvxtrStatus vvReadImageData ()=0

Read image data into the OCR engine.

virtual vvxtrStatus vvReadImageData (const struct vvxtrImage *img)=0

Read image data into the OCR engine.

virtual vvxtrStatus vvUnloadImage ()=0

Unload the page of input image data currently loaded in the OCR engine.

virtual vvxtrStatus vvPreprocess ()=0

Run preprocessing on the currently loaded image page.

virtual vvxtrStatus vvRecognize ()=0

Run recognition on the currently loaded image page.

virtual vvxtrStatus vvInitValues ()=0

Initialize engine values.

virtual vvxtrStatus vvGetStatus (const int key, vvxtr_stdarg *result)=0

Get engine status for the passed key.

vvxtrStatus vvSetValue (const int key, int value)

Set the integer value of the passed key in the engine.

vvxtrStatus vvSetValue (const int key, char *value)

Set the string value of the passed key in the engine.

vvxtrStatus vvGetValue (const int key, int *result)

Get an integer engine value.

vvxtrStatus vvGetValue (const int key, char **result)

Get a character or string engine value.

virtual vvxtrStatus vvGetState (vvxtr_state *resultState)=0

Get the engine state.

virtual vvxtrStatus vvGetCond (const vvxtr_cond c, int *result)=0

Get the value of an engine condition.

virtual vvxtrStatus vvSetHint (vvxtrHint hint, bool set=true)

Give the engine more information about its environment to possibly improve performance.

virtual bool vvGetHint (vvxtrHint hint)

Return the current setting of one of the hints.

virtual void vvSigHUP ()

A function to call when your client application receives a signal of type SIGHUP.

virtual const char * vvGetStatusString (vvxtrStatus status=VVXTR_PREVIOUS_ERROR)

Returns a string that describes the last error condition, if any detailed information about the error is available.

virtual vvxtrStatus vvGetVersion (vvxtrVersionLocationEnum loc, const char **ver)=0

Return the version.

virtual vvxtrStatus vvAddWordToLexicon (const char *word, int constraintId)=0

Add a word to a user lexicon.

virtual vvxtrStatus vvSetLexicalConstraints (int mode)=0

Set lexical constraints for an area.

virtual vvxtrStatus vvSetRegionProperties (void)=0

Set region information.

virtual vvxtrStatus vvForceRegionForeground (int foregroundColor)=0

Explicitly set the foreground photometric interpretation.

virtual vvxtrStatus vvRemoveRegion (void)=0

Remove a region.

Public Attributes

bool m_hints [vvNumberOfHints]

Current hint flags.

Detailed Description

Optical Character Recognition Engine API Class.

This class is the interface to using the OCR Shop XTR/API.

Use of the API generally consists of:

Making a sequence of "action" calls.
Setting "values" in the engine to control the actions.
Passing image data to the engine.
Receiving document and subimage data from the engine.

The basic sequence of actions is:

1. Initialization:

vvEngAPI::vvInitInstance Initialize the OCR instance.

vvEngAPI::vvStartOCRSes Start an OCR session, loading appropriate languages.

vvEngAPI::vvInitValues Initialize all "values".

2. Input image recognition:

vvEngAPI::vvOpenImageFile Open an input image file (required only for file input).

vvEngAPI::vvReadImageData Read a page of image data into the engine.

vvEngAPI::vvPreprocess Run preprocessing.

vvEngAPI::vvRecognize Run recognition.

vvEngAPI::vvUnloadImage Unload the image data from the engine.

vvEngAPI::vvCloseImageFile Close the input image file (required only for file input).

3. Output a document:

vvEngAPI::vvStartDoc Start an output document.

vvEngAPI::vvSpoolDoc Send data to the output document.

vvEngAPI::vvEndDoc Close the output document.

vvEngAPI::vvAcquireDocMemory Download the output document to an allocated memory block.

vvEngAPI::vvAcquireDocFile Download the output document to a file.

4. Output a subimage:

vvEngAPI::vvCaptureSubimage Create a subimage from the input image.

vvEngAPI::vvAcquireSubimageMemory Download the subimage to an allocated memory block.

vvEngAPI::vvAcquireSubimageFile Download the subimage to a file.

5. Close down the engine:

vvEngAPI::vvEndOCRSes End the OCR session.

vvEngAPI::vvEndInstance End the OCR instance.

vvEngAPI::vvKill Completely shut down the engine.

Before each action call, the appropriate values should be set in the engine to control the action's functionality.

See also:: vvEngAPI::vvSetValue

Opening and closing of the input image and the output document may be performed asynchronously, allowing for more complex results. For example, the one output document may remain open while multiple input images are recognized and output is spooled to the output document for each one.

The actions listed above do not have to be performed in the exact order specified. Please see the detailed description on state and the individual function documentation for more information.

Other API functions exist as well:

vvEngAPI::vvKill Shuts down the OCR engine completely; may be called regardless of current state.
vvEngAPI::vvGetStatus Get the status from the engine.
vvEngAPI::vvSetValue Set a value in the engine.
vvEngAPI::vvGetValue Get a value from the engine.
vvEngAPI::vvGetState Get the current engine state.
vvEngAPI::vvGetCond Get the value of a specific condition in the state.
vvEngAPI::vvGetStatusString Get the status string.

Handling values:

Values should be set before they will be used by the engine. Please see the list of engine values and the documentation in vvxtrDefs.h and the sample program.

Set values with the vvEngAPI::vvSetValue function, and read values using vvEngAPI::vvGetValue.

Values are usually strings or numbers. Strings are represented as char *:

When you pass a char* to vvEngAPI::vvSetValue, the engine will make its own copy of the passed string.

When you get a char* value with vvEngAPI::vvGetValue, the engine passes you a pointer to memory it is responsible for. Do not write to this memory or attempt to delete it. This memory is temporary and not guaranteed to remain unchanged after the next call to any API function.

Handling data:

Input and output data may always be handled through files or through passed memory blocks.

Input data:

You may open a file to use as input with the vvEngAPI::vvOpenImageFile, then you can read any page of that file using the vvEngAPI::vvReadImageData function call.

If you want to pass image data directly to the engine through memory, you can directly call vvEngAPI::vvReadImageData and pass the data, and you do not need to call vvEngAPI::vvOpenImageFile, since there is not a file to read.

The input image, whether passed as a file or through memory, must always be unloaded from the engine with the vvEngAPI::vvUnloadImage function call.

When an input file was opened, it must always be closed with the vvEngAPI::vvCloseImageFile function call.

Output data:

The output format value dm_out_text_format must be set before an output document is started. Available output formats are listed in the vvxtrOutTextFormatEnum.

An output document is created (vvEngAPI::vvStartDoc), written to (vvEngAPI::vvSpoolDoc), and closed (vvEngAPI::vvEndDoc) without respect to how it will be acquired (through memory or written to a file).

In the first method for acquiring an output document, you request the engine write it to a file with the vvEngAPI::vvAcquireDocFile function call.

In the second method for acquiring an output document, you request the output document be placed in memory by calling vvEngAPI::vvAcquireDocMemory, passing a pre-allocated block of memory. The document's size is available as soon as the output document is closed (vvEngAPI::vvEndDoc).

Subimage output works in a similar manner, except the creation of a subimage is atomic, being started and finished in the function call vvEngAPI::vvCaptureSubimage.

You can acquire a subimage and write it to a file using the vvEngAPI::vvAcquireSubimageFile function call.

You can acquire a subimage in memory by calling vvEngAPI::vvAcquireSubimageMemory, passing a pre-allocated block of memory. The subimage's size is available after the subimage is created (vvEngAPI::vvCaptureSubimage).

Both output documents and subimages are available for acquisition as long as a new output document has not been started, or a new subimage has not been captured, respectively, and while the OCR session continues.

Engine State and API call sequencing

Conditions:

Condition Abbreviation Value Description

C_READY Re 0x400 ready

C_OCRSESOPEN Se 0x200 OCR session is open

C_OUTDOCOPEN Ou 0x100 output document is open

C_FILEOPEN Fi 0x080 input image is open

C_IMAGELOADED Im 0x040 input page is open

C_PREPROCDONE Pr 0x020 preprocessing has been run on the current page

C_RECOGDONE Rc 0x010 recognition has been run on the current page

C_DOCREADY Do 0x008 output document is ready for acquisition

C_SUBIMAGEREADY Su 0x004 output subimage is ready for acquisition

C_ENGINEBUSY En 0x002 engine is currently busy

C_ERROR Er 0x001 error

See also:: vvxtrDefs.h

State table for actions:

vvEngAPI::vvInitInstance

  	Conditions of interest:  Re| Se| Ou|   Fi| Im| Pr| Rc|   Do| Su| En| Er		111 1111 1111 = 7FF
  	Required values:        !Re|!Se|!Ou|  !Fi|!Im|!Pr|!Rc|  !Do|!Su|!En|!Er		000 0000 0000 = 000
  	Change in state:         Re|---|---|  ---|---|---|---|  ---|---|---|---

vvEngAPI::vvEndInstance

  	Conditions of interest:	 Re|---|---|  ---|---|---|---|  ---|---| En| Er		100 0000 0011 = 403
  	Required values:         Re|---|---|  ---|---|---|---|  ---|---|!En|!Er		100 0000 0000 = 400
  	Change in state:        !Re|---|---|  ---|---|---|---|  ---|---|---|---

vvEngAPI::vvStartOCRSes

  	Conditions of interest:	 Re| Se|---|  ---|---|---|---|  ---|---| En| Er		110 0000 0011 = 603
  	Required values:         Re|!Se|---|  ---|---|---|---|  ---|---|!En|!Er		100 0000 0000 = 400
  	Change in state:        ---| Se|---|  ---|---|---|---|  ---|---|---|---

vvEngAPI::vvEndOCRSes

  	Conditions of interest:	 Re| Se|---|  ---|---|---|---|  ---|---| En| Er		110 0000 0011 = 603
  	Required values:         Re| Se|---|  ---|---|---|---|  ---|---|!En|!Er		110 0000 0000 = 600
  	Change in state:        ---|!Se|---|  ---|---|---|---|  !Do|---|---|---

vvEngAPI::vvStartDoc

  	Conditions of interest:	 Re| Se| Ou|  ---|---|---|---|  ---|---| En| Er		111 0000 0011 = 703
  	Required values:         Re| Se|!Ou|  ---|---|---|---|  ---|---|!En|!Er		110 0000 0000 = 600
  	Change in state:        ---|---| Ou|  ---|---|---|---|  ---|---|---|---

vvEngAPI::vvSpoolDoc

  	Conditions of interest:	 Re| Se| Ou|  ---| Im| Pr| Rc|  ---|---| En| Er		111 0111 0011 = 773
  	Required values:         Re| Se| Ou|  ---| Im| Pr| Rc|  ---|---|!En|!Er		111 0111 0000 = 770
  	Change in state:        ---|---|---|  ---|---|---|---|  ---|---|---|---

vvEngAPI::vvEndDoc

  	Conditions of interest:	 Re| Se| Ou|  ---|---|---|---|  ---|---| En| Er		111 0000 0011 = 703
  	Required values:         Re| Se| Ou|  ---|---|---|---|  ---|---|!En|!Er		111 0000 0000 = 700
  	Change in state:        ---|---|!Ou|  ---|---|---|---|   Do|---|---|---

vvEngAPI::vvAcquireDocMemory

  	Conditions of interest:	 Re| Se| Ou|  ---|---|---|---|   Do|---| En| Er		111 0000 1011 = 70B
  	Required values:         Re| Se| Ou|  ---|---|---|---|   Do|---|!En|!Er		110 0000 1000 = 608
  	Change in state:        ---|---|---|  ---|---|---|---|  ---|---|---|---

vvEngAPI::vvAcquireDocFile

  	Conditions of interest:	 Re| Se| Ou|  ---|---|---|---|   Do|---| En| Er		111 0000 1011 = 70B
  	Required values:         Re| Se| Ou|  ---|---|---|---|   Do|---|!En|!Er 	110 0000 1000 = 608
  	Change in state:        ---|---|---|  ---|---|---|---|  ---|---|---|---

vvEngAPI::vvCaptureSubimage

  	Conditions of interest:	 Re| Se|---|  ---| Im| Pr| Rc|  ---|---| En| Er		110 0111 0011 = 673
  	Required values:         Re| Se|---|  ---| Im| Pr| Rc|  ---|---|!En|!Er		110 0111 0000 = 670
  	Change in state:        ---|---|---|  ---|---|---|---|  ---| Su|---|---

vvEngAPI::vvAcquireSubimageMemory

  	Conditions of interest:	 Re| Se|---|  ---|---|---|---|  ---| Su| En| Er		110 0000 0111 = 607
  	Required values:         Re| Se|---|  ---|---|---|---|  ---| Su|!En|!Er		110 0000 0100 = 604 
  	Change in state:        ---|---|---|  ---|---|---|---|  ---|---|---|---

vvEngAPI::vvAcquireSubimageFile

  	Conditions of interest:	 Re| Se|---|  ---|---|---|---|  ---| Su| En| Er		110 0000 0111 = 607
  	Required values:         Re| Se|---|  ---|---|---|---|  ---| Su|!En|!Er		110 0000 0100 = 604 
  	Change in state:        ---|---|---|  ---|---|---|---|  ---|---|---|---

vvEngAPI::vvOpenImageFile

  	Conditions of interest:	 Re| Se|---|   Fi|---|---|---|  ---|---| En| Er		110 1000 0011 = 683
  	Required values:         Re| Se|---|  !Fi|---|---|---|  ---|---|!En|!Er		110 0000 0000 = 600
  	Change in state:        ---|---|---|   Fi|---|---|---|  ---|---|---|---

vvEngAPI::vvCloseImageFile

  	Conditions of interest:	 Re| Se|---|   Fi| Im|---|---|  ---|---| En| Er		110 1100 0011 = 6C3
  	Required values:         Re| Se|---|   Fi|!Im|---|---|  ---|---|!En|!Er		110 1000 0000 = 680
  	Change in state:        ---|---|---|  !Fi|---|---|---|  ---|---|---|---
  	Change in state:        ---|---|---|   Fi|---|---|---|  ---|---|---|---
  	Change in state:        ---|---|---|   Fi|---|---|---|  ---|---|---|---

vvEngAPI::vvReadImageData (from file)

  	Conditions of interest:	 Re| Se|---|   Fi| Im|---|---|  ---|---| En| Er		110 1100 0011 = 6C3
  	Conditions of interest:	 Re| Se|---|   Fi| Im|---|---|  ---|---| En| Er		110 1100 0011 = 6C3
  	Conditions of interest:	 Re| Se|---|   Fi| Im|---|---|  ---|---| En| Er		110 1100 0011 = 6C3
  	Required values:         Re| Se|---|   Fi|!Im|---|---|  ---|---|!En|!Er		110 1000 0000 = 680
  	Change in state:        ---|---|---|  ---| Im|---|---|  ---|---|---|---

vvEngAPI::vvReadImageData (from memory)

  	Conditions of interest:	 Re| Se|---|  ---| Im|---|---|  ---|---| En| Er		110 0100 0011 = 643
  	Required values:         Re| Se|---|  ---|!Im|---|---|  ---|---|!En|!Er		110 0000 0000 = 600
  	Change in state:        ---|---|---|  ---| Im|---|---|  ---|---|---|---

vvEngAPI::vvUnloadImage

  	Conditions of interest:	 Re| Se|---|  ---| Im|---|---|  ---|---| En| Er		110 0100 0011 = 643
  	Required values:         Re| Se|---|  ---| Im|---|---|  ---|---|!En|!Er		110 0100 0000 = 640
  	Change in state:        ---|---|---|  ---|!Im|!Pr|!Rc|  ---|---|---|---

vvEngAPI::vvPreprocess

  	Conditions of interest:	 Re| Se|---|  ---| Im|---|---|  ---|---| En| Er		110 0100 0011 = 643
  	Required values:         Re| Se|---|  ---| Im|---|---|  ---|---|!En|!Er		110 0100 0000 = 640
  	Change in state:        ---|---|---|  ---|---| Pr|---|  ---|---|---|---

vvEngAPI::vvRecognize

  	Conditions of interest:	 Re| Se|---|  ---| Im| Pr|---|  ---|---| En| Er		110 0110 0011 = 663
  	Required values:         Re| Se|---|  ---| Im| Pr|---|  ---|---|!En|!Er		110 0110 0000 = 660
  	Change in state:        ---|---|---|  ---|---|---| Rc|  ---|---|---|---

vvEngAPI::vvInitValues

  	Conditions of interest:	 Re| Se|---|  ---|---|---|---|  ---|---| En| Er		110 0000 0011 = 603
  	Required values:         Re| Se|---|  ---|---|---|---|  ---|---|!En|!Er		110 0000 0000 = 600
  	Change in state:        ---|---|---|  ---|---|---|---|  ---|---|---|---

Commands:

Partial state diagram:


                 ^ |
   vvEndInstance | | vvInitInstance
                 | |
                 | V
                 C_READY
                   ^
                   | vvStartOCRSes
                   | vvEndOCRSes
                   V
                 C_READY            vvStartDoc             C_READY
    -----------> C_OCRSESOPEN <--------------------------> C_OCRSESOPEN <--------
   |               |        ^       vvEndDoc               C_OUTDOCOPEN          |
   |               |        |                              ^     |               |
   |               |        |                              |     |               |
   |        vvRead |        |    vvOpenImageFile           |     | vvRead        |
   |         Image |        |    vvCloseImageFile          |     |  Image        |
   |          Data*|        |                              |     |   Data*       |
   |               |        V                              V     |               |
   |               |   C_READY      vvStartDoc    C_READY        |               |
   |---------------|-> C_OCRSESOPEN <-----------> C_OCRSESOPEN <-|---------------|
   |               |   C_FILEOPEN   vvEndDoc      C_FILEOPEN     |               |
   |               |   |                          C_OUTDOCOPEN   |               |
   |               |   |                                   |     |               |
   |               |   |                                   |     |               |
   |vvUnloadImage  |   |vvReadImageData*   vvReadImageData*|     |  vvUnloadImage|
   |               |   |                                   |     |               |
   |               |   |                                   |     |               |
   |               V   V                                   V     V               |
   |             C_READY            vvStartDoc             C_READY               |
   |------------ C_OCRSESOPEN <--------------------------> C_OCRSESOPEN ---------|
   |            (C_FILEOPEN)        vvEndDoc              (C_FILEOPEN)           |
   |             C_IMGLOADED                               C_IMGLOADED           |
   |               |                                       C_OUTDOCOPEN          |
   |               |                                           |                 |
   |               | vvPreprocess                 vvPreprocess |                 |
   |               |                                           |                 |
   |               V                                           V                 |
   |             C_READY                                   C_READY               |
   |             C_OCRSESOPEN       vvStartDoc             C_OCRSESOPEN          |
   |----------- (C_FILEOPEN) <--------------------------> (C_FILEOPEN) ----------|
   |             C_IMGLOADED        vvEndDoc               C_IMGLOADED           |
   |          -> C_PREPROCDONE                             C_PREPROCDONE         |
   |         |   ^ ^  |                                    C_OUTDOCOPEN <-       |
   |         |   | |  |                                        |   ^  ^   |      |
   |          ---  |  |                                        |   |   ---       |
   |               |  |                                        |   |             |
   |  vvPreprocess |  | vvRecognize                vvRecognize |   |vvPreprocess |
   |               |  |                                        |   |             |
   |               |  V                                        V   |             |
   |             C_READY                                   C_READY               |
   |             C_OCRSESOPEN       vvStartDoc             C_OCRSESOPEN          |
    ----------- (C_FILEOPEN) <--------------------------> (C_FILEOPEN)  ---------
                 C_IMGLOADED        vvEndDoc               C_IMGLOADED 
                 C_PREPROCDONE                             C_PREPROCDONE
                 C_RECOGDONE                               C_RECOGDONE
                   |  ^                                    C_OUTDOCOPEN
                   |  |                                        |   ^  
                    --                                          ---   
                  vvRecognize                              vvSpoolDoc
                                                           vvRecognize

Remarks:

* vvEngAPI::vvReadImageData can be called by two methods: one with the image structure passed as a parameter, the other after having opened a file. vvEngAPI::vvReadImageData can not be called with zero parameters if an input image file is not currently open.

vvEngAPI::vvAcquireDocFile and vvEngAPI::vvAcquireDocMemory may be called at any time C_OUTDOCOPEN is false, C_READY is true, and C_OCRSESOPEN is true. However, it will only be meaningful if an output document has been created through vvEngAPI::vvStartDoc and vvEngAPI::vvEndDoc.

vvEngAPI::vvAcquireSubimageFile and vvEngAPI::vvAcquireSubimageMemory may be called at any time C_READY is true and C_OCRSESOPEN is true. However, it will only be meaningful if an output subimage has been created through vvEngAPI::vvCaptureSubimage.

Definition at line 426 of file vvxtrAPI.h.

Constructor & Destructor Documentation

virtual vvEngAPI::~vvEngAPI ( ) [inline, virtual]

Destructor.

Definition at line 434 of file vvxtrAPI.h.

Member Function Documentation

virtual vvxtrStatus vvEngAPI::vvAcquireDocFile ( const char * filename ) [pure virtual]

Get the document output as a file.
Call this function after you have created an output document through the calls to vvEngAPI::vvStartDoc, vvEngAPI::vvSpoolDoc, and vvEngAPI::vvEndDoc. You must end the output document before you acquire it through this function.
This function writes the document output to a file, as specified by the passed filename. If the file already exists, it will be overwritten.

Precondition:
An output document must have been created and closed.

Parameters:

filename Name to use for output file.

Returns:
vvxtrStatus based on status

Referenced by outputDoc().

virtual vvxtrStatus vvEngAPI::vvAcquireDocMemory ( void * memPtr,

int bufsize

) [pure virtual]

Get the document output through memory.
Call this function after you have created an output document through the calls to vvEngAPI::vvStartDoc, vvEngAPI::vvSpoolDoc, and vvEngAPI::vvEndDoc. You must end the output document before you acquire it through this function.
You are responsible for allocating the memory passed to this function, and you are responsible for deleting the memory in your client program. Allocate memory before calling this function, using the size obtained through finding the dm_doc_memory_size data value, then pass a pointer to the allocated memory. The buffer size (bufsize) you pass should correspond to both dm_doc_memory_size and the amount of memory you allocated.

Precondition:
Sufficient memory must be allocated in the passed buffer.
An output document must have been created and closed.

Parameters:

memPtr Pointer to preallocated memory.

bufsize Size of the buffer pointed to by memPtr.

Returns:
vvxtrStatus based on status

Referenced by outputDoc().

virtual vvxtrStatus vvEngAPI::vvAcquireSubimageFile ( const char * filename ) [pure virtual]

Write the image output to a file.
After capturing a subimage, you can obtain the image data as a file by calling this function. If the file already exists, it will be overwritten.

Precondition:
An image must have been captured through a call to vvEngAPI::vvCaptureSubimage.
dm_out_graphics_format must be set before calling this function to set the format of the image data.

Parameters:

filename Output filename

Returns:
vvxtrStatus based on status

Referenced by outputImg().

virtual vvxtrStatus vvEngAPI::vvAcquireSubimageMemory ( void * memPtr,

int bufsize

) [pure virtual]

Get the image output through memory.
After capturing a subimage, you can obtain the image data through memory by calling this function.
You are responsible for allocating and later deleting the memory in the passed buffer.

Precondition:
An image must have been captured through a call to vvEngAPI::vvCaptureSubimage.
Sufficient memory must be allocated in the passed buffer by the client program. Find out the required memory size through the value dm_subimage_memory_size.
dm_out_graphics_format must be set before calling this function to set the format of the image data.

Parameters:

memPtr Pointer to allocated memory.

bufsize Size of the buffer pointed to by memPtr.

Returns:
vvxtrStatus based on status

Referenced by outputImg().

virtual vvxtrStatus vvEngAPI::vvAddWordToLexicon ( const char * word,

int constraintId

) [pure virtual]

Add a word to a user lexicon.
Multiple words may be added to a user lexicon. Words will be grouped into lexicons based on the constraintId.
The constraintId should be used to set the dm_region_lexical_constraint_id or the dm_word_lexicon_id. The constraintId is associated with a page or a region through vvEngAPI::vvSetLexicalConstraints.

Parameters:

word Word to add the the user lexicon.

constraintId Specifies a group of user lexicon words; use with dm_region_lexical_constraint_id; set ::dm_wordlist_id to this before calling vvEngAPI::vvSetLexicalConstraints.

Returns:
vvxtrStatus

vvxtrStatus vvEngAPI::vvCaptureSubimage ( int regionID ) [inline]

Capture a subimage.
This is a helper function that sets the current region to the passed regionID, before calling vvEngAPI::vvCaptureSubimage. (It automatically calls vvSetValue() for dm_current_region.)

Returns:
vvxtrStatus based on status

Definition at line 685 of file vvxtrAPI.h.
References dm_current_region, vvCaptureSubimage(), vvSetValue(), vvxtr_stdarg, and vvxtrStatus.

virtual vvxtrStatus vvEngAPI::vvCaptureSubimage ( ) [pure virtual]

Capture a subimage.
This function is the first step in obtaining image data for output. First, set which region you wish to capture using the value dm_current_region. Then call this function. After this function completes, you can obtain the requested image data through vvEngAPI::vvAcquireSubimageFile or vvEngAPI::vvAcquireSubimageMemory.

Precondition:
You must set dm_current_region before calling this function.
You may also wish to set dm_output_img_source before calling this function.

Returns:
vvxtrStatus based on status

Referenced by outputImg(), and vvCaptureSubimage().

virtual vvxtrStatus vvEngAPI::vvCloseImageFile ( ) [pure virtual]

Close the input image file currently open in the OCR engine.
This function closes the currently open input image file, releasing the engine to open another input image file in the future.
This function must be called while an image file is open (image files are opened with the function vvEngAPI::vvOpenImageFile); you should not call this function if you are reading image data directly from memory rather than from an input file. Note that before the image file may be closed, you must unload any currently loaded page of image data with a call to vvEngAPI::vvUnloadImage.

See also:
vvEngAPI::vvOpenImageFile
vvEngAPI::vvReadImageData
* vvEngAPI::vvUnloadImage

Precondition:
An input image file must be open.

Returns:
vvxtrStatus based on status

Referenced by processOneDocument().

virtual vvxtrStatus vvEngAPI::vvEndDoc ( ) [pure virtual]

End the output document.
After you are done spooling output and are ready to acquire your output, you end the output document by calling this function. At this point, you can no longer spool to the output, and you can call vvEngAPI::vvAcquireDocMemory or vvEngAPI::vvAcquireDocFile in order to acquire a copy of the output document in your client program.
After vvEndDoc is called, the output document will remain in the engine until a new output document is started or the session is ended.
Memory management for the output document is handled internally in the engine; you do not need to be concerned with it in relation to this function.

Precondition:
An output document must be open.

Returns:
vvxtrStatus based on status

Referenced by outputDoc().

virtual vvxtrStatus vvEngAPI::vvEndInstance ( ) [pure virtual]

End OCR engine instance.

Precondition:
An OCR instance must have been started.

Returns:
vvxtrStatus based on status

Referenced by runOCR().

virtual vvxtrStatus vvEngAPI::vvEndOCRSes ( ) [pure virtual]

End an OCR session.

Precondition:
An OCR session must be open.

Returns:
vvxtrStatus based on status

Referenced by runOCR().

virtual vvxtrStatus vvEngAPI::vvForceRegionForeground ( int foregroundColor ) [pure virtual]

Explicitly set the foreground photometric interpretation.
Sets the photometric interpretation of the current region and processes the image to match the set interpretation.
If the passed foreground color matches the current setting, the image within the region remains unchanged, otherwise, the image within the region is inverted in order to agree with the passed color.
This function assumes the photometric interpretation is correct prior to the function call.
This function does not affect image output.
Uses the value of: dm_current_region

Parameters:

foregroundColor Foreground color (black or white) (use vvxtrRegionForegroundEnum)

Returns:
vvxtrStatus

virtual vvxtrStatus vvEngAPI::vvGetCond ( const vvxtr_cond c,

int * result

) [pure virtual]

Get the value of an engine condition.

Parameters:

c The function will look up the value of this condition. (Possible values are C_READY, C_OCRSESOPEN, C_OUTDOCOPEN, C_FILEOPEN, C_IMAGELOADED, C_PREPROCDONE, C_RECOGDONE, C_DOCREADY, C_SUBIMAGEREADY, C_ENGINEBUSY, and C_ERROR.)

result The function will write the value of condition c here.

Returns:
vvxtrStatus based on status

See also:
Engine State and API call sequencing

virtual bool vvEngAPI::vvGetHint ( vvxtrHint hint ) [inline, virtual]

Return the current setting of one of the hints.

Parameters:

hint Hint to query (vvxtrHint).

Returns:
The current hint setting.

Definition at line 1027 of file vvxtrAPI.h.
References m_hints.

virtual vvxtrStatus vvEngAPI::vvGetState ( vvxtr_state * resultState ) [pure virtual]

Get the engine state.

Parameters:

resultState The function will write the current engine state here; see vvxtr_state.

Returns:
vvxtrStatus based on status

See also:
vvxtr_state to decipher the returned state bit string.
Engine State and API call sequencing

virtual vvxtrStatus vvEngAPI::vvGetStatus ( const int key,

vvxtr_stdarg * result

) [pure virtual]

Get engine status for the passed key.

Parameters:

key The key for which we want the status. See vvxtrStatusEnum.

result The function will write the key's status here.

Returns:
vvxtrStatus based on status

virtual const char* vvEngAPI::vvGetStatusString ( vvxtrStatus status = VVXTR_PREVIOUS_ERROR ) [inline, virtual]

Returns a string that describes the last error condition, if any detailed information about the error is available.

:

Returns:
A temporary string pointer. The string will often be invalidated on the next API call.

Definition at line 1048 of file vvxtrAPI.h.
References VVXTR_ERR_BAD_LANGUAGE, VVXTR_ERR_BUFFER_TOO_SMALL, VVXTR_ERR_CONNECTION_FAILED, VVXTR_ERR_COULD_NOT_CONVERT_DEPTH, VVXTR_ERR_CREATE_LANG_GROUP, VVXTR_ERR_END_SESSION_FAILED, VVXTR_ERR_ENDINSTANCE_FAILURE, VVXTR_ERR_ENG_OUT_OF_MEMORY, VVXTR_ERR_ENGINE_KILLED, VVXTR_ERR_GETTING_IMG_REGION, VVXTR_ERR_HOST_LOOKUP_FAILED, VVXTR_ERR_IMG_ACQ_FAILED, VVXTR_ERR_INITINSTANCE_FAILURE, VVXTR_ERR_INV_PDF_FORMAT, VVXTR_ERR_INV_SUBIMG_FORMAT, VVXTR_ERR_INVALID_PAGE, VVXTR_ERR_INVALID_REGION_ID, VVXTR_ERR_INVALID_SHAPE_PACK_PATH, VVXTR_ERR_INVALID_STATE, VVXTR_ERR_INVALID_SYNTAX, VVXTR_ERR_INVALID_UOR_COUNT, VVXTR_ERR_INVALID_UOR_STRING, VVXTR_ERR_LOAD_LANG_FAILED, VVXTR_ERR_MISSING_LANG, VVXTR_ERR_NO_DOC, VVXTR_ERR_NO_FEATURE, VVXTR_ERR_NO_INPUT, VVXTR_ERR_NO_INPUT_FILE_SPECIFIED, VVXTR_ERR_NO_LICENSE, VVXTR_ERR_NO_LICENSE_MANAGER, VVXTR_ERR_NO_SUBIMAGE, VVXTR_ERR_NOENGINE, VVXTR_ERR_NOT_IMPLEMENTED, VVXTR_ERR_OPEN_CHAR_SET_FAILURE, VVXTR_ERR_OPENING_LANG_PACK, VVXTR_ERR_OPENING_OUTPUT_FILE, VVXTR_ERR_OUTPUT_INV_REGION, VVXTR_ERR_PDF_END_OUTPUT, VVXTR_ERR_PDF_IMG_OUTPUT, VVXTR_ERR_PP_FAILED, VVXTR_ERR_READONLY_VALUE, VVXTR_ERR_RECOGNITION_FAILED, VVXTR_ERR_REGION_ECLIPSED, VVXTR_ERR_REGION_HANDLER, VVXTR_ERR_REMOVE_FILE_FAILED, VVXTR_ERR_SET_DEF_LEX_CONSTRAINTS, VVXTR_ERR_SET_OPTIONS_FAILED, VVXTR_ERR_SET_REGION_UNSUCCESSFUL, VVXTR_ERR_START_SESSION_FAILED, VVXTR_ERR_SYNCHRONIZATION, VVXTR_ERR_TRANSFER_FAILED, VVXTR_ERR_UNABLE_TO_LOAD_IMAGE_FILE, VVXTR_ERR_WRITE_OUTPUT_FAILED, and VVXTR_PREVIOUS_ERROR.

vvxtrStatus vvEngAPI::vvGetValue ( const int key,

char ** result

) [inline]

Get a character or string engine value.

Parameters:

key The key for which we want the value in the engine.

result The function will write the key's value here.

Returns:
vvxtrStatus based on status

See also:
vvxtrEngineVariables

Definition at line 972 of file vvxtrAPI.h.
References vvGetValue(), vvxtr_stdarg, and vvxtrStatus.

vvxtrStatus vvEngAPI::vvGetValue ( const int key,

int * result

) [inline]

Get an integer engine value.

Parameters:

key The key for which we want the value in the engine.

result The function will write the key's value here.

Returns:
vvxtrStatus based on status

See also:
vvxtrEngineVariables

Definition at line 959 of file vvxtrAPI.h.
References vvxtr_stdarg, and vvxtrStatus.
Referenced by outputDoc(), outputImg(), processOneDocument(), and vvGetValue().

virtual vvxtrStatus vvEngAPI::vvGetVersion ( vvxtrVersionLocationEnum loc,

const char ** ver

) [pure virtual]

Return the version.

Parameters:

loc Specifies whether to return the version of the local or remote system (see vvxtrVersionLocationEnum).

ver version

Returns:
vvxtrStatus

virtual vvxtrStatus vvEngAPI::vvInitInstance ( ) [pure virtual]

Initialize OCR engine instance.
vvInitInstance should be called after starting an OCR session and at any point within an OCR session where you would like to reset the values. It is NOT required to call vvEngAPI::vvInitInstance prior to recognition of every file.

Precondition:
An OCR session must be started.

Returns:
vvxtrStatus based on status

Referenced by runOCR().

virtual vvxtrStatus vvEngAPI::vvInitValues ( ) [pure virtual]

Initialize engine values.

Returns:
vvxtrStatus based on status

Referenced by runOCR().

virtual vvxtrStatus vvEngAPI::vvKill ( ) [pure virtual]

Kill the engine.
vvKill should not normally be called. It is an asynchronous exit, so only use it if you need to exit for an unexpected reason or if the engine hangs.

Returns:
vvxtrStatus based on status

Referenced by CloseDown().

vvxtrStatus vvEngAPI::vvOpenImageFile ( const char * fileName ) [inline]

Open the input image file passed as a parameter.
This is a helper function that integrates the vvEngAPI::vvSetValue call in order to implicitely set the value of dm_in_filename. See the documentation for vvEngAPI::vvOpenImageFile.

Parameters:

fileName The file to open.

Returns:
vvxtrStatus based on the status of the file open or of the vvEngAPI::vvSetValue call.

Definition at line 759 of file vvxtrAPI.h.
References dm_in_filename, vvOpenImageFile(), vvSetValue(), vvxtr_stdarg, and vvxtrStatus.

virtual vvxtrStatus vvEngAPI::vvOpenImageFile ( ) [pure virtual]

Open an input image document in the OCR engine.
This function opens an input image document file. A page of the input image document must be still opened before the engine can process any image data. This function should be called once for each input image file.
See the list of supported input file formats.

Precondition:
dm_in_filename must be set before this function is called, so that the engine knows what image file to open.
An input image file cannot currently be open.

Returns:
vvxtrStatus based on status

Referenced by openImageDocument(), and vvOpenImageFile().

virtual vvxtrStatus vvEngAPI::vvPreprocess ( ) [pure virtual]

Run preprocessing on the currently loaded image page.
vvEngAPI::vvPreprocess should be called for every new image loaded into the engine, because it is an important step in the OCR process, where the engine segments the image and runs image processing over the image data in order to improve the ultimate OCR results.
Preprocessing is separate from recognition so that it can be run multiple times before recognition, if desired. In addition, preprocessing could be run without recognition at all, if for example, someone wanted to extract the image regions from a document but didn't care about recognizing text. However, calling vvEngAPI::vvPreprocess once and then vvEngAPI::vvRecognize once is by far the most common usage.
The preprocessing functions used in this step are intended as an aid to optical character recognition during the recognition step, and are not intended to affect or in any way clean up image output you may generate.

Precondition:
Image data must be loaded in the OCR engine (see vvEngAPI::vvReadImageData).
All preprocessing options should be set before this function is called. See all the values starting with "dm_pp_".

Returns:
vvxtrStatus based on status

Referenced by processOnePage().

virtual vvxtrStatus vvEngAPI::vvReadImageData ( const struct vvxtrImage * img ) [pure virtual]

Read image data into the OCR engine.
This function loads a page of input image data from the passed image structure into the OCR engine. It provides an alternative method for loading image data into the OCR engine, by allowing you to directly place the image data into memory and instead of reading it from a file.
After this function call, the loaded image data may be processed with, for example, vvEngAPI::vvPreprocess and then vvEngAPI::vvRecognize.
(Note: When this function is used, vvEngAPI::vvOpenImageFile does NOT need to be called first.)
Only one page of data can be handled at a time through this function.
You are responsible for memory management of the the passed vvxtrImage data structure.
Please see vvxtrSample2.cc for an example of using this function.

Precondition:
No image data can currently be loaded in the OCR engine.

Returns:
vvxtrStatus based on status

virtual vvxtrStatus vvEngAPI::vvReadImageData ( ) [pure virtual]

Read image data into the OCR engine.
This function reads one page of the currently open image file and loads it into the OCR engine in preparation for OCR processing. After this function call, the loaded image data may be processed with, for example, vvEngAPI::vvPreprocess and then vvEngAPI::vvRecognize.

Precondition:
The value dm_in_curr_page should be set before this function is called so that the engine knows which page of the input image file to read.

Returns:
vvxtrStatus based on status

Referenced by processOneDocument().

virtual vvxtrStatus vvEngAPI::vvRecognize ( ) [pure virtual]

Run recognition on the currently loaded image page.
This function runs optical character recognition on the currently loaded image data; it is the step where the image data is converted into text and formatting information internally.
When the recognition step is run, the recognized text is stored internally and can be accessed by generating output (see vvEngAPI::vvWriteOutput). Each time vvRecognize is called, the internal buffer of recognized text is cleared before it is written; recognized text from previous calls to vvRecognize is no longer available.

Precondition:
Image data must be loaded in the OCR engine (see vvEngAPI::vvReadImageData).
Preprocessing must have been run on this image data (see vvEngAPI::vvPreprocess).
Set all recognition options before calling this function.

Returns:
vvxtrStatus based on status

Referenced by processOnePage().

virtual vvxtrStatus vvEngAPI::vvRemoveRegion ( void ) [pure virtual]

Remove a region.
Removes the current region, as specified by the dm_current_region value.

Precondition:
dm_current_region must be set prior to this call.

Returns:
vvxtrStatus

virtual vvxtrStatus vvEngAPI::vvSetHint ( vvxtrHint hint,

bool set = true

) [inline, virtual]

Give the engine more information about its environment to possibly improve performance.
Not all hints will have an effect.

See also:
vvxtrHint

Parameters:

hint Hint to add or remove (vvxtrHint).

set True to set the hint. False to remove the hint.

Returns:
vvxtrStatus - VV_OK on success.

Definition at line 1018 of file vvxtrAPI.h.
References m_hints, and vvxtrStatus.
Referenced by runOCR().

virtual vvxtrStatus vvEngAPI::vvSetLexicalConstraints ( int mode ) [pure virtual]

Set lexical constraints for an area.
For a specific area, one or more of these lexical constraints may be set:

character set

language

word list

The character set should be set in the dm_char_set value. If dm_char_set is NULL, then the character set lexical constraint will not be set.
The language(s) should be set in the dm_language value. If it is NULL, then the language lexical constraint will not be set.
The word list should be set up using vvEngAPI::vvAddWordToLexicon and setting ::dm_wordlist_id to the constraintId passed to the function. If ::dm_wordlist_id is -1, then the word list lexical constraint will not be set.
Lexical constraints may be set for the page or for a specific region. Lexical constraints for a specific region will override those set for the page. Specify the area through the value dm_focus_area and dm_current_region (when dm_focus_area == vvFocusAreaRegion).

Parameters:

mode Specifies whether the lexical constraints should be added or replaced for this area.

See also:
vvxtrLexicalConstraintModeEnum.

Returns:
vvxtrStatus

virtual vvxtrStatus vvEngAPI::vvSetRegionProperties ( void ) [pure virtual]

Set region information.
Set properties of the region specified by dm_current_region.
A new region may be created by setting region properties for an unused region id.
Note that if two regions overlap, one will obscure the other, based on the regions' values for dm_region_stacking.

Precondition:
These values will be read by this function and should be set as desired before calling this function:

dm_region_type (vvxtrRegionTypeEnum)
dm_region_subtype (vvxtrRegionSubtypeEnum)
dm_region_stacking (number)
dm_region_grammar_mode (vvxtrRegionGrammarModeEnum)
dm_region_lexical_constraint_id (number corresponding to a user lexicon set up with vvEngAPI::vvAddWordToLexicon)
dm_region_lexmode (vvxtrRegionLexmodeEnum)
dm_region_foreground (vvxtrRegionForegroundEnum)
dm_region_out_order (number)
dm_region_name (string for region name)
dm_region_uor_string (UOR boundary definition of region)
dm_region_uor_count (number of rectangles in the dm_region_uor_string)

Returns:
vvxtrStatus

vvxtrStatus vvEngAPI::vvSetValue ( const int key,

char * value

) [inline]

Set the string value of the passed key in the engine.

Parameters:

key The key whose value we wish to set.

value The function will set the key to this value in the engine.

Returns:
vvxtrStatus based on status

See also:
vvxtrEngineVariables

Definition at line 942 of file vvxtrAPI.h.
References vvSetValue(), vvxtr_stdarg, and vvxtrStatus.

vvxtrStatus vvEngAPI::vvSetValue ( const int key,

int value

) [inline]

Set the integer value of the passed key in the engine.

Parameters:

key The key whose value we wish to set.

value The function will set the key to this value in the engine.

Returns:
vvxtrStatus based on status

See also:
vvxtrEngineVariables

Definition at line 929 of file vvxtrAPI.h.
References vvxtr_stdarg, and vvxtrStatus.
Referenced by openImageDocument(), outputImg(), processOneDocument(), runOCR(), vvCaptureSubimage(), vvOpenImageFile(), vvSetValue(), and vvStartDoc().

virtual void vvEngAPI::vvSigHUP ( ) [inline, virtual]

A function to call when your client application receives a signal of type SIGHUP.
Will reread any local parameters (does not communicate across a link; use the utility vvlmreread to have a license daemon reread the license file).
Definition at line 1037 of file vvxtrAPI.h.

virtual vvxtrStatus vvEngAPI::vvSpoolDoc ( ) [pure virtual]

Spool recognized data to the output doc.
After you recognize text, if you want to retain that text, you must spool it to an output document before running recognition again.
Before calling this function, you must start an output document with vvEngAPI::vvStartDoc, and that output document must still be open. You can call vvSpoolDoc multiple times for one output document, and writing output is independent of reading input documents. The output document remains open and you may spool to it until you close it with the function vvEngAPI::vvEndDoc.
This function is independent of the output format, or the eventual output destination (file or memory).

Precondition:
An output document must already be started.
dm_output_img_source should be set if you wish to use a different image source than the default (only applicable to compound output documents with embedded images).

Returns:
vvxtrStatus based on status

Referenced by outputDoc().

vvxtrStatus vvEngAPI::vvStartDoc ( int fileFormat ) [inline]

Start an output document.
Please see the documentation for vvEngAPI::vvStartDoc.
This is a helper function that calls vvSetValue to set dm_out_text_format prior to calling vvEngAPI::vvStartDoc()

Returns:
vvxtrStatus based on status

Definition at line 561 of file vvxtrAPI.h.
References dm_out_text_format, vvSetValue(), vvStartDoc(), vvxtr_stdarg, and vvxtrStatus.

virtual vvxtrStatus vvEngAPI::vvStartDoc ( ) [pure virtual]

Start an output document.
An output document is handled internally in the engine. You begin it by calling this function, send data to it by calling vvEngAPI::vvSpoolDoc, and end it by calling vvEngAPI::vvEndDoc. The output document can span multiple input files and multiple pages of recognized image data, depending on how much information you would like in your output document.
When you call this function, if a previous output document existed, it is no longer available.
Memory management for the output document is handled internally throughout the sequence of vvEngAPI::vvStartDoc, vvEngAPI::vvSpoolDoc, and vvEngAPI::vvEndDoc. You do not need to allocate or delete memory until you acquire a completed output document; please see vvEngAPI::vvAcquireDocMemory and vvEngAPI::vvAcquireDocFile.

Precondition:
The file format should be specified prior to calling this function (see dm_out_text_format, vvxtrOutTextFormatEnum), or use the other version of vvStartDoc that takes the file format as a parameter.

Returns:
vvxtrStatus based on status

Referenced by outputDoc(), and vvStartDoc().

virtual vvxtrStatus vvEngAPI::vvStartOCRSes ( ) [pure virtual]

Start an OCR session.
Sets default lexical constraints for the OCR session based on:
dm_language dm_char_set
This function should be called as a part of the start up process for a set of similar documents, after calling vvEngAPI::vvInitInstance. It may also be called any time after vvEngAPI::vvEndOCRSes, as long as vvEngAPI::vvEndInstance has not been called, ending the current instance.
Within one OCR session, internal training is built up on the recognized characters using the language (dictionary) information as reinforcement. This training is sensitive to:

font
point size
density
style

and helps the system recognize deformed characters when it has seen good versions before. Ending and restarting the OCR session flushes this training cache.
As a result of the training that takes place within an OCR session, one OCR session should be considered one "job" in the workflow, where the separate input documents of that job are likely to have pages that are related in some sense. Processing of these similar documents should be braketed by calls to vvEngAPI::vvStartOCRSes and vvEngAPI::vvStartOCRSes.
It will improve the recognition results to permit training to persist between pages of documents from the same source or rendering environment (printer, carbon tape, toner cartridge, etc). Conversely, it will hurt the recognition results if you train over too much disparate material. When in doubt, it is probably best to err on the side of caution and start and end OCR sessions more frequently rather than less frequently. For example, you could start and end the OCR session after every 10 pages, with additional breaks where you know you should have them.

Precondition:
The instance must be initialized and an OCR session cannot currently be open.

Returns:
vvxtrStatus based on status

Referenced by runOCR().

virtual vvxtrStatus vvEngAPI::vvUnloadImage ( ) [pure virtual]

Unload the page of input image data currently loaded in the OCR engine.
This function should be called after input image data has been loaded with vvEngAPI::vvReadImageData and after all processing on the image data is complete.
No more preprocessing or recognition may be performed after this function is called. However, after this function returns, you can load another page of input image data into the OCR engine by calling vvEngAPI::vvReadImageData again.
Calling this function does not affect your output document.

Precondition:
Image data must be currently loaded in the OCR engine (see vvEngAPI::vvReadImageData).

Returns:
vvxtrStatus based on status

Referenced by processOneDocument().

The documentation for this class was generated from the following file:

vvxtrAPI.h

Generated on Thu Dec 11 09:32:25 2003 for OCR Shop XTR/API User Documentation by

1.3.2


Public Member Functions
virtual	~vvEngAPI ()
	Destructor.
virtual vvxtrStatus	vvKill ()=0
	Kill the engine.
virtual vvxtrStatus	vvInitInstance ()=0
	Initialize OCR engine instance.
virtual vvxtrStatus	vvEndInstance ()=0
	End OCR engine instance.
virtual vvxtrStatus	vvStartOCRSes ()=0
	Start an OCR session.
virtual vvxtrStatus	vvEndOCRSes ()=0
	End an OCR session.
virtual vvxtrStatus	vvStartDoc ()=0
	Start an output document.
vvxtrStatus	vvStartDoc (int fileFormat)
	Start an output document.
virtual vvxtrStatus	vvSpoolDoc ()=0
	Spool recognized data to the output doc.
virtual vvxtrStatus	vvEndDoc ()=0
	End the output document.
virtual vvxtrStatus	vvAcquireDocMemory (void *memPtr, int bufsize)=0
	Get the document output through memory.
virtual vvxtrStatus	vvAcquireDocFile (const char *filename)=0
	Get the document output as a file.
virtual vvxtrStatus	vvCaptureSubimage ()=0
	Capture a subimage.
vvxtrStatus	vvCaptureSubimage (int regionID)
	Capture a subimage.
virtual vvxtrStatus	vvAcquireSubimageMemory (void *memPtr, int bufsize)=0
	Get the image output through memory.
virtual vvxtrStatus	vvAcquireSubimageFile (const char *filename)=0
	Write the image output to a file.
virtual vvxtrStatus	vvOpenImageFile ()=0
	Open an input image document in the OCR engine.
vvxtrStatus	vvOpenImageFile (const char *fileName)
	Open the input image file passed as a parameter.
virtual vvxtrStatus	vvCloseImageFile ()=0
	Close the input image file currently open in the OCR engine.
virtual vvxtrStatus	vvReadImageData ()=0
	Read image data into the OCR engine.
virtual vvxtrStatus	vvReadImageData (const struct vvxtrImage *img)=0
	Read image data into the OCR engine.
virtual vvxtrStatus	vvUnloadImage ()=0
	Unload the page of input image data currently loaded in the OCR engine.
virtual vvxtrStatus	vvPreprocess ()=0
	Run preprocessing on the currently loaded image page.
virtual vvxtrStatus	vvRecognize ()=0
	Run recognition on the currently loaded image page.
virtual vvxtrStatus	vvInitValues ()=0
	Initialize engine values.
virtual vvxtrStatus	vvGetStatus (const int key, vvxtr_stdarg *result)=0
	Get engine status for the passed key.
vvxtrStatus	vvSetValue (const int key, int value)
	Set the integer value of the passed key in the engine.
vvxtrStatus	vvSetValue (const int key, char *value)
	Set the string value of the passed key in the engine.
vvxtrStatus	vvGetValue (const int key, int *result)
	Get an integer engine value.
vvxtrStatus	vvGetValue (const int key, char **result)
	Get a character or string engine value.
virtual vvxtrStatus	vvGetState (vvxtr_state *resultState)=0
	Get the engine state.
virtual vvxtrStatus	vvGetCond (const vvxtr_cond c, int *result)=0
	Get the value of an engine condition.
virtual vvxtrStatus	vvSetHint (vvxtrHint hint, bool set=true)
	Give the engine more information about its environment to possibly improve performance.
virtual bool	vvGetHint (vvxtrHint hint)
	Return the current setting of one of the hints.
virtual void	vvSigHUP ()
	A function to call when your client application receives a signal of type SIGHUP.
virtual const char *	vvGetStatusString (vvxtrStatus status=VVXTR_PREVIOUS_ERROR)
	Returns a string that describes the last error condition, if any detailed information about the error is available.
virtual vvxtrStatus	vvGetVersion (vvxtrVersionLocationEnum loc, const char **ver)=0
	Return the version.
virtual vvxtrStatus	vvAddWordToLexicon (const char *word, int constraintId)=0
	Add a word to a user lexicon.
virtual vvxtrStatus	vvSetLexicalConstraints (int mode)=0
	Set lexical constraints for an area.
virtual vvxtrStatus	vvSetRegionProperties (void)=0
	Set region information.
virtual vvxtrStatus	vvForceRegionForeground (int foregroundColor)=0
	Explicitly set the foreground photometric interpretation.
virtual vvxtrStatus	vvRemoveRegion (void)=0
	Remove a region.
Public Attributes
bool	m_hints [vvNumberOfHints]
	Current hint flags.

*1. Initialization:*
vvEngAPI::vvInitInstance	Initialize the OCR instance.
vvEngAPI::vvStartOCRSes	Start an OCR session, loading appropriate languages.
vvEngAPI::vvInitValues	Initialize all "values".
*2. Input image recognition:*
vvEngAPI::vvOpenImageFile	Open an input image file (required only for file input).
vvEngAPI::vvReadImageData	Read a page of image data into the engine.
vvEngAPI::vvPreprocess	Run preprocessing.
vvEngAPI::vvRecognize	Run recognition.
vvEngAPI::vvUnloadImage	Unload the image data from the engine.
vvEngAPI::vvCloseImageFile	Close the input image file (required only for file input).
*3. Output a document:*
vvEngAPI::vvStartDoc	Start an output document.
vvEngAPI::vvSpoolDoc	Send data to the output document.
vvEngAPI::vvEndDoc	Close the output document.
vvEngAPI::vvAcquireDocMemory	Download the output document to an allocated memory block.
vvEngAPI::vvAcquireDocFile	Download the output document to a file.
*4. Output a subimage:*
vvEngAPI::vvCaptureSubimage	Create a subimage from the input image.
vvEngAPI::vvAcquireSubimageMemory	Download the subimage to an allocated memory block.
vvEngAPI::vvAcquireSubimageFile	Download the subimage to a file.
*5. Close down the engine:*
vvEngAPI::vvEndOCRSes	End the OCR session.
vvEngAPI::vvEndInstance	End the OCR instance.
vvEngAPI::vvKill	Completely shut down the engine.

Condition	Abbreviation	Value	Description
C_READY	Re	0x400	ready
C_OCRSESOPEN	Se	0x200	OCR session is open
C_OUTDOCOPEN	Ou	0x100	output document is open
C_FILEOPEN	Fi	0x080	input image is open
C_IMAGELOADED	Im	0x040	input page is open
C_PREPROCDONE	Pr	0x020	preprocessing has been run on the current page
C_RECOGDONE	Rc	0x010	recognition has been run on the current page
C_DOCREADY	Do	0x008	output document is ready for acquisition
C_SUBIMAGEREADY	Su	0x004	output subimage is ready for acquisition
C_ENGINEBUSY	En	0x002	engine is currently busy
C_ERROR	Er	0x001	error

vvEngAPI Class Reference [Ocrxtrapi_public]

Public Member Functions

Public Attributes