OmniPage CSDK v22.0 has introduced Python API to access KernelAPI, RecAPIPlus and RecPDF functions in Python. The mapping code is autogenerated via SWIG that relies on the C API. See PythonSamples bundled with this CSDK to see the example usages.

Installation

Accessing the Python API requires an extra step after CSDK install. Please locate the available *.whl files under the installation folder (default is shown in these examples).
Using a dos prompt:

cd "C:\ProgramData\OmniPage\CSDK22\x64\Bin"

dir *.whl

Please find the wheel package as a file, e.g. omnipage-22.1-cp37-cp37m-win_amd64.whl that belongs exactly to this CSDK version, and install it manually.
Make sure you have removed any previous install:

pip uninstall -y omnipage

Your python main version 3.7.* have to match in this case, according to 37 in the .whl name.

pip install omnipage-22.1-cp37-cp37m-win_amd64.whl

So far it was assumed that python and pip executables can be found in PATH - in case not, or have multiple python environments (picking the right one):

"C:<absolute_path>\python.exe" -m pip install ...

Separate available .whl package belongs to python-3.8.*, python-3.9.* etc...
Samples

After installing the CSDK, Python samples are available here:

C:\Program Files\OmniPage\CSDK22\Samples\Python

Example - current working directory can be anywhere:

python "C:\ProgramData\OmniPage\CSDK22\x64\Samples\Python\PythonSamples.py" -h
PythonSamples for Tungsten OmniPage CSDK
Parsing arguments
Usage:
  C:\ProgramData\OmniPage\CSDK22\x64\Samples\Python\PythonSamples.py  OPTION ID
        ID could be 1-109 or -all
 -d      ID     prints the description of sample ID to stdout
 -f      ID     prints the function list of sample ID to stdout
 -all           executes all samples, writes all the messages to stdout
 -input  path   sets the input folder where files will be loaded from
 -output path   sets the outputfolder where results will be written to
 -h|?   prints this help
 
python "C:\ProgramData\OmniPage\CSDK22\x64\Samples\Python\PythonSamples.py" 1
PythonSamples for Tungsten OmniPage CSDK
Parsing arguments
Input folder: C:\ProgramData\OmniPage\CSDK22\x64\Samples\Inputs
Output folder: C:\Users\<user>\OmniPage\CSDK22\SamplesOutput\Python\
...
INF > Free all resources allocated by the Engine -- kRecQuit()
INF > End of Sample001 application
The sample passed

Its default input directory is located in the Samples\Inputs folder, and the output files are generated in

%USERPROFILE%\OmniPage\CSDK22\SamplesOutput\Python

Note: color codes are being used by PythonSamples for dos prompt. In case you are not seeing the colors, then you need to open registry, and create in HKCU\Console a DWORD named VirtualTerminalLevel and set it to 0x1.
Notations

As function signatures for Python, we are using PEP 3107 and PEP 484 annotations. The CSDK-specific types (e.g. "RECT") are enclosed within double quotes. Modern Python IDEs are able to use these annotations for static code checks and hints.

Initialization

See kRecInit, RecInitPlus and rPdfInit. All these 3 functions have an optional 3rd parameter with None by default, that means the directory of an installed CSDK binary looked up automatically from the registry. In case you have multiple installations, you may need to specify this path. It is important to call the belonging kRecQuit / RecQuitPlus / rPdfQuit for freeing resources in the end, separately for each 3 type of Init call in reverse order.

Types

When operating on more complex types, SWIG offers special ways for handling them. For simplicity, the enum types are mapped here via int. For their names in Python, please refer to the C-style enum definitions of the C API. But, some of the types are int-like, e.g. REC_COLOR. You can access int-like values via the int function:

import RecAPI as r
r.kRecInit(None, None)
rc, hPage = r.kRecLoadImgF(0, 'Samples/038.jpg', 0)
rc = r.kRecRecognize(0, hPage, None)
rc, zd = r.kRecGetOCRZoneData(hPage, r.II_OCR, 1)
print(int(zd.color))

There is one special type that needs to be used in a with statement:

ProgressMonitorCallback (Sample048.py)

This usage is intended to avoid running the garbage collector too early.

Arrays

For CSDK arrays, the mappings between C and Python are possible via SWIG wrappers: "RectArray", "IntArray", ... so any type name having the "...Array" postfix in double quotes. Example:

import RecAPI as r
 
indices = r.IntArray.createFrom([ 1,2,3 ])
type(indices)
<class 'RecAPI.IntArray'>
 
rects = r.RectArray.createFrom([ r.RECT(1,2,3,4), r.RECT(5,6,7,8)])
[i.left for i in rects]
[1, 5]

Type names of arrays applying the same rule as above: RectArray, PointArray, VDICTDESCArray, CombCellInfoArray, LetterArray, UIntArray, IntArray, SizeTArray, IntArray, DoubleArray, ModuleInfoArray, ClassifyInfoArray.
Note that arrays of enums are accessible via IntArray, and other int-like array e.g. array of REC_COLOR is represented via UIntArray.
SizeTArray is the type name in Python API of the array of size_t in C.

Resource handling

Where not mentioned explicitly and no belonging C API function in this document, objects are freed automatically. E.g. the kRecFree function is available only in C, but doesn't exist in Python so no need to care. However, there are a few ones that exist on the Pythin API too, and the user has to call these explicitly:

It is important to call these functions before kRecQuit/RecQuitPlus/rPdfQuit, in case have any handle unfreed.

Numpy ndarray support

In case an input or output picture should be kept in the memory or passed by another module - typically numpy.ndarray -, we have introduced support for passing input/output via these functions:

def kRecLoadImgPy(sid: int, arrin: "ndarray", RGBOrder: int, dpi: int=72, LineOrder: int=TOP_DOWN) -> Tuple[int, "HPAGE"]
def kRecGetImgAreaPy(sid: int, hPageIn: "HPAGE", iiImg: int, RGBOrder: int, pSrcRect: "RECT"=None, pDstSize: "SIZE"=None, StretchMode: int=STRETCH_DELETE, LineOrder: int=TOP_DOWN) -> Tuple[int, "IMG_INFO", "ndarray"]
The type "ndarray" refers here to numpy.ndarray.
Both the usage of these functions and installing numpy are optional.
It is highly recommended to provide the exact dpi, rather than leaving it on default.
Copy happens internally only when needed (typically, when the ndarray internal representation is not congiuous C).
See Sample007.py for example.
Limitations

These functions are not supported in Python at this moment:

Python is supported only with the 64-bit CSDK release, with some of the latest 64-bit Python versions available at CSDK release time. The 32-bit versions are not supported.