RecAPI
Enumerations | Functions
Direct TXT Output Converter Module
KernelAPI

Simple output converters. More...

Enumerations

enum  DTXTOUTPUTFORMATS {
  DTXT_TXTS,
  DTXT_TXTCSV,
  DTXT_TXTF,
  DTXT_PDFIOT,
  DTXT_XMLCOORD,
  DTXT_BINARY,
  DTXT_IOTPDF,
  DTXT_IOTPDF_MRC,
  DTXT_ALTO,
  DTXT_HOCR
}
 DTXT output formats. More...

Functions

RECERR RECAPIKRN kRecSetDTXTFormat (int sid, DTXTOUTPUTFORMATS dFormat)
 Changing DTXT format.
RECERR RECAPIKRN kRecGetDTXTFormat (int sid, DTXTOUTPUTFORMATS *pdFormat)
 Getting DTXT format.
RECERR RECAPIKRN kRecConvert2DTXT (int sid, const HPAGE *ahPage, int nPage, LPCTSTR pFilename)
 Converting pages with DTXT.
RECERR RECAPIKRN kRecConvert2DTXTEx (int sid, const HPAGE *ahPage, int nPage, IMAGEINDEX iiImg, LPCTSTR pFilename)
 Converting pages with DTXT.
RECERR RECAPIKRN kRecMakePagesSearchable (int sid, LPCTSTR pFilename, int fromPage, const HPAGE *ahPage, int nPage, IMAGEINDEX iiImg)
 Making a PDF page searchable.

Detailed Description

Simple output converters.

This module gives you the possibility to convert recognized text simply and quickly. That is, you use the output of the recognition module as is (without reading order and paragraph detection). Therefore the DirectTXT Outputs are simpler than the Layout Retention Output conversions (available in RecAPIPlus) and also faster to produce, because they do not include slow detection processes.

There are different functions for starting the DTXT conversion. The older function kRecConvert2DTXT can create all the possible DTXT formats. Its newer successor is kRecConvert2DTXTEx, which has an additional IMAGEINDEX parameter for controlling the orientation of the pages creating a PDF file. This latter functions also can create all DTXT formats.

For existing PDF files a special conversion method can be applied. The function kRecMakePagesSearchable inserts invisible text (coming from a recognition step) into the PDF file (in-place), i.e. it makes the file searchable.

You can have control over DirectTXT output behavior through various settings. The root of DirectTXT settings is Kernel.DTxt. These settings can be queried and modified through Settings Manager Module. The following DirectTXT output types can be selected by calling kRecSetDTXTFormat:

The code page used at generating DTXT_TXT* output files can be specified by the setting Kernel.Chr.CodePage, or the function kRecSetCodePage.

The DirectTXT Text (DTXT_TXTS) output is a simple text file. The settings used by this converter are as follows:

The DirectTXT CSV (DTXT_TXTCSV) output is a simple format to represent tables. Microsoft Excel can read this format. The settings used by this converter are as follows:

When you want to process forms, you can collect data into one row for each page. E.g. Kernel.DTxt.PageBreak = ""; Kernel.DTxt.csv.RecordSeparator = 2

The DirectTXT Formatted Text (DTXT_TXTF) delivers plain text, but attempts to keep layout as detected in the original image: this creates a text file that simulates columns and boxes using tabulators. The settings used by this converter are as follows:

The newer DirectTXT PDF formats (DTXT_IOTPDF and DTXT_IOTPDF_MRC) (supported on: Windows, Linux, Embedded Linux, MacOS) contain the whole image of the original page and the text behind the image on a separate layer. These pdf files especially suit the purpose of page archiving, because they contain both the image and the searchable recognized text. There are possibilities to affect on the quality of the generated PDF file. For details see the section about newer image formats.

See also PDF Files in CSDK 22.

DTXT_PDFIOT is deprecated now. Although it can be used, but DTXT_IOTPDF and DTXT_IOTPDF_MRC are suggested to use instead.
The DirectTXT PDF (DTXT_IOTPDF) output (supported on: Windows, Linux, Embedded Linux, MacOS) contains the whole image of the original page and the text behind the image on a separate layer. These pdf files especially suit the purpose of page archiving, because they contain both the image and the searchable recognized text. The following settings affect the DTXT_PDFIOT output (depricated):

See also PDF Files in CSDK 22.

The DirectTXT XML (DTXT_XMLCOORD) output is typically used for further processing recognized data. You can easily parse (e.g. MSXML) or transform (XSLT) the output xml file. The format of the xml output is specified by the same scheme as the Layout Retention Xml Output (http://www.scansoft.com/omnipage/xml/ssdoc-schema3.xsd). The settings used by this converter are as follows:

The DirectTXT ALTO (DTXT_ALTO) option generates ALTO output format (http://www.loc.gov/standards/alto). This xml output is always in UTF-8, ignoring the settings Kernel.Chr.CodePage and Kernel.Chr.CodePage.default.

Setting "Kernel.DTxt.ALTO.InsertCharacters" to true (default) requires applying the ALTO version 4.0 scheme by setting "Kernel.DTxt.ALTO.Version" to 40 (default). When writing ALTO version 2.0 (Kernel.DTxt.ALTO.Version = 20), keep with the following restrictions:

Regardless of ALTO versions, you cannot write multiple languages, even where CSDK could (for example, in a TextBlock). Due to XML restrictions, you cannot use multiple XML attributes with the same name ("LANG" or "language") within a single XML label. The CSDK structures correspondence with the supported ALTO terms:

CSDK ALTO
HPAGE Page
Zone (WT_GRAPHIC) Illustration
Zone (WT_TABLE) ComposedBlock (TYPE="Table")
Zone (WT_FLOW, ...) TextBlock
LETTER Glyph
RLINE GraphicalElement
kRecGetFrameInfo (CELL_INFO.rect) GraphicalElement

The ALTO TextLine, String, SP, and HYP elements are calculated from LETTER attributes.

In the rare case when a single Unicode character is composed of multiple LETTER structures, those may be combined into one glyph with the proper CONTENT attribute, having a string with one or more character. For example, in case of the Thai language, where combining diacritical marks are commonly used, the CONTENT attribute of the output glyph element may contain more than one UTF-8 characters. This does not comply with ALTO schema version 4, which requires exactly 1 character per glyph. CSDK does this on purpose, assuming that these UTF-8 characters belong together.

The DirectTXT hOCR (DTXT_HOCR) option generates hOCR output format (https://en.wikipedia.org/wiki/HOCR). This XHTML output is always in UTF-8, ignoring the settings Kernel.Chr.CodePage and Kernel.Chr.CodePage.default. The CSDK structures correspondence with the supported hOCR terms:

CSDK hOCR
HPAGE ocr_page
Zone (WT_GRAPHIC) ocr_photo
Zone (WT_TABLE) ocr_table
Zone (WT_FLOW, ...) ocr_carea and ocr_par
RLINE ocr_separator
kRecGetFrameInfo (CELL_INFO.rect) ocr_separator

The hOCR ocr_line and ocrx_word elements are calculated from LETTER attributes.

The DirectTXT Binary (DTXT_BINARY) output is used for creating files directly from the LETTER array (i.e. the recognition result) without any character conversion and formatting. It is designed for the barcodes containing binary data (for example BAR_C128 or BAR_PDF417 barcodes containing encrypted data). This method does not perform code page conversion. The lines do not contain spaces at the end of them, except when these spaces are in itself the binary data (i.e. this method removes the zero width end-line spaces). Using this output method, the barcode modules must be forced to generate also binary result, which can be specified by the setting Kernel.OcrMgr.BarBinary. See the topics Binary output, The settings of the BAR Recognition Engine Module.

When you specify an already existing file name, all the types except DTXT_BINARY are appended. You can set and get the output format using kRecSetDTXTFormat and kRecGetDTXTFormat. To perform conversion use kRecConvert2DTXT.

The DTXT module can be especially useful for applications that do not require formatting but speed is an important factor. For example: indexing, archiving, or form processing applications.

For a collected list of the DTXT settings see the Settings of the Direct TXT Module.

Enumeration Type Documentation

enum DTXTOUTPUTFORMATS

DTXT output formats.

The following output formats can be created by Direct TXT output converter. All of them except DTXT_BINARY are appendable. Some of the selectable output formats can be balanced by settings. See Settings of the Direct TXT Module.

Enumerator:
DTXT_TXTS 

Text Standard. Details...

DTXT_TXTCSV 

Text CSV. Details...

DTXT_TXTF 

Text Formatted. Details...

DTXT_PDFIOT 

Deprecated (see usage of new formats). PDF Image on Text. Supported on: Windows, Linux, Embedded Linux, MacOS. Details...

DTXT_XMLCOORD 

XML Simple. Details...

DTXT_BINARY 

Binary output. Details...

DTXT_IOTPDF 

Image on Text PDF with changeable compression level. Supported on: Windows, Linux, Embedded Linux, MacOS. Details...

DTXT_IOTPDF_MRC 

Image on Text PDF with MRC technology. Supported on: Windows, Linux, Embedded Linux, MacOS. Details...

DTXT_ALTO 

ALTO xml. Details...

DTXT_HOCR 

hOCR xhtml. Details...

Function Documentation

RECERR RECAPIKRN kRecConvert2DTXT ( int  sid,
const HPAGE *  ahPage,
int  nPage,
LPCTSTR  pFilename 
)

Converting pages with DTXT.

This function converts the given pages using Direct TXT output converter.

Parameters:
[in]sidSettings Collection ID.
[in]ahPageArray of HPAGEs to be converted.
[in]nPageNumber of HPAGEs in ahPage.
[in]pFilenameFile name of the resulted file.
Return values:
RECERR
Note:
You might find kRecConvert2DTXTEx better to use; that is the suggested fuction to call. This function is equivalent to kRecConvert2DTXTEx(sid, ahPage, nPage, II_CURRENT, pFilename) in the default case when there is no original image.
HPAGE's may be rather big memory areas, thus keeping them in memory simultaneously may cause memory errors. All the DTXT types except DTXT_BINARY are appendable, thus it is recommended to append them page-by-page (or per some pages) to the same file instead of using a large array containing all of the HPAGE's.
If hPage contains DataStream this function may put the image into the output file without recompression. See the details in the section about DataStream.
Some of the settings used by this function can be modified with calling the kRecSetDTXTFormat. The rest of the used settings can be changed only through the Settings Manager Module. For more information see the Settings of the Direct TXT Module or the description of the module.
The code page used at generating DTXT_TXT* output files can be specified by the setting Kernel.Chr.CodePage, or the function kRecSetCodePage.
The specification of this function in C# is: 
    RECERR kRecConvert2DTXT(int sid, IntPtr[] ahPage, string pFilename);
    // or
    RECERR kRecConvert2DTXT(int sid, IntPtr ahPage, string pFilename);
The specification of this function in Java is: 
 int kRecConvert2DTXT(int sid, HPAGE[] ahPage, String pFilename)
The specification of this function in Python is: 
 def kRecConvert2DTXT(sid: int, ahPage: "HPAGE", pFilename: str) -> int
RECERR RECAPIKRN kRecConvert2DTXTEx ( int  sid,
const HPAGE *  ahPage,
int  nPage,
IMAGEINDEX  iiImg,
LPCTSTR  pFilename 
)

Converting pages with DTXT.

This function converts the given pages using Direct TXT output converter.

Parameters:
[in]sidSettings Collection ID.
[in]ahPageArray of HPAGEs to be converted.
[in]nPageNumber of HPAGEs in ahPage.
[in]iiImgIndex of the image to be saved. (II_CURRENT or II_ORIGINAL)
[in]pFilenameFile name of the resulted file.
Return values:
RECERR
Note:
This function is the successor of the kRecConvert2DTXT function.
HPAGE's may be rather big memory areas, thus keeping them in memory simultaneously may cause memory errors. All the DTXT types except DTXT_BINARY are appendable, thus it is recommended to append them page-by-page (or per some pages) to the same file instead of using a large array containing all of the HPAGE's.
In case of DTXT_XMLCOORD output iiImg specifies the orientation of the coordinates written into the XML file. II_ORIGINAL can be used even if the original image does not exist.
If hPage contains DataStream this function may put the image into the output file without recompression. See the details in the section about DataStream.
In case of different PDF outputs iiImg specifies the image used to create the PDF file. II_ORIGINAL can be used only if the original image or DataStream is available. See also kRecSetPreserveOriginalImg and the documentation of DataStream.
Some of the settings used by this function can be modified with calling the kRecSetDTXTFormat. The rest of the used settings can be changed only through the Settings Manager Module. For more information see the Settings of the Direct TXT Module or the description of the module.
The code page used at generating DTXT_TXT* output files can be specified by the setting Kernel.Chr.CodePage, or the function kRecSetCodePage.
The specification of this function in C# is: 
    RECERR kRecConvert2DTXTEx(int sid, IntPtr[] ahPage, IMAGEINDEX iiImg, string pFilename);
    // or
    RECERR kRecConvert2DTXTEx(int sid, IntPtr ahPage, IMAGEINDEX iiImg, string pFilename);
The specification of this function in Java is: 
 int kRecConvert2DTXTEx(int sid, HPAGE[] ahPage, IMAGEINDEX iiImg, String pFilename)
The specification of this function in Python is: 
 def kRecConvert2DTXTEx(sid: int, ahPage: "HPAGE", iiImg: int, pFilename: str) -> int
RECERR RECAPIKRN kRecGetDTXTFormat ( int  sid,
DTXTOUTPUTFORMATS *  pdFormat 
)

Getting DTXT format.

This function retrieves the Direct TXT output format.

Parameters:
[in]sidSettings Collection ID.
[out]pdFormatPointer of a variable to store the output format.
Return values:
RECERR
Note:
This function gets the value of the setting Kernel.DTxt.DirectTxtFormat. This setting can be changed by kRecSetDTXTFormat.
The specification of this function in C# is: 
 RECERR kRecGetDTXTFormat(int sid, out DTXTOUTPUTFORMATS pdFormat);
The specification of this function in Java is: 
 int kRecGetDTXTFormat(int sid, DTXTOUTPUTFORMATS[] pdFormat)
The specification of this function in Python is: 
 def kRecGetDTXTFormat(sid: int) -> Tuple[int, int]
RECERR RECAPIKRN kRecMakePagesSearchable ( int  sid,
LPCTSTR  pFilename,
int  fromPage,
const HPAGE *  ahPage,
int  nPage,
IMAGEINDEX  iiImg 
)

Making a PDF page searchable.

This function writes invisible textual information into a PDF to make it searchable/readable

Parameters:
[in]sidSettings Collection ID.
[in]pFilenameName of the file to be made searchable
[in]fromPageIndex of the first page to be made searchable (zero start index). The function processes the nPage pages starting from fromPage.
[in]ahPageArray of HPAGE's containing the searchable/textual data (comes from kRecRecognize).
[in]nPageNumber of HPAGE's in ahPage
[in]iiImgIndex of the image to use for orienting the pages. (II_ORIGINAL or II_CURRENT)
Return values:
RECERR
Note:
The orientation of the processed page is not changed if iiImg is II_ORIGINAL. (The text might be rotated to the correct position if needed.) On the other hand, when iiImg is II_CURRENT the function may rotate the pages to make them upright standing. The image itself is not touched even in that case just rotated matrix added.
The file pFilename should not be opened during kRecMakePagesSearchable. It is recommended to make searchable page-by-page instead of using an array with lots of HPAGE's. Since each open/close requires greater resources, grouping HPAGE's are supported. However HPAGE's may be rather big memory areas, thus keeping them in memory simultaneously may cause memory errors.
Page-by-page sample: 
    "Kernel.OcrMgr.PDF.ProcessingMode"=PDF_PM_GRAPHICS_ONLY
    HPAGE hPage;
    rc = kRecLoadImgF(sid, pFilename, &hPage, i);
    rc = kRecPreprocessImg(sid, hPage);
    rc = kRecRecognize(sid, hPage, NULL);
    rc = kRecMakePagesSearchable(sid, pFilename, i, &hPage, 1, II_CURRENT);
    rc = kRecFreeImg(hPage);
Page grouping sample: 
    HIMGFILE hIFile = NULL;
    HPAGE hPage[NPAGES];
    ..
    rc = kRecOpenImgFile(pFilename, &hIFile, IMGF_READ, (IMF_FORMAT)0);
    ..
    for(ipage)
        rc = kRecLoadImg(sid, hIFile, hPage+ipages, first_page+ipage);
    ..
    rc = kRecCloseImgFile(hIFile);
    ..
    //Preprocessing must be somewhere between load and recognize.
    //So you can also attach it to the loop of either load or recognize.
    for(ipage)
        rc = kRecPreprocessImg(sid, hPage[ipage]);
    ..
    for(ipage)
        rc = kRecRecognize(sid, hPage[ipage], NULL);
    ..
    rc = kRecMakePagesSearchable(sid, pFilename, first_page, hPage, NPAGES, II_CURRENT);
    ..
    for(ipage)
        rc = kRecFreeImg(hPage[ipage]);
An interesting trick, which can be useful sometimes: this function can change the orientation of the pages in the PDF file even if it gets HPAGE's having no letters (if preprocess have been already called and II_CURRENT is passed in iiImg).
The specification of this function in C# is: 
    RECERR kRecMakePagesSearchable(int sid, string pFilename, int fromPage, IntPtr[] ahPage, IMAGEINDEX iiImg);
    // or
    RECERR kRecMakePagesSearchable(int sid, string pFilename, int fromPage, IntPtr ahPage, IMAGEINDEX iiImg);
The specification of this function in Java is: 
 int kRecMakePagesSearchable(int sid, String pFilename, int fromPage, HPAGE[] ahPage, IMAGEINDEX iiImg)
The specification of this function in Python is: 
 def kRecMakePagesSearchable(sid: int, pFilename: str, fromPage: int, ahPage: "HPAGE", iiImg: int) -> int
RECERR RECAPIKRN kRecSetDTXTFormat ( int  sid,
DTXTOUTPUTFORMATS  dFormat 
)

Changing DTXT format.

This function changes the Direct TXT output format setting.

Parameters:
[in]sidSettings Collection ID.
[in]dFormatThe output format to be set.
Return values:
RECERR
Note:
This function sets the value of the setting Kernel.DTxt.DirectTxtFormat. This setting can be retrieved by kRecGetDTXTFormat.
The specification of this function in C# is: 
 RECERR kRecSetDTXTFormat(int sid, DTXTOUTPUTFORMATS dFormat);
The specification of this function in Java is: 
 int kRecSetDTXTFormat(int sid, DTXTOUTPUTFORMATS dFormat)
The specification of this function in Python is: 
 def kRecSetDTXTFormat(sid: int, dFormat: int) -> int