Skip to main content
This scenario is used to extract all possible data from a document and store it in a structured way. The result is a JSON file which represents the document structure. It stores all document objects: printed and handwritten text, tables, barcodes, checkmarks, and images with their location and attributes. This format is optimal for further processing, storing data in a database, or integrating with another application. A document goes through several processing steps in this scenario:
  1. Preprocessing of scanned images or photos
Images you get by means of a scanner or a digital camera may need some tweaking before they can be optically recognized. For example, noisy images or images with distorted text lines will need some correction for optical recognition to be successful.
  1. Extracting all the data on the document in a structured way
During layout analysis, various objects are detected on the image and put into blocks of corresponding type. The blocks are recognized according to the optimal settings of their type. In the course of synthesis, the logical structure of the document is restored in a consistent manner. The text order even for complex layouts is preserved to be similar to how a human would read it. This ensures that re-recognition of the same document would result in the same order of the text.
  1. Export to a structured format
The recognized document is saved to JSON or XML.

​
Scenario implementation

The code samples provided in this topic are Windows -specific.
Below you will find a detailed description of the recommended method of using ABBYY FineReader Engine 12 to extract the data from documents. The proposed method uses the processing settings that are most suitable for this purpose.
To start your work with ABBYY FineReader Engine, you need to create the Engine object. The Engine object is the top object in the hierarchy of the ABBYY FineReader Engine objects and provides various global settings, some processing methods, and methods for creating the other objects.To create the Engine object, you can use the InitializeEngine function. See also other ways to load Engine object (Win).

​
C#

public class EngineLoader : IDisposable
{
    public EngineLoader()
    {
        // Initialize these variables with the full path to FREngine.dll, your Customer Project ID,
        // and, if applicable, the path to your Online License token file and the Online License password
        string enginePath = "";
        string customerProjectId = "";
        string licensePath = "";
        string licensePassword = "";
        // Load the FREngine.dll library
        dllHandle = LoadLibraryEx(enginePath, IntPtr.Zero, LOAD_WITH_ALTERED_SEARCH_PATH);
           
        try
        {
            if (dllHandle == IntPtr.Zero)
            {
                throw new Exception("Can't load " + enginePath);
            }
            IntPtr initializeEnginePtr = GetProcAddress(dllHandle, "InitializeEngine");
            if (initializeEnginePtr == IntPtr.Zero)
            {
                throw new Exception("Can't find InitializeEngine function");
            }
            IntPtr deinitializeEnginePtr = GetProcAddress(dllHandle, "DeinitializeEngine");
            if (deinitializeEnginePtr == IntPtr.Zero)
            {
                throw new Exception("Can't find DeinitializeEngine function");
            }
            IntPtr dllCanUnloadNowPtr = GetProcAddress(dllHandle, "DllCanUnloadNow");
            if (dllCanUnloadNowPtr == IntPtr.Zero)
            {
                throw new Exception("Can't find DllCanUnloadNow function");
            }
            // Convert pointers to delegates
            initializeEngine = (InitializeEngine)Marshal.GetDelegateForFunctionPointer(
                initializeEnginePtr, typeof(InitializeEngine));
            deinitializeEngine = (DeinitializeEngine)Marshal.GetDelegateForFunctionPointer(
                deinitializeEnginePtr, typeof(DeinitializeEngine));
            dllCanUnloadNow = (DllCanUnloadNow)Marshal.GetDelegateForFunctionPointer(
                dllCanUnloadNowPtr, typeof(DllCanUnloadNow));
            // Call the InitializeEngine function 
            // passing the path to the Online License file and the Online License password
            int hresult = initializeEngine(customerProjectId, licensePath, licensePassword, 
                "", "", false, ref engine);
            Marshal.ThrowExceptionForHR(hresult);
        }
        catch (Exception)
        {
            // Free the FREngine.dll library
            engine = null;
            // Deleting all objects before FreeLibrary call
            GC.Collect();
            GC.WaitForPendingFinalizers();
            GC.Collect();
            FreeLibrary(dllHandle);
            dllHandle = IntPtr.Zero;
            initializeEngine = null;
            deinitializeEngine = null;
            dllCanUnloadNow = null;
            throw;
        }
    }
    // Kernel32.dll functions
    [DllImport("kernel32.dll")]
    private static extern IntPtr LoadLibraryEx(string dllToLoad, IntPtr reserved, uint flags);
    private const uint LOAD_WITH_ALTERED_SEARCH_PATH = 0x00000008;
    [DllImport("kernel32.dll")]
    private static extern IntPtr GetProcAddress(IntPtr hModule, string procedureName);
    [DllImport("kernel32.dll")]
    private static extern bool FreeLibrary(IntPtr hModule);
    // FREngine.dll functions
    [UnmanagedFunctionPointer(CallingConvention.StdCall, CharSet = CharSet.Unicode)]
    private delegate int InitializeEngine(string customerProjectId, string licensePath, 
        string licensePassword, string tempFolder, string dataFolder, bool isSharedCPUCoresMode, 
        ref FREngine.IEngine engine);
    [UnmanagedFunctionPointer(CallingConvention.StdCall)]
    private delegate int DeinitializeEngine();
    [UnmanagedFunctionPointer(CallingConvention.StdCall)]
    private delegate int DllCanUnloadNow();
    // private variables
    private FREngine.IEngine engine = null;
    // Handle to FREngine.dll
    private IntPtr dllHandle = IntPtr.Zero;
    private InitializeEngine initializeEngine = null;
    private DeinitializeEngine deinitializeEngine = null;
    private DllCanUnloadNow dllCanUnloadNow = null;
}

​
C++ (COM)

// Initialize these variables with the path to FREngine.dll, your FineReader Engine customer project ID,
// and, if applicable, the path to the Online License token and Online License password
wchar_t* FreDllPath;
wchar_t* CustomerProjectId;
wchar_t* LicensePath;  // if you don't use an Online License, assign empty strings to these variables
wchar_t* LicensePassword;
// HANDLE to FREngine.dll
static HMODULE libraryHandle = 0;
// Global FineReader Engine object
FREngine::IEnginePtr Engine;
void LoadFREngine()
{
    if( Engine != 0 ) {
    // Already loaded
    return;
    }
    // First step: load FREngine.dll
    if( libraryHandle == 0 ) {
        libraryHandle = LoadLibraryEx( FreDllPath, 0, LOAD_WITH_ALTERED_SEARCH_PATH );
        if( libraryHandle == 0 ) {
            throw L"Error while loading ABBYY FineReader Engine";
        }
    }
    // Second step: obtain the Engine object
    typedef HRESULT ( STDAPICALLTYPE* InitializeEngineFunc )( BSTR, BSTR, BSTR, BSTR, 
        BSTR, VARIANT_BOOL, FREngine::IEngine** );
    InitializeEngineFunc pInitializeEngine =
    ( InitializeEngineFunc )GetProcAddress( libraryHandle, "InitializeEngine" );
    if( pInitializeEngine == 0 || pInitializeEngine( CustomerProjectId, LicensePath, 
        LicensePassword, L"", L"", VARIANT_FALSE, &Engine ) != S_OK ) {
    UnloadFREngine();
    throw L"Error while loading ABBYY FineReader Engine";
    }
}
ABBYY FineReader Engine enables loading of all processing settings that are most suitable for this scenario using the LoadPredefinedProfile method of the Engine object. This method receives the profile name as an input parameter. Please see Working with Profiles for more information.The settings for this scenario are available in the DataExtraction predefined profile:
  • Layout analysis and recognition prioritize accuracy over speed.
  • Detects all text on an image, including handwritten text and small text areas of low quality.
  • Detects tables, checkmarks, and barcodes.
  • Full synthesis of the logical structure of a document is performed.

​
C#

// Load a predefined profile
engine.LoadPredefinedProfile("DataExtraction");

​
C++ (COM)

// Load a predefined profile
Engine->LoadPredefinedProfile( L"DataExtraction" );
If you wish to change processing settings, use the corresponding parameter objects. Please see Additional optimization section below for more information.
ABBYY FineReader Engine provides the FRDocument object which allows processing multi-page documents. Using of this object allows you to preserve the logical organization of the document, retaining the original text and columns, fonts, styles, etc.To load images of a single document and preprocess them, you should create the FRDocument object and add images to it. You may do one of the following:

​
C#

// Create the FRDocument object from an image file
FREngine.IFRDocument frDocument = engine.CreateFRDocumentFromImage( "C:\\MyImage.tif", null );

​
C++ (COM)

// Create the FRDocument object from an image file
FREngine::IFRDocumentPtr frDocument = Engine->CreateFRDocumentFromImage( L"C:\\MyImage.tif", 0 );
To recognize a document, we suggest that you use the analysis and recognition methods of the FRDocument object. This object provides a whole array of methods for document analysis, recognition, and synthesis. The most convenient method which provides document analysis, recognition, and synthesis all-in-one is the Process method. It also uses simultaneous processing features of multiprocessor and multicore systems in the most efficient manner. However, you can also perform consecutive preprocessing, analysis, recognition, and synthesis using Preprocess, Analyze, Recognize, and Synthesize methods.

​
C#

// Analyze, recognize, and synthesize the document
// There is no need for additional parameters because they are set up by the processing profile
frDocument.Process( null );

​
C++ (COM)

// Analyze, recognize, and synthesize the document
// There is no need for additional parameters because they are set up by the processing profile
frDocument->Process( 0 );
To save a recognized document, you can use the Export method of the FRDocument object by assigning the FileExportFormatEnum constant as one of the parameters. You can change the default parameters of export using the corresponding export object. Please see Additional optimization for specific tasks below for further information.After you have finished your work with the FRDocument object, release all the resources that were used by this object. Use the IFRDocument::Close method.

​
C#

// Save the recognized document in a structured format
frDocument.Export( "C:\\Data.json", FREngine.FileExportFormatEnum.FEF_JSON, null );
// Release the FRDocument object
frDocument.Close();

​
C++ (COM)

// Save the recognized document in a structured format
frDocument->Export( L"C:\\Data.json", FREngine::FEF_JSON, 0 );
// Release the FRDocument object
frDocument->Close();
After finishing your work with ABBYY FineReader Engine, you need to unload the Engine object. To do this, use the DeinitializeEngine exported function.

​
C#

public class EngineLoader : IDisposable
{
    // Unload FineReader Engine
    public void Dispose()
    {
        if (engine == null)
        {
            // Engine was not loaded
            return;
        }
        engine = null;
        // Deleting all objects before FreeLibrary call
        GC.Collect();
        GC.WaitForPendingFinalizers();
        GC.Collect();
        int hresult = deinitializeEngine();
 
        hresult = dllCanUnloadNow();
        if (hresult == 0)
        {
            FreeLibrary(dllHandle);
        }
        dllHandle = IntPtr.Zero;
        initializeEngine = null;
        deinitializeEngine = null;
        dllCanUnloadNow = null;
        // throwing exception after cleaning up
        Marshal.ThrowExceptionForHR(hresult);
    }
    // Kernel32.dll functions
    [DllImport("kernel32.dll")]
    private static extern IntPtr LoadLibraryEx(string dllToLoad, IntPtr reserved, uint flags);
    private const uint LOAD_WITH_ALTERED_SEARCH_PATH = 0x00000008;
    [DllImport("kernel32.dll")]
    private static extern IntPtr GetProcAddress(IntPtr hModule, string procedureName);
    [DllImport("kernel32.dll")]
    private static extern bool FreeLibrary(IntPtr hModule);
    // FREngine.dll functions
    [UnmanagedFunctionPointer(CallingConvention.StdCall, CharSet = CharSet.Unicode)]
    private delegate int InitializeEngine( string customerProjectId, string LicensePath, string LicensePassword, , , , ref FREngine.IEngine engine);
    [UnmanagedFunctionPointer(CallingConvention.StdCall)]
    private delegate int DeinitializeEngine();
    [UnmanagedFunctionPointer(CallingConvention.StdCall)]
    private delegate int DllCanUnloadNow();
    // private variables
    private FREngine.IEngine engine = null;
    // Handle to FREngine.dll
    private IntPtr dllHandle = IntPtr.Zero;
    private InitializeEngine initializeEngine = null;
    private DeinitializeEngine deinitializeEngine = null;
    private DllCanUnloadNow dllCanUnloadNow = null;
}

​
C++ (COM)

void UnloadFREngine()
{
 if( libraryHandle == 0 ) {
  return;
 }
 // Release Engine object
 Engine = 0;
 // Deinitialize FineReader Engine
 typedef HRESULT ( STDAPICALLTYPE* DeinitializeEngineFunc )();
 DeinitializeEngineFunc pDeinitializeEngine =
  ( DeinitializeEngineFunc )GetProcAddress( libraryHandle, "DeinitializeEngine" );
 if( pDeinitializeEngine == 0 || pDeinitializeEngine() != S_OK ) {
  throw L"Error while unloading ABBYY FineReader Engine";
 }
 // Now it's safe to free the FREngine.dll library
 FreeLibrary( libraryHandle );
 libraryHandle = 0;
}

​
Required resources

You can use the FREngineDistribution.csv file to automatically create a list of files required for your application to function. For processing with this scenario, select in the column 5 (RequiredByModule) the following values: Core Core.Resources Opening Opening, Processing Processing Processing.OCR Processing.OCR, Processing.ICR Processing.OCR.NaturalLanguages Processing.OCR.NaturalLanguages, Processing.ICR.NaturalLanguages Export Export, Processing If you modify the standard scenario, change the required modules accordingly. You also need to specify the interface languages, recognition languages and any additional features which your application uses (such as, for example, Opening.PDF if you need to open PDF files, or Processing.OCR.CJK if you need to recognize texts in CJK languages). See Working with the FREngineDistribution.csv File for further details.

​
Additional optimization for specific tasks

Below is the overview of the Help topics containing additional information regarding customization of settings at different stages of the document conversion to an editable format:
  • Scanning - Windows Only
    • Scanning
      Description of the ABBYY FineReader Engine scenario for document scanning.
  • Recognition
    • Tuning Parameters of Preprocessing, Analysis, Recognition, and Synthesis
      Customization of document processing using objects of analysis, recognition and synthesis parameters.
    • PageProcessingParams Object
      This object enables the customization of analysis and recognition parameters. Using this object, you can indicate which image and text characteristics must be detected (inverted image, orientation, barcodes, recognition language, recognition error margin).
    • SynthesisParamsForPage Object
      This object includes parameters responsible for restoration of a page formatting during synthesis.
    • SynthesisParamsForDocument Object
      This object enables customization of the document synthesis: restoration of its structure and formatting.
    • MultiProcessingParams Object - Implemented for Linux and Windows
      Simultaneous processing may be useful when processing a large number of images. In this case, the processing load will be spread over the processor cores during image opening and preprocessing, layout analysis, recognition, and export, which makes it possible to speed up processing.
      Reading modes (simultaneous or consecutive) are set using the MultiProcessingMode property. The RecognitionProcessesCount property controls the number of processes that may be started.
  • Export

​
See also

Basic Usage Scenarios Implementation