Go to: Contents |
Guided Tour
How to Use the ABBYY Mobile OCR Engine Native Library
The ABBYY Mobile OCR Engine native library may be used for testing. The ABBYY Mobile OCR Engine
library supplied as DLL and static library and as a wrapper of the library for Android
and iOS may be found in the appropriate distributions.
This section contains description of how to work with DLL and static library.
Go to the Native Library API Reference section for detailed description of the ABBYY Mobile OCR Engine
native library functions and structures.
Loading the library
You start your work with ABBYY Mobile OCR Engine by loading the library with help of the
FineInitialize function.
It allows you to specify memory allocation/de-allocation functions and
a logging function. Then you need to specify the license information (see the
Licensing section for details).
Note: If you use a trial license, the word "ABBYY" will appear in every 20th line in the recognized text and in every third recognized business card.
- [optional] Implement custom
memory management
functions and a
logging function if you wish to use them.
- Call the FineInitialize
function, passing these functions as input parameters. If you do not wish to
use custom functions, pass 0 for the corresponding parameters.
- Load the license file into memory.
- Create a
CFineLicenseInfo
structure. Assign the pointer to the loaded license data to the
LicenseData field and the size of loaded data to the DataLength
field. Assign the name of your application to the
ApplicationID field. It must correspond to the name of the
application that is specified in the license file.
- Call the
FineSetLicenseInfo function, passing to it the constant pointer
to the
CFineLicenseInfo
structure you just configured.
- After specifying the license you can work with the library until the FineDeinitialize function is called.
Important! All functions of the ABBYY Mobile OCR Engine library should only be called from the thread in which the library was initialized. You cannot
initialize the library in several threads simultaneously without deinitialization.
Opening and processing the images
Below is a description of a typical procedure performed by ABBYY Mobile OCR Engine:
- Load the image for recognition. You can open the image file with the help of the
FineLoadImageFromFile
function or load it from the input stream using the
FineLoadImageFromInputStream
function. These functions convert the image in JPEG or PNG format into
CFineImage internal format of ABBYY Mobile OCR Engine. If you need to load an image in
any other format, you must load
it into memory and convert it into
CFineImage format on your
side. The functions which perform recognition work with the image in this
format.
- Recognize the image. We will use the
FineRecognizeImage
function as an example. Configure the parameters in the following way:
- languages: Recognition languages, passed as an array of the
TLanguageID constants. We do not recommend setting more than two
recognition languages at once.
- patterns: You need to load the
pattern file which includes the
description of the languages you need
into memory and pass its address as
TFinePatternsPtr.
To find out which predefined pattern file you need for your languages,
consult the PatternsFilesInfo.txt file which you will find in the data/Patterns
folder of the distribution package.
- cjkPatterns: If you need to recognize CJK languages, load the pattern
files for those languages into memory in the same way and create a
zero-terminated array of
TFinePatternsPtr variables with the addresses of loaded patterns.
Otherwise, pass an array which contains only one zero pointer.
- dictionaries: Load the
dictionary files
for the languages you use. Attaching the dictionary will improve recognition
quality. See Recognition Languages
in ABBYY Mobile OCR Engine for information on which languages have
built-in dictionary support. Create a zero-terminated array of
TFineDictionaryPtr
variables with the addresses of loaded dictionaries. If you do not use
dictionaries, pass an array which contains only one zero pointer (do not
pass zero instead of array).
- image: Pass the
CFineImage structure you obtained in the first step.
- imageProcessingOptions: Select the image processing options and pass the OR
combination of appropriate
TFineImageProcessingOptionsFlags constants. For default option, pass
0.
- recMode: Choose the recognition mode and specify the appropriate
TFineRecognitionMode
constant.
- confidenceLevel: Choose the level of marking characters as uncertain (TFineRecognitionConfidenceLevel).
- layoutBuff: The result of processing. Create a
CFineLayout*
pointer variable which will receive the recognition results.
- rotation: Create a
TFineRotationType variable which will receive the information
about image rotation. You can pass 0 as this parameter if you do not use
the recognized text coordinates.
- progressCallback: Implement the
TFineProgressCallbackFunction
function if you need to receive information about the operation progress or
be able to cancel the operation. You can pass zero pointer if you do not
use this callback.
- prebuiltDataCallback: Implement the
TFinePrebuiltDataCallbackFunction function if you need to
receive information about the image rotation and detected text blocks before
the processing is completed, for example, to display the text blocks while
the recognition is going on. You can pass zero pointer if you do not use
this callback.
- The CFineLayout
structure you receive after the operation is completed contains all
recognized text and its coordinates. Iterate through the blocks, the text
lines within them, and the characters within text lines; save the text in
the format you need, search it for keywords or work with it in any other way.
Note: By default, recognition operations will be performed in
parallel, using up to 4 threads. You can change this limitation by calling the
FineSetRecognizerThreadsCount after library initialization. Pass 1 for
the threadsCount parameter to turn off multi-threading, or increase the
number of threads if you need faster processing. However, the number of threads
working simultaneously can never exceed the number of CPU cores the device
provides.
See also
Description of the Native Sample