Supporting different image file formats. More...

Typedefs
typedef struct tagIMGFILEHANDLE *	HIMGFILE
	Handle of image files.
Enumerations
enum	IMF_FORMAT { FF_TIFNO = 0, FF_TIFPB, FF_TIFHU, FF_TIFG31, FF_TIFG32, FF_TIFG4, FF_TIFLZW, FF_PCX, FF_DCX, FF_SIM, FF_BMP_NO, FF_BMP_RLE8, FF_BMP_RLE4, FF_AWD, FF_JPG_SUPERB, FF_JPG_LOSSLESS = FF_JPG_SUPERB, FF_JPG_GOOD, FF_JPG_MIN, FF_PDA, FF_PNG, FF_XIFF, FF_GIF, FF_MAX_LOSSLESS, FF_MAX_GOOD, FF_MAX_MIN, FF_PGX, FF_PDF_MIN, FF_PDF_GOOD, FF_PDF_SUPERB, FF_PDF_LOSSLESS = FF_PDF_SUPERB, FF_PDF_MRC_MIN, FF_PDF_MRC_GOOD, FF_PDF_MRC_SUPERB, FF_PDF_MRC_LOSSLESS = FF_PDF_MRC_SUPERB, FF_TIFJPGNEW, FF_JPG2K_SUPERB, FF_JPG2K_LOSSLESS = FF_JPG2K_SUPERB, FF_JPG2K_GOOD, FF_JPG2K_MIN, FF_JBIG2_LOSSLESS, FF_JBIG2_LOSSY, FF_XPS, FF_WMP, FF_JBIG, FF_OPG, FF_PDF, FF_PDF_MRC, FF_JPG, FF_JPG2K, FF_TIF, FF_SIZE }
	Image formats. More...
enum	IMF_IMAGEQUALITY { IMF_IMAGEQUALITY_MIN = 0, IMF_IMAGEQUALITY_GOOD = 1, IMF_IMAGEQUALITY_SUPERB = 2 }
	Image quality (for DTXT PDF output) More...
enum	IMF_MRCLEVEL { IMF_MRCLEVEL_NO = 0, IMF_MRCLEVEL_MIN = 1, IMF_MRCLEVEL_GOOD = 2, IMF_MRCLEVEL_SUPERB = 3 }
	MRC level (for DTXT PDF output) More...
enum	COMPRESSION_TRADEOFF { COMPRESSION_ADVANCED, COMPRESSION_FAST }
	Compression tradeoff. More...
enum	IMF_PDFCOMPATIBILITY { IMF_PDF_FORCESIZE = 0, IMF_PDF_FORCEQUALITY = 1, IMF_PDF15 = 2, IMF_PDF14 = 3, IMF_PDF13 = 4, IMF_PDF12 = 5, IMF_PDF11 = 6, IMF_PDF10 = 7, IMF_PDFA = 8, IMF_PDFA1B = IMF_PDFA, IMF_PDF16 = 9, IMF_PDF17 = 10, IMF_PDFA2B = 11, IMF_PDFA2U = 12, IMF_PDFA1A = 13, IMF_PDFA2A = 14, IMF_PDFA3B = 15, IMF_PDFA3U = 16, IMF_PDFA3A = 17, IMF_PDF20 = 18 }
	PDF compatibility (for saving PDF with KernelAPI) More...
enum	IMF_PDFENCRYPTION { IMF_PDFSECURITY_NONE, IMF_PDFSECURITY_STANDARD, IMF_PDFSECURITY_ENHANCED, IMF_PDFSECURITY_AES, IMF_PDFSECURITY_AES256, IMF_PDFSECURITY_AES256X }
	PDF encryption types. More...
enum	ENCRYPT_LEVEL { ENC_NOPAS = 0, ENC_MUSTPAS = 1, ENC_MASTER = 2, ENC_USER = 4, ENC_MUSTUSER = ENC_MUSTPAS \| ENC_USER, ENC_MUSTMASTER = ENC_MUSTPAS \| ENC_MASTER, ENC_MUSTANY = ENC_MUSTPAS \| ENC_MASTER \| ENC_USER, ENC_NOACCESS = 8 }
	PDF encryption level. More...
Functions
RECERR RECAPIKRN	kRecOpenImgFile (LPCTSTR pFilename, HIMGFILE *pHIMGFILE, int mode, IMF_FORMAT filetype)
	Opening an image file.
RECERR RECAPIKRN	kRecCloseImgFile (HIMGFILE hIFile)
	Closing an image file.
RECERR RECAPIKRN	kRecGetPDFEncLevel (HIMGFILE hIFile, ENCRYPT_LEVEL *pEncLev)
RECERR RECAPIKRN	kRecSetImfLoadFlags (int sid, DWORD fFlag)
	Setting IMF PDF load flags.
RECERR RECAPIKRN	kRecGetImfLoadFlags (int sid, DWORD *pfFlag)
	Getting IMF PDF load flags.
RECERR RECAPIKRN	kRecLoadImg (int sid, HIMGFILE hIFile, HPAGE *phPage, int iPage)
	Loading a page from an opened image file.
RECERR RECAPIKRN	kRecLoadImgF (int sid, LPCTSTR pFilename, HPAGE *phPage, int nPage)
	Loading a page directly from an image file.
RECERR RECAPIKRN	kRecLoadImgDataStream (int sid, HIMGFILE hIFile, HPAGE *phPage, int iPage)
	Loading a page from an opened image file without decompressing the image.
RECERR RECAPIKRN	kRecLoadImgDataStreamF (int sid, LPCTSTR pFilename, HPAGE *phPage, int nPage)
	Loading a page directly from an image file without decompressing the image.
RECERR RECAPIKRN	kRecDecompressImgDataStream (int sid, HPAGE hPage)
	Decompressing a DataStream.
RECERR RECAPIKRN	kRecFreeImgDataStream (int sid, HPAGE hPage)
	Deleting DataStream from an HPAGE.
RECERR RECAPIKRN	kRecLoadImgM (int sid, BYTE lpBitmap, LPCIMG_INFO lpImg, HPAGE phPage)
	Loading a page directly from a memory buffer.
RECERR RECAPIKRN	kRecLoadImgMC (int sid, BYTE lpBuf, size_t bufLen, LPCCOMPRESSED_IMG_INFO lpCImg, HPAGE phPage)
	Loading a page directly from a compressed memory buffer.
RECERR RECAPIKRN	kRecLoadImgDataStreamMC (int sid, BYTE lpBuf, size_t bufLen, LPCOMPRESSED_IMG_INFO lpCImg, HPAGE phPage)
	Loading a page directly from a compressed memory buffer without decompressing the image.
RECERR RECAPIKRN	kRecSetCompressionLevel (int sid, int CompressionLevel)
	Setting the compression level.
RECERR RECAPIKRN	kRecGetCompressionLevel (int sid, int *pCompressionLevel)
	Getting the compression level.
RECERR RECAPIKRN	kRecSetCompressionTradeoff (int sid, COMPRESSION_TRADEOFF CompressionTradeoff)
	Setting the compression trade-off.
RECERR RECAPIKRN	kRecGetCompressionTradeoff (int sid, COMPRESSION_TRADEOFF *pCompressionTradeoff)
	Getting the compression tradeoff.
RECERR RECAPIKRN	kRecSetMRCCompressionSettingsFromLevel (int sid, int CompressionLevel, COMPRESSION_TRADEOFF CompressionTradeOff)
	Modifying the MRC settings according to the given compression level and tradeoff.
RECERR RECAPIKRN	kRecSetJPGQuality (int sid, int nQuality)
	Setting JPEG quality.
RECERR RECAPIKRN	kRecGetJPGQuality (int sid, int *pnQuality)
	Getting JPEG quality.
RECERR RECAPIKRN	kRecSaveImg (int sid, HIMGFILE hIFile, IMF_FORMAT Imgfileformat, HPAGE hPage, IMAGEINDEX iiImg, INTBOOL bAppend)
	Saving a page.
RECERR RECAPIKRN	kRecSaveImgForce (int sid, HIMGFILE hIFile, IMF_FORMAT Imgfileformat, HPAGE hPage, IMAGEINDEX iiImg, INTBOOL bAppend)
	Saving a page with forcing the format.
RECERR RECAPIKRN	kRecSaveImgF (int sid, LPCTSTR pFilename, IMF_FORMAT Imgfileformat, HPAGE hPage, IMAGEINDEX img, INTBOOL bAppend)
	Saving a page directly into a file.
RECERR RECAPIKRN	kRecSaveImgForceF (int sid, LPCTSTR pFilename, IMF_FORMAT Imgfileformat, HPAGE hPage, IMAGEINDEX iiImg, INTBOOL bAppend)
	Saving a page directly into a file with forcing of the format.
RECERR RECAPIKRN	kRecSaveImgArea (int sid, HIMGFILE hIFile, IMF_FORMAT format, HPAGE hPage, IMAGEINDEX iiImg, LPCRECT pRect, INTBOOL append)
	Saving an area of a page.
RECERR RECAPIKRN	kRecSaveImgAreaF (int sid, LPCTSTR pFilename, IMF_FORMAT format, HPAGE hPage, IMAGEINDEX iiImg, LPCRECT pRect, INTBOOL append)
	Saving an area of a page directly into a file.
RECERR RECAPIKRN	kRecSetPdfPassword (HIMGFILE hIFile, LPCTSTR pwd)
	Setting PDF password.
RECERR RECAPIKRN	kRecSetPdfTagInfo (int sid, INTBOOL bUseTagInfo)
	Setting use of PDF tag information.
RECERR RECAPIKRN	kRecGetPdfTagInfo (int sid, INTBOOL *pbUseTagInfo)
	Getting the use of PDF tag information.
RECERR RECAPIKRN	kRecGetImgFilePageCount (HIMGFILE hIFile, int *lpPageCount)
	Getting the number of pages in an image file.
RECERR RECAPIKRN	kRecGetImgFilePageInfo (int sid, HIMGFILE hIFile, int nPage, LPIMG_INFO pImg, IMF_FORMAT *pFormat)
	Getting information about a page of an image file.
RECERR RECAPIKRN	kRecCopyImgFilePage (int sid, HIMGFILE hIFileDst, int ndstPage, HIMGFILE hIFileSrc, int nsrcPage)
	Copying a page between TIFF files.
RECERR RECAPIKRN	kRecDeleteImgFilePage (int sid, HIMGFILE hIFile, int nPage)
	Removing a page from a TIFF file.
RECERR RECAPIKRN	kRecInsertImgFilePage (int sid, HPAGE hPage, IMAGEINDEX iiImg, HIMGFILE hIFile, int nPage, IMF_FORMAT format)
	Inserting a page into a TIFF file.
RECERR RECAPIKRN	kRecIsMultipageImgFileFormat (IMF_FORMAT imgfileformat, INTBOOL *bEnabled)
	Checking multi-page capability of an image format.
RECERR RECAPIKRN	kRecMatchImgFileFormat (int sid, HPAGE hPage, IMAGEINDEX iiImg, IMF_FORMAT imgfileformat, INTBOOL *match)
	Checking whether an image is suitable for a file format.
RECERR RECAPIKRN	kRecPackImgFile (int sid, LPCTSTR pFileName)
	Packing a TIFF file.
RECERR RECAPIKRN	kRecUpdateImgFilePage (int sid, HPAGE hPage, IMAGEINDEX iiImg, HIMGFILE hIFile, int nPage, IMF_FORMAT format)
	Replacing a page in a TIFF file.
RECERR RECAPIKRN	kRecReplaceImgFilePage (int sid, HIMGFILE hIFileDst, int ndstPage, HIMGFILE hIFileSrc, int nsrcPage)
	Replacing a page in a TIFF file.
RECERR RECAPIKRN	kRecGetImgFilePageIndex (HIMGFILE hIFile, int *pIndex)
	Getting the index of the current page.
Image file opening modes

#define	IMGF_SCANNER (HIMGFILE)-1
	Image input from scanner. (Use it with kRecLoadImg.)
#define	IMGF_READ 0
	Opening file for reading only. The file can be shared. (Use it with kRecOpenImgFile.)
#define	IMGF_RDWR 2
	Opening file for both reading and writing. The opening is exclusive. The file is appendable. When the file does not exist it creates a new one. (Use it with kRecOpenImgFile.)
IMF PDF Load Flags defines for loading PDF file
Possible bits of the setting Kernel.Imf.PDF.LoadFlags, which can be set by kRecSetImfLoadFlags. These bits can be combined. The rendered elements appear on the II_ORIGINAL image of the HPAGE. Note: There are other ways to affect on PDF processing. See also PDF_PROC_MODE.
#define	IMF_PDF_AS_IMAGE 1
	Disable using PDF text. PDF is loaded as an image (e.g. a TIFF).
#define	IMF_PDF_NO_TAGS 2
	Disable using PDF tags.
#define	IMF_PDF_ANN_NOTE (4 << 0)
	Enable rendering sticky-note icons.
#define	IMF_PDF_ANN_LINK (4 << 1)
	Enable rendering hyperlinks.
#define	IMF_PDF_ANN_TEXT (4 << 2)
	Enable rendering text.
#define	IMF_PDF_ANN_LINE (4 << 3)
	Enable rendering straight lines.
#define	IMF_PDF_ANN_SQUARE (4 << 4)
	Enable rendering rectangles.
#define	IMF_PDF_ANN_CIRCLE (4 << 5)
	Enable rendering ellipses.
#define	IMF_PDF_ANN_POLYGON (4 << 6)
	Enable rendering closed and filled polygons.
#define	IMF_PDF_ANN_POLYLINE (4 << 7)
	Enable rendering closed polygons.
#define	IMF_PDF_ANN_HIGHLIGHT (4 << 8)
	Enable rendering highlights of the document text.
#define	IMF_PDF_ANN_UNDERLINE (4 << 9)
	Enable rendering underline of the document text.
#define	IMF_PDF_ANN_SQUIGGLY (4 << 10)
	Enable rendering jagged underline of the document text.
#define	IMF_PDF_ANN_CROSSOUT (4 << 11)
	Enable rendering crossout of the document text.
#define	IMF_PDF_ANN_STAMP (4 << 12)
	Enable rendering stamps.
#define	IMF_PDF_ANN_CARET (4 << 13)
	Enable rendering carets.
#define	IMF_PDF_ANN_PENCIL (4 << 14)
	Enable rendering freehand drawing.
#define	IMF_PDF_ANN_POPUP (4 << 15)
	Enable rendering popup windows.
#define	IMF_PDF_ANN_FILEATTACHMENT (4 << 16)
	Enable rendering file attachment icons.
#define	IMF_PDF_ANN_SOUND (4 << 17)
	Enable rendering sound icons.
#define	IMF_PDF_ANN_MOVIE (4 << 18)
	Enable rendering movie icons.
#define	IMF_PDF_ANN_FORM (4 << 19)
	Enable rendering Acro-Form fields.
#define	IMF_PDF_ANN_SCREEN (4 << 20)
	Enable rendering screen icons.
#define	IMF_PDF_ANN_PRINTERMARK (4 << 21)
	Enable rendering printer's mark icons.
#define	IMF_PDF_ANN_TRAPNET (4 << 22)
	Enable rendering trap network icons.
#define	IMF_PDF_ANN_WATERMARK (4 << 23)
	Enable rendering watermark.
#define	IMF_PDF_ANN_3D (4 << 24)
	Enable rendering 3d icons.
Pagenumber defines for loading a page
See kRecLoadImg.
#define	IMGF_NEXTPAGE -1
	The next page of a HIMGFILE.
#define	IMGF_FIRSTPAGE 0
	The first page of a HIMGFILE.

Detailed Description

Supporting different image file formats.

This module supports loading and saving different image file formats. Accessible formats are specified by IMF_FORMAT. During loading, the system can automatically detect the file format and compression method of the image files without using file extensions. Both this module, and the Image Handling Module support B/W, grayscale and color images.

CSDK v20 can read the following multi-page image file formats: DCX, MAX, PDF, TIFF and TIFF-FX.

Load input can be an image file already open (kRecOpenImgFile, kRecLoadImg), the image file itself (kRecLoadImgF), or the memory of the integrating application (kRecLoadImgM, kRecLoadImgMC). The first two functions can handle multi-page image files. The former can load a specified page or the next page, while the latter can load only the specified one.

After the file is loaded, the image is forwarded to the Image Handling Module. Saving input is also provided by the Image Handling Module.

On loading, 4-bit greyscale images are converted into the 8-bit greyscale format, and 4-bit palette color images are converted into the 8-bit palette color format.

The working of the Image File Handling Module can be adjusted with settings in some points.

See also:: PDF Files in CSDK 20; Image File Format List

Extended image size

There is a limit for the maximum number of pixels for either the height or width of an image, given by the settings Kernel.Img.Max.Pix.*. Its default value is 8400 pixels, for both the X and Y dimensions. The user can process larger images by modifying these values - up to 32000 pixels, both horizontally and vertically. Thus CSDK can reach either A0 size (33" x 46") or 2400 DPI in particular situations (see the indicative table at the end of chapter 1 in the User’s Guide). The default value is fixed so that any workflow can be safely and successfully finished without image size issues. Any image exceeding the pixel limit will be skipped. Using the default value protects high-volume unattended processing from use of high resources.

The inch-based page size limits (Kernel.Img.Max.Inch.*) are abolished since CSDK 16. There are no module-specific limits to image size. The available memory, the computing environment and properties of individual image files all influence the maximum sizes for successful image processing.

Notes

Memory segmentation (mainly due to system DLL's) may strongly decrease these amounts.
It is recommended to create 64-bit applications, because in this case the above mentioned memory segmentation does not exist. For 32-bit applications use of Enable large addresses VisualStudio linker option (or equivalent options in other linkers) is recommended.
In the Microsoft Word and Power Point programs, the size of the page is limited. The width and height of the page must be between 0.1 and 22 inches. Because of this, if you scanned or loaded a page that is larger than this limit, you cannot save it into Flowing Page or True Page formats with *.rtf and *.docx and *.pptx file extensions. These formats try to retain the original page size and layout. If you try to save this, you will get an error message and the file will not be saved.
There are also X and Y limits for the minimum pixel size of the image: Kernel.Img.Min.Pix.*

Using images without decompression

In a standard workflow, saving an image using a lossy compression method loses both the compression level and the quality of the input image even if the output file format is the same as the loaded one. It can be especially annoying when a JPEG image is put into a PDF file for creating a searchable PDF.

OmniPage CSDK 20.20 introduces a new notion called DataStream. This is an optional part of an HPAGE that contains the input image without any decompression. The DataStream can use JPEG or JPEG2000 compression; therefore such a page can be created from JPEG, JPEG2000 and TIFF using 'new style' JPEG files. After loading these types of image files, the HPAGE does not contain decompressed bitmap, but all CSDK functions can decompress it automatically if the decompressed bitmap is needed. After decompressing the DataStream the HPAGE contains both the DataStream and the decompressed bitmap. When the HPAGE is saved, you can specify whether or not to use the DataStream.

To keep compatibility with the previous versions of CSDK, two new settings were introduced:

Kernel.Imf.DataStream.TryToLoad: bool setting, default is false, and
Kernel.Imf.DataStream.Save: bool setting, default is true.

If you set Kernel.Imf.DataStream.TryToLoad to true, the standard image loading functions (kRecLoadImg, kRecLoadImgF) load the DataStream if possible, otherwise they load the decompressed image. There are functions (kRecLoadImgDataStream, kRecLoadImgDataStreamF, kRecLoadImgDataStreamMC), that – regardless of the status of Kernel.Imf.DataStream.TryToLoad – always load the DataStream, or return error if the input format is not suitable.

If Kernel.Imf.DataStream.Save is true, and the HPAGE contains DataStream, the saving operations (any kRecSaveImg* and also any kRecConvert2DTXT*) decide whether or not to write the DataStream into the output file.

The DataStream will be saved if
- the output format is compatible with the format of the DataStream, i.e. PDF (non-MRC), JPEG (for JPEG and TIFF inputs) or JPEG2000 (for JPEG2000 inputs); and
- the IMAGEINDEX is II_ORIGINAL or II_CURRENT and it has not been changed (except rotation and deskew, see below)
- the whole image area is saved.
If the output file is PDF, then the DataStream can be saved even if the image has been rotated and/or 2d-deskewed, because PDF contains a transformation matrix that can describe the necessary transformation. If the output is JPEG or JPEG2000, the DataStream is used only if the image is neither rotated nor deskewed.
In any other cases, the decompressed data will be saved.

If a CSDK function changes II_CURRENT image, the DataStream will be deleted except if the image is rotated or 2d-deskewed or Kernel.Img.KeepOriginalImage is true.

If you want to force saving the decompressed data, you can set Kernel.Imf.DataStream.Save to false, or you can delete DataStream calling kRecFreeImgDataStream.

Newer image formats

In OmniPage CSDK 19.20 the following image formats were introduced (supported on: Windows, Linux, Embedded Linux):

FF_PDF (instead of FF_PDF_MIN, FF_PDF_GOOD, FF_PDF_SUPERB),
FF_PDF_MRC (instead of FF_PDF_MRC_MIN, FF_PDF_MRC_GOOD, FF_PDF_MRC_SUPERB),
FF_JPG (instead of FF_JPG_MIN, FF_JPG_GOOD, FF_JPG_SUPERB),
FF_JPG2K (instead of FF_JPG2K_MIN, FF_JPG2K_GOOD, FF_JPG2K_SUPERB),
DTXT_IOTPDF (instead of DTXT_PDFIOT),
DTXT_IOTPDF_MRC (instead of DTXT_PDFIOT using MRC).

Note: the mentioned older formats can be used, but the newer ones are suggested.

The older formats provided 3 predefined levels (MIN, GOOD, SUPERB). The newer ones can be used with 5 different predefined levels (1-5) by calling kRecSetCompressionLevel.

In addition for PDF formats a trade-off setting is introduced (COMPRESSION_TRADEOFF, kRecSetCompressionTradeoff), which can speed up the used algorithm (producing a lower quality).

The higher compression level means lower compression and higher quality (i.e. greater file size). The older levels can be reproduced by newer ones if the trade-off is COMPRESSION_ADVANCED:

MIN - level 1,
GOOD - level 3,
SUPERB - level 5.

Furthermore, there is a customization possibility for manual tuning of quality with compression level 0.

Customization of JPGQuality

The quality of JPEG and JPEG2000 images can be tuned by the setting Kernel.IMF.JPG.Quality both in older and newer formats (either JPEG, JPEG2000 or non-MRC PDF). However, in newer formats the value of this setting is used only in compression level 0. For the predefined JPEG quality values of different compression levels see kRecSetJPGQuality.

Customization of quality for PDF formats

The older formats were customizable by different settings. If these settings were modified, their values were used during file creation.

The newer formats do not use some older settings:

Kernel.Imf.PDF.MRC.BWFormat,
Kernel.Imf.PDF.MRC.ColorFormat,
Kernel.Imf.PDF.MRC.JPGQualityBGMIN,
Kernel.Imf.PDF.MRC.JPGQualityBGGOOD,
Kernel.Imf.PDF.MRC.JPGQualityBGMAX,
Kernel.Imf.PDF.MRC.JPGQualityFGMAX.

Instead of the above settings new ones were introduced (see detailed descriptions):

Kernel.IMF.PDF.ColorFormat
Kernel.IMF.PDF.BWFormat
Kernel.IMF.PDF.MRC.EnableMultipleFG
Kernel.IMF.PDF.MRC.BGLayer.JPGQuality
Kernel.IMF.PDF.MRC.BGLayer.SubSampleRate
Kernel.IMF.PDF.MRC.BGLayer.Method
Kernel.IMF.PDF.MRC.BGLayer.ConsolidationStrength
Kernel.IMF.PDF.MRC.BGLayer.Smoothing
Kernel.IMF.PDF.MRC.BGLayer.DilatationSteps
Kernel.IMF.PDF.MRC.FGLayer.JPGQuality
Kernel.IMF.PDF.MRC.FGLayer.SubSampleRate
Kernel.IMF.PDF.MRC.FGLayer.Method
Kernel.IMF.PDF.MRC.SelLayer.SubSampleRate
Kernel.IMF.PDF.MRC.Selector.Method

Each compression level uses predefined values for these new settings. Selecting a non-0 compression level the predefined values are used during creation of file, even if the value of any new setting were changed manually. However compression level 0 uses the current value of these settings. For putting the predefined values of a non-0 compression level into these settings the function kRecSetMRCCompressionSettingsFromLevel can be used. See notes in the documentation of the function for details.

Note:: Older formats do not use the above mentioned new settings.

Orientation of page at saving a PDF

There are some saving functions that can affect on the orientation of the page, when they create a PDF file (kRecSaveImg, kRecSaveImgF, kRecSaveImgForce, kRecSaveImgForceF, kRecConvert2DTXTEx and kRecMakePagesSearchable). The orientation of the written page depends on the IMAGEINDEX parameter of these functions. In case of PDF output this parameter can get only the following values:

II_ORIGINAL - preserves the orientation of the loaded page and the text is rotated according to that orientation.
II_CURRENT - uses the orientation of the current (preprocessed) image, which is equal to the orientation of the readable text.

The result of using other IMAGEINDEX values is undefined.

However there are some exceptions:

II_CURRENT can be used when kRecPreprocessImg have been already called.
II_ORIGINAL can be used when this image exists. See the lifetime of the different images of the HPAGE.
II_ORIGINAL can be used also when HPAGE contains DataStream or when kRecMakePagesSearchable is called.

Note:

The older function kRecConvert2DTXT has no IMAGEINDEX parameter. Thus if it creates PDF output, the orientation of the page depends on the setting Kernel.Img.KeepOriginalImage as the followings:

if the setting is FALSE, the result of the function is the same as the one created by kRecConvert2DTXTEx using II_CURRENT image index.
if the setting is TRUE, the result of the function is the same as the one created by kRecConvert2DTXTEx using II_ORIGINAL image index.

Please note that the function kRecRecognize calls kRecConvert2DTXT (so not kRecConvert2DTXTEx) if its file name parameter is not empty. That's why it is recommended to use kRecConvert2DTXTEx instead.

An interesting trick, which can be useful sometimes: kRecMakePagesSearchable can changes 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 the IMAGEINDEX parameter).

Enumeration Type Documentation

enum COMPRESSION_TRADEOFF

Compression tradeoff.

This enum gives the possible values of the setting Kernel.Imf.CompressionTradeoff, which determines whether the fast or advanced compression method is used. This setting is used when FF_PDF and FF_PDF_MRC output is created. In both cases

FAST trade-off indicates usage of JPEG or TIFF G4 compression,
ADVANCED trade-off uses JPEG2000 or JBIG2 compression,

according to the bit-depth of the image. In case of FF_PDF_MRC the trade-off affects on the algorithms used for creating layers as well.

Enumerator:

COMPRESSION_ADVANCED	Use advanced but slower method (default).
COMPRESSION_FAST	Use fast compression method.

enum ENCRYPT_LEVEL

PDF encryption level.

PDF files may be protected by two types of password: an open (also known as user) password and a permissions (also known as owner or master) password. The open password protects the opening of the file. When a file requires an open password, OmniPage CSDK cannot open it without this, so an appropriate interface must be provided for the user to supply the password. If a file is protected by a permissions password, it must be supplied in order to grant or deny permissions for different file operations, such as copying content, printing or modifying. When a particular operation is prohibited, OmniPage CSDK does not allow the operation concerned. If text copying is prohibited from a PDF file with a text layer and a permissions password is not given, CSDK opens it as if it were an image-only PDF. If printing is prohibited and a permissions password is not given, the PDF file cannot be opened. When a file is protected by both an open and a permissions password, OmniPage CSDK requires only the permissions password for full access to be granted. See kRecGetPDFEncLevel.

Enumerator:

ENC_NOPAS	No need for any password at all.
ENC_MUSTPAS	This bit can be used only in bit combination. Password must be given. See `ENC_MUSTUSER`, `ENC_MUSTMASTER` and `ENC_MUSTANY`.
ENC_MASTER	Permissions password is needed, because text copying is prohibited. Without it, file is opened as image-only. It can also be used in bit combination, see `ENC_MUSTMASTER` and `ENC_MUSTANY`.
ENC_USER	This bit can be used only in bit combination. See `ENC_MUSTUSER` and `ENC_MUSTANY`.
ENC_MUSTUSER	The file is protected by an open password for opening. This is combination of bits `ENC_MUSTPAS` and `ENC_USER`.
ENC_MUSTMASTER	Permissions password is required for accessing the file. This is combination of bits `ENC_MUSTPAS` and `ENC_MASTER`.
ENC_MUSTANY	The file is protected by both password types. Giving the permissions password, the text content of the PDF is accessible. Giving the open password, PDF is loaded as image-only. This is a combination of the bits `ENC_MUSTPAS`, `ENC_USER` and `ENC_MASTER`.
ENC_NOACCESS	Unknown encryption mode. The file cannot be opened.

enum IMF_FORMAT

Image formats.

The supported image formats. The multi-page file types (TIFF, DCX, MAX, PDF, JBIG) can contain pages compressed by different methods in the same file. Thus image format must be given page-by-page.

Note:

Images to be loaded from image files into the Engine (or to be stored to disk from the Engine) can be in different formats. The main attributes of these files are:

the image type, i.e. the bit depth (B/W, 4 or 8-bit grayscale or color),
whether the image file contains only one or more images,
what kind of image compression has been used, if any.

The Engine does not support all the file formats listed here in the same way. Some of them can be read but cannot be created; other formats are supported by the Engine only for B/W images, etc.

Currently the FF_PDA, FF_BMP_RLE4 formats are not supported at all.
The FF_PCX, FF_DCX, FF_BMP_NO, FF_BMP_RLE8, FF_TIFNO, FF_TIFPB, and FF_PNG are supported by the Engine for both reading and writing and for all image types (B/W, 4-bit grayscale, 8-bit grayscale, 8-bit palette-color and 24-bit true-color).
Some other TIFF formats like FF_TIFHU, FF_TIFG31, FF_TIFG32, FF_TIFG4 and the FF_SIM formats support reading and writing B/W images only.
The three JPEG formats and FF_TIFJPGNEW images are supported by the Engine only for 8-bit grayscale and 24-bit color images.
If a 4-bit grayscale image in the Engine is to be saved to JPEG format, it will be automatically converted to an 8-bit grayscale one. Saving a B/W image into JPEG format is not supported.
With this toolkit version, the support of the At Work Document images (FF_AWD) has been removed. Microsoft no longer supports this format either.
Image formats supporting multi-page image files are the different TIFF formats, DCX, PDF, JBIG and the PaperPort MAX formats.
Both PDF input and output are supported on: Windows, Linux and on Mac OS X. In addition PDF output is also supported on Embedded Linux. This information is true also for PDF_MRC.
For more information about PDF output see PDF Output in CSDK 20.

In addition to the image file formats above, the Engine also supports TIFF-FX files for reading.

See notes of kRecSetJPGQuality for more information about the different JPEG and JPEG2000 formats.

For more detail on the supported image file formats see the topic Image File Format List.

Enumerator:

FF_TIFNO	Uncompressed TIFF image format.
FF_TIFPB	Packbits TIFF image format.
FF_TIFHU	Group 3 Modified TIFF image format.
FF_TIFG31	Standard G3 1D TIFF image format.
FF_TIFG32	Standard G3 2D TIFF image format.
FF_TIFG4	Standard G4 TIFF image format.
FF_TIFLZW	TIFF-LZW image format incorporating Unisys compression.
FF_PCX	PCX format.
FF_DCX	DCX format.
FF_SIM	Simple file format. Supported on: Windows, Linux, Embedded Linux, Mac OS X.
FF_BMP_NO	Windows bitmap format without compression.
FF_BMP_RLE8	Windows bitmap RLE8 format.
FF_BMP_RLE4	Windows bitmap RLE4 format. Only for reading!
FF_AWD	Not supported!
FF_JPG_SUPERB	Deprecated (see usage of new formats). JPEG format with negligible information loss.
FF_JPG_LOSSLESS	Deprecated, same as FF_JPG_SUPERB.
FF_JPG_GOOD	Deprecated (see usage of new formats). JPEG format with average information loss. (Results in medium-size image files when saving.)
FF_JPG_MIN	Deprecated (see usage of new formats). JPEG format optimized for minimum image file size. Worst image quality.
FF_PDA	Caere's proprietary compound document format. Only for reading! Only images with a single zone are supported!
FF_PNG	Portable Image format for Network Graphics.
FF_XIFF	TIFF-FX format. Only for reading! Supported on: Windows 32-bit.
FF_GIF	GIF image format incorporating Unisys compression.
FF_MAX_LOSSLESS	PaperPort MAX file format without information loss. Only for reading! Supported on: Windows 32-bit.
FF_MAX_GOOD	PaperPort MAX file format with average information loss. Only for reading! Supported on: Windows 32-bit.
FF_MAX_MIN	PaperPort MAX file format optimized for minimum image file size. Only for reading! Supported on: Windows 32-bit.
FF_PGX	Only for internal use!
FF_PDF_MIN	Deprecated (see usage of new formats). Adobe PDF format. Minimum image file size. Supported on: Windows, Linux, Embedded Linux.
FF_PDF_GOOD	Deprecated (see usage of new formats). Adobe PDF format. Results in medium-size image files when saving. Supported on: Windows, Linux, Embedded Linux.
FF_PDF_SUPERB	Deprecated (see usage of new formats). Adobe PDF format with negligible information loss. Supported on: Windows, Linux, Embedded Linux.
FF_PDF_LOSSLESS	Deprecated, use FF_PDF_SUPERB instead.
FF_PDF_MRC_MIN	Deprecated (see usage of new formats). Adobe PDF format with MRC technology. Optimized for minimum image file size. Supported on: Windows, Linux, Embedded Linux.
FF_PDF_MRC_GOOD	Deprecated (see usage of new formats). Adobe PDF format with MRC technology. (Results in medium-size image files when saving.) Supported on: Windows, Linux, Embedded Linux.
FF_PDF_MRC_SUPERB	Deprecated (see usage of new formats). Adobe PDF format with MRC technology. PDF with small information loss. Supported on: Windows, Linux, Embedded Linux.
FF_PDF_MRC_LOSSLESS	Deprecated, use FF_PDF_MRC_SUPERB instead.
FF_TIFJPGNEW	New JPG Compressed TIFF image format.
FF_JPG2K_SUPERB	Deprecated (see usage of new formats). JPEG2000 file format. Negligible information loss.
FF_JPG2K_LOSSLESS	Deprecated, same as FF_JPG2K_SUPERB.
FF_JPG2K_GOOD	Deprecated (see usage of new formats). JPEG2000 file format. Results in medium-size image files when saving.
FF_JPG2K_MIN	Deprecated (see usage of new formats). JPEG2000 file format. Optimized for minimum image file size.
FF_JBIG2_LOSSLESS	JBIG2 file format. Lossless image saving.
FF_JBIG2_LOSSY	JBIG2 file format. Optimized for minimum image file size.
FF_XPS	XPS file format. Supported on: Windows.
FF_WMP	Microsoft HD Photo (Windows Media Photo). Supported on: Windows.
FF_JBIG	JBIG format. Only for reading! Supported on: Windows.
FF_OPG	"OmniPageCSDK" HPAGE serialization format. One-page format, not appendable. OPG file contains all members of the `HPAGE` including images, zones, letters and other internal information stored by `HPAGE`. Binary images, not image-only PDF images and palette-color images are saved using lossless compression, true-color and gray-scale images are saved using lossy compression. When OPG is being saved kRecSaveImg, kRecSaveImgF and kRecSaveImgForceF do not use their `iiImg` parameter, kRecSaveImgArea and kRecSaveImgAreaF do not use their `iiImg` and `pRect` parameters. Loading an OPG file restores the saved `HPAGE`. Primary image conversion is not applied when OPG file is loaded.
FF_PDF	Adobe PDF format with changeable compression level (see usage of new formats). Supported on: Windows, Linux, Embedded Linux.
FF_PDF_MRC	Adobe PDF format using MRC technology with changeable compression level (see usage of new formats). Supported on: Windows, Linux, Embedded Linux.
FF_JPG	JPEG format with changeable compression level (see usage of new formats). Supported on: Windows, Linux, Embedded Linux.
FF_JPG2K	JPEG2000 file format with changeable compression level (see usage of new formats). Supported on: Windows, Linux, Embedded Linux.
FF_TIF	TIF file format with changeable compression and compression level (see usage of new formats). Supported on: Windows, Linux, Embedded Linux.
FF_SIZE	Number of supported image file formats.

enum IMF_IMAGEQUALITY

Image quality (for DTXT PDF output)

This enum gives the possible values of Kernel.DTxt.PDF.BWQuality and ...ColorQuality. See also the section PDF output in KernelAPI.

Enumerator:

IMF_IMAGEQUALITY_MIN	Minimal size, lowest quality.
IMF_IMAGEQUALITY_GOOD	Medium size, good quality.
IMF_IMAGEQUALITY_SUPERB	Large size, best quality.

enum IMF_MRCLEVEL

MRC level (for DTXT PDF output)

This enum gives the possible values of the setting Kernel.DTxt.PDF.UseMRC, which determines the MRC method used for DTXT PDF output. See also the section PDF output in KernelAPI.

Enumerator:

IMF_MRCLEVEL_NO	Do not use MRC.
IMF_MRCLEVEL_MIN	Minimal size, lowest quality.
IMF_MRCLEVEL_GOOD	Medium size, good quality.
IMF_MRCLEVEL_SUPERB	Large size, best quality.

enum IMF_PDFCOMPATIBILITY

PDF compatibility (for saving PDF with KernelAPI)

This enum gives the possible values of the setting Kernel.Imf.PDF.Compatibility, which is used during saving image-only or image-on-text PDF files. See also the section PDF output in KernelAPI.

Enumerator:

IMF_PDF_FORCESIZE	Optimized for size.
IMF_PDF_FORCEQUALITY	Optimized for quality.
IMF_PDF15	PDF 1.5.
IMF_PDF14	PDF 1.4.
IMF_PDF13	PDF 1.3.
IMF_PDF12	PDF 1.2.
IMF_PDF11	PDF 1.1.
IMF_PDF10	PDF 1.0.
IMF_PDFA	PDF/A-1b compliant output (deprecated version of IMF_PDFA1B)
IMF_PDFA1B	PDF/A-1b compliant output.
IMF_PDF16	PDF 1.6.
IMF_PDF17	PDF 1.7.
IMF_PDFA2B	PDF/A-2b compliant output.
IMF_PDFA2U	PDF/A-2u compliant output.
IMF_PDFA1A	PDF/A-1a compliant output.
IMF_PDFA2A	PDF/A-2a compliant output.
IMF_PDFA3B	PDF/A-3b compliant output.
IMF_PDFA3U	PDF/A-3u compliant output.
IMF_PDFA3A	PDF/A-3a compliant output.
IMF_PDF20	PDF 2.0.

enum IMF_PDFENCRYPTION

PDF encryption types.

PDF files may be saved with different encryption types. The setting Kernel.Imf.PDF.PDFSecurity.Type gets one of the values listed below for specifying the used encryption type. See also the description of saving encrypted PDF.

Enumerator:

IMF_PDFSECURITY_NONE	There is no encryption.
IMF_PDFSECURITY_STANDARD	Standard, 40 bit encryption.
IMF_PDFSECURITY_ENHANCED	Enhanced, 128 bit encryption.
IMF_PDFSECURITY_AES	AES 128 bit encryption.
IMF_PDFSECURITY_AES256	AES 256 bit encryption.
IMF_PDFSECURITY_AES256X	AES 256 bit encryption with hardened hash.

Function Documentation

RECERR RECAPIKRN kRecCloseImgFile ( HIMGFILE hIFile )

Closing an image file.

This function closes an image file opened by kRecOpenImgFile.

Parameters:

[in] hIFile Handle of the image file.

Return values:

RECERR

Note:

The specification of this function in C# is:

 RECERR kRecCloseImgFile(IntPtr pHIMGFILE);

RECERR RECAPIKRN kRecCopyImgFilePage	(	int	sid,
		HIMGFILE	hIFileDst,
		int	ndstPage,
		HIMGFILE	hIFileSrc,
		int	nsrcPage
	)

Copying a page between TIFF files.

The kRecCopyImgFilePage function copies a page from a source TIFF image file and inserts it into a destination TIFF image file.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hIFileDst	Handle of the destination TIFF image file opened by kRecOpenImgFile for writing.
[in]	ndstPage	Page number of the page in the destination image file, before which the page should be copied, -1 means append. To insert the page as the first page in the image file, the value zero (0) should be specified.
[in]	hIFileSrc	Handle of the source TIFF image file opened by kRecOpenImgFile for reading.
[in]	nsrcPage	Page number of the page in the source image file to be copied from. For a single-page source image file a value of zero (0) should be specified.

Return values:

RECERR

Note:

In order to save time, this operation is performed without decompressing the page.

This function belongs to the Multi-page TIFF File Handling Function Group. To use these functions, the pages in the multi-page TIFF file must be stored in One-strip format and the StripBytesCount TIFF tag must exist in the page header. Note that TIFF image files created by OmniPage CSDK fulfil this requirement.

The specification of this function in C# is:

 RECERR kRecCopyImgFilePage(int sid, IntPtr hIFileDst, int ndstPage, IntPtr hIFileSrc, int nsrcPage);

RECERR RECAPIKRN kRecDecompressImgDataStream	(	int	sid,
		HPAGE	hPage
	)

Decompressing a DataStream.

This function decompresses the DataStream of the given HPAGE loaded by kRecLoadImgDataStream or kRecLoadImgDataStreamF.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page containing the DataStream.

Return values:

RECERR

Note:

This function is deprecated. All CSDK functions can decompress the image automatically if the decompressed image is needed.

This function works on an HPAGE contaning DataStream. See the details about possible operations and their working in the documentation of DataStream. If hPage does not contain DataStream, or DataStream already has been decompressed the function returns REC_OK without doing anything.

After calling this function hPage will contain both the compressed DataStream and the decompressed image.

The specification of this function in C# is:

 RECERR kRecDecompressImgDataStream(int sid, IntPtr hPage);

RECERR RECAPIKRN kRecDeleteImgFilePage	(	int	sid,
		HIMGFILE	hIFile,
		int	nPage
	)

Removing a page from a TIFF file.

The kRecDeleteImgFilePage deletes a page from a TIFF image file.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hIFile	Handle of the multi-page TIFF image file.
[in]	nPage	Page number of the page to be deleted. The value zero (0) means the first page of the file.

Return values:

RECERR

Note:

The kRecDeleteImgFilePage function does not delete the selected page physically from the multi-page TIFF image file. The kRecPackImgFile function can remove any previously deleted (or updated) page.

The kRecDeleteImgFilePage deletes the page logically also from a one-page TIFF file. In this case, most image viewers cannot open the resulting file. But the CSDK functions can handle such a file, so it can be opened, closed and packed; its page count can be queried and pages can be inserted into it. If kRecPackImgFile gets such a file it removes the page physically and the resulting pageless file can be handled in the same way.

This function belongs to the Multi-page TIFF File Handling Function Group. To use these functions, the pages in the multi-page TIFF file must be stored in One-strip format and the StripBytesCount TIFF tag must exist in the page header. Note that TIFF image files created by the OmniPage CSDK fulfils this requirement.

The specification of this function in C# is:

 RECERR kRecDeleteImgFilePage(int sid, IntPtr hIFile, int nPage);

RECERR RECAPIKRN kRecFreeImgDataStream	(	int	sid,
		HPAGE	hPage
	)

Deleting DataStream from an HPAGE.

This function deletes the uncompressed DataStream from the HPAGE loaded by kRecLoadImgDataStream or kRecLoadImgDataStreamF.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page containing the DataStream.

Return values:

RECERR

Note:

This function works on an HPAGE contaning DataStream. See the details about possible operations and their working in the documentation of DataStream. If hPage does not contain DataStream the function returns API_PARAMETER_ERR. kRecFreeImg function frees the whole HPAGE (including DataStream), so in typical workflow this function should not be called.

The specification of this function in C# is:

 RECERR kRecFreeImgDataStream(int sid, IntPtr hPage);

RECERR RECAPIKRN kRecGetCompressionLevel	(	int	sid,
		int *	pCompressionLevel
	)

Getting the compression level.

This function retrieves the compression level used when an image is saved to specific formats.

Parameters:

[in]	sid	Settings Collection ID.
[out]	pCompressionLevel	Pointer of a variable to store the current compression level.

Return values:

RECERR

Note:

This function gets the value of the setting Kernel.Imf.CompressionLevel.

The compression level can be set by kRecSetCompressionLevel.

The specification of this function in C# is:

 RECERR kRecGetCompressionLevel(int sid, out int CompressionLevel);

RECERR RECAPIKRN kRecGetCompressionTradeoff	(	int	sid,
		COMPRESSION_TRADEOFF *	pCompressionTradeoff
	)

Getting the compression tradeoff.

This function gets the compression trade-off used when an image is saved to specific formats.

Parameters:

[in]	sid	Settings Collection ID.
[out]	pCompressionTradeoff	Pointer of a variable to store the current compression tradeoff.

Return values:

RECERR

Note:

This function gets the value of the setting Kernel.Imf.CompressionTradeoff.

The compression level can be set by kRecSetCompressionTradeoff.

The specification of this function in C# is:

 RECERR kRecGetCompressionTradeoff(int sid, out int CompressionTradeoff);

RECERR RECAPIKRN kRecGetImfLoadFlags	(	int	sid,
		DWORD *	pfFlag
	)

Getting IMF PDF load flags.

The kRecGetImfLoadFlags function get the current IMF Load Flags.

Parameters:

[in]	sid	Settings Collection ID.
[out]	pfFlag	The IMF Load Flag combination

Return values:

RECERR

Note:

This function gets the setting Kernel.Imf.PDF.LoadFlags. This setting can be chaged by kRecSetImfLoadFlags.

The specification of this function in C# is:

 RECERR kRecGetImfLoadFlags(int sid, out uint fFlag);

RECERR RECAPIKRN kRecGetImgFilePageCount	(	HIMGFILE	hIFile,
		int *	lpPageCount
	)

Getting the number of pages in an image file.

The kRecGetImgFilePageCount function inquires the number of pages in an image file. With this function there is no need to load the pages of an image file to find out their number.

Parameters:

[in]	hIFile	Handle of the image file opened by kRecOpenImgFile to be examined.
[out]	lpPageCount	Pointer of a variable to get the number of pages.

Return values:

RECERR

Note:

The HIMGFILE passed to this function can be opened for writing as well.

The specification of this function in C# is:

 RECERR kRecGetImgFilePageCount(IntPtr hIFile, out int pPageCount);

RECERR RECAPIKRN kRecGetImgFilePageIndex	(	HIMGFILE	hIFile,
		int *	pIndex
	)

Getting the index of the current page.

This function retrieves the current index of the page counter. The page counter holds the index of the page to be read from a multi-page image file by a subsequent image loader function call kRecLoadImg passing a IMGF_NEXTPAGE parameter.

Parameters:

[in]	hIFile	Handle of the file.
[out]	pIndex	Pointer of a variable to store the index of the page. It is a zero-based index. If the latest page has been loaded, it is -1.

Return values:

RECERR

Note:

The specification of this function in C# is:

 RECERR kRecGetImgFilePageIndex(IntPtr hIFile, out int pIndex);

RECERR RECAPIKRN kRecGetImgFilePageInfo	(	int	sid,
		HIMGFILE	hIFile,
		int	nPage,
		LPIMG_INFO	pImg,
		IMF_FORMAT *	pFormat
	)

Getting information about a page of an image file.

The kRecGetImgFilePageInfo function inquires the size, resolution and other attributes of the specified page of an image file.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hIFile	Handle of the image file.
[in]	nPage	Pagenumber of the required page.
[out]	pImg	Address of the structure to get the page information.
[out]	pFormat	Pointer of a variable to get the compression format of the page.

Return values:

RECERR

Note:

The use of this function does not influence current page counter etc. settings when reading from a multi-page image file using subsequent kRecLoadImg calls.

In case of PDF and XPS files this function needs to load the page for determining its color-depth. However, this loading can fail if the dimension of the page is out of the enabled range (Kernel.Img.Max.Pix.X and ...Y and Kernel.Img.Min.Pix.X and ...Y). In such a case this function returns with IMG_SIZE_ERR.

The specification of this function in C# is:

 RECERR kRecGetImgFilePageInfo(int sid, IntPtr hIFile, int nPage, out IMG_INFO pImg, out IMF_FORMAT pFormat);

RECERR RECAPIKRN kRecGetJPGQuality	(	int	sid,
		int *	pnQuality
	)

Getting JPEG quality.

This function retrieves the JPEG quality setting used when images were saved into JPEG or JPEG2000 files.

Parameters:

[in]	sid	Settings Collection ID.
[out]	pnQuality	JPEG quality.

Return values:

RECERR

Note:

This function gets the value of the setting Kernel.Imf.JPG.Quality. This setting can be changed by kRecSetJPGQuality.

The specification of this function in C# is:

 RECERR kRecGetJPGQuality(int sid, out int nQuality);

RECERR RECAPIKRN kRecGetPDFEncLevel	(	HIMGFILE	hIFile,
		ENCRYPT_LEVEL *	pEncLev
	)

This function retrieves the encryption level of the opened PDF. For more information see ENCRYPT_LEVEL and Handling Encrypted PDF Files.

Parameters:

[in]	hIFile	Handle of the image file.
[out]	pEncLev	Pointer of a variable to store the encryption level.

Return values:

RECERR

Note:

The specification of this function in C# is:

 RECERR kRecGetPDFEncLevel(IntPtr hIFile, out ENCRYPT_LEVEL pEncLev);

RECERR RECAPIKRN kRecGetPdfTagInfo	(	int	sid,
		INTBOOL *	pbUseTagInfo
	)

Getting the use of PDF tag information.

This function gets whether the Engine is set to use the tag information of the PDF file or not. For more information see kRecSetPdfTagInfo.

Parameters:

[in]	sid	Settings Collection ID.
[out]	pbUseTagInfo	Pointer of a variable to store whether the Engine is set to use tag information. If it is TRUE the tag information is used.

Return values:

RECERR

Note:

The specification of this function in C# is:

 RECERR kRecGetPdfTagInfo(int sid, out bool pbUseTagInfo);

RECERR RECAPIKRN kRecInsertImgFilePage	(	int	sid,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		HIMGFILE	hIFile,
		int	nPage,
		IMF_FORMAT	format
	)

Inserting a page into a TIFF file.

The kRecInsertImgFilePage function inserts a compressed image into a TIFF image file.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page containing the image to be inserted.
[in]	iiImg	Index of the image to be inserted.
[in]	hIFile	Handle of the multi-page TIFF image file.
[in]	nPage	Page number of the page in the image file before which the new page should be inserted. To insert the page as the first page in the image file, the value zero (0) should be specified.
[in]	format	Image file format (compression) to be applied to the page. Of course, only the TIFF formats can be selected.

Return values:

RECERR

Note:

This function belongs to the Multi-page TIFF File Handling Function Group. To use these functions, the pages in the multi-page TIFF file must be stored in One-strip format and the StripBytesCount TIFF tag must exist in the page header. TIFF image files created by OmniPage CSDK fulfil this requirement.

The specification of this function in C# is:

 RECERR kRecInsertImgFilePage(int sid, IntPtr hPage, IMAGEINDEX iiImg, IntPtr hIFile, int nPage, IMF_FORMAT format);

RECERR RECAPIKRN kRecIsMultipageImgFileFormat	(	IMF_FORMAT	imgfileformat,
		INTBOOL *	bEnabled
	)

Checking multi-page capability of an image format.

The kRecIsMultipageImgFileFormat function checks whether the specified image file format can handle multi-page image files.

Parameters:

[in]	imgfileformat	Selected image file format to be checked.
[out]	bEnabled	Pointer of a Boolean variable to get the information. The returned value of TRUE means that the selected image file format supports multi-page images.

Return values:

RECERR

Note:

OmniPage Capture SDK supports the following multi-page image file formats for reading: DCX, MAX, PDF, TIFF and TIFF-FX. Multi-page image file formats supported for writing are DCX, MAX, TIFF and image-only PDF.

The specification of this function in C# is:

 RECERR kRecIsMultipageImgFileFormat(IMF_FORMAT imgfileformat, out bool bEnabled);

RECERR RECAPIKRN kRecLoadImg	(	int	sid,
		HIMGFILE	hIFile,
		HPAGE *	phPage,
		int	iPage
	)

Loading a page from an opened image file.

The kRecLoadImg function loads a page from an image file opened by kRecOpenImgFile into the image management module.

If the image source provides a gray-scale image, this function can convert it to B/W. If the image source provides a 24-bit color image, this function can convert it to gray-scale or B/W. The way this function handles the different image types (such as B/W, gray-scale or 24-bit color images) is called primary image conversion mode. The conversion mode to be applied can be set by the kRecSetImgConvMode API function. This function should also be used for subsequent access to pages of multi-page image files. The kRecLoadImg function activates the PID_IMGINPUT process. The PID_SCANNER_WARMUP process might also be activated by using image file handle IMGF_SCANNER.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hIFile	Handle of the image file.
[out]	phPage	Address of a variable to store the handle of the created page.
[in]	iPage	The page number of the page to be loaded. IMGF_NEXTPAGE means the next page.

Return values:

RECERR

Note:

Not all the image formats are supported on all platforms. For details see the description of IMF_FORMAT.

See details about size limits of input images.

During loading, the 4-bit gray-scale images are converted into an 8-bit gray-scale format, and 4-bit palette color images are converted into the 8-bit palette color format.

If the bits per pixel value of the image file is not one of the supported values, the function returns IMG_BITSPERPIXEL_ERR. See the table of supported file formats.

When the page is no longer needed, the application should call the kRecFreeImg function which removes the page from the image management module.

This function is fairly fault-tolerant: an image is loaded even if some errors occur. If the phPage output parameter contains a NULL value, the image has not been loaded into the Engine. If the function returns an error but phPage is not NULL then you may have a corrupted image loaded. It gives an IMG_DPI_WARN warning when the resolution is less than 75 DPI or greater than 2400 DPI, but of course the image is loaded and in this case it is not corrupted. It is strongly recommended to handle the return code of this function properly.

If the input is JPEG file, the function can analyse exif info in order to determine the orientation and resolution of the image, see: Kernel.Imf.JPG.Resolution, JPG_RESOLUTION, Kernel.Imf.JPG.Orientation, JPG_ORIENTATION.

After having successfully loaded an image, its attributes can be inquired by calling the kRecGetImgInfo function. For JPG, TIF and PDF files additional information can be inquired by calling the kRecGetImgMetaData function.

If the input is JPEG, JPEG2000 or TIFF using 'new style' JPEG, this function can load the compressed data stream without decompressing, See the details about possible operations and their working in the documentation of DataStream.

If the input is JPG file, the function analyses exif info in order to determine whether the image is captured by digital camera (phone) or not, and sets IMG_FLAGS_CAMERAIMAGE flag accordingly see: IMG_FLAGS.

You can read pages of a multi-page image file one after the other by calling this function repeatedly with a IMGF_NEXTPAGE pagenumber, since each subsequent call automatically increments the page counter by 1. While the kRecGetImgFilePageCount function inquires the number of pages in an image file, the kRecGetImgFilePageIndex provides the current index of the page counter. When loading from an exact page number, the page counter is set to the given one, thus specifying IMGF_NEXTPAGE directly after loading, the 5th page (passing 5 in iPage) loads the 6th page.

Processing the pages of a multi-page image file:

    RECERR rc;
    int nPages;
    HPAGE hPage;
    char *imgfile = "imgfile.tif";
    HIMGFILE hIFile = NULL;
    rc = kRecOpenImgFile( imgfile, &hIFile, IMGF_READ, (IMF_FORMAT)0);
    rc = kRecGetImgFilePageCount(hIFile, &nPages);
    for (int i = 0; i < nPages; i++)  {
      rc = kRecLoadImg(sid, hIFile, &hPage, IMGF_NEXTPAGE);
      if (rc != REC_OK) {
        kRecCloseImgFile(hIFile);
        // . . . Some error handling . . .
        return;
      }
      // . . .
      // do something
      // (e.g: save part of the image or call kRecRecognize)
      // . . .
      rc = kRecFreeImg(hPage);
    }
    kRecCloseImgFile(hIFile);

The specification of this function in C# is:

 RECERR kRecLoadImg(int sid, IntPtr hIFile, out IntPtr phPage, int page);

RECERR RECAPIKRN kRecLoadImgDataStream	(	int	sid,
		HIMGFILE	hIFile,
		HPAGE *	phPage,
		int	iPage
	)

Loading a page from an opened image file without decompressing the image.

The kRecLoadImgDataStream function loads a page from an image file opened by kRecOpenImgFile without decompressing the image.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hIFile	Handle of the image file.
[out]	phPage	Address of a variable to store the handle of the created page.
[in]	iPage	The page number of the page to be loaded. IMGF_NEXTPAGE means the next page.

Return values:

RECERR

Note:

This function supports only JPEG, JPEG2000 and TIFF using 'new style' JPEG input formats.

The returned HPAGE does not contain decompressed bitmap. See the details about possible operations and their working in the documentation of DataStream.

See details about size limits of input images.

You can read pages of a multi-page image file one after the other by calling this function repeatedly with a IMGF_NEXTPAGE pagenumber, since each subsequent call automatically increments the page counter by 1. While the kRecGetImgFilePageCount function inquires the number of pages in an image file, the kRecGetImgFilePageIndex provides the current index of the page counter. When loading from an exact page number, the page counter is set to the given one, thus specifying IMGF_NEXTPAGE directly after loading, the 5th page (passing 5 in iPage) loads the 6th page.

When the page is no longer needed, the application should call the kRecFreeImg function which removes the page from the image management module.

The specification of this function in C# is:

 RECERR kRecLoadImgDataStream(int sid, IntPtr hIFile, out IntPtr phPage, int page);

RECERR RECAPIKRN kRecLoadImgDataStreamF	(	int	sid,
		LPCTSTR	pFilename,
		HPAGE *	phPage,
		int	nPage
	)

Loading a page directly from an image file without decompressing the image.

This function loads a page from the specified image file without decompressing the image.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pFilename	Path of the image file.
[out]	phPage	Pointer of a variable to store the handle of the page.
[in]	nPage	The page number of the page to be loaded.

Return values:

RECERR

Note:

This function opens the file, loads the given page and closes the file as well.

This function supports only JPEG, JPEG2000 and TIFF using 'new style' JPEG input formats.

The returned HPAGE does not contain decompressed bitmap. See the details about possible operations and their working in the documentation of DataStream.

See details about size limits of input images.

When the page is no longer needed, the application should call the kRecFreeImg function which removes the page from the image management module.

The specification of this function in C# is:

 RECERR kRecLoadImgDataStreamF(int sid, string filename, out IntPtr phPage, int page);

RECERR RECAPIKRN kRecLoadImgDataStreamMC	(	int	sid,
		BYTE *	lpBuf,
		size_t	bufLen,
		LPCOMPRESSED_IMG_INFO	lpCImg,
		HPAGE *	phPage
	)

Loading a page directly from a compressed memory buffer without decompressing the image.

This function loads a page from the specified compressed memory buffer. The image is not decompressed during the operation, thus the resulted HPAGE contains a DataStream only.

Parameters:

[in]	sid	Settings Collection ID.
[in]	lpBuf	Buffer of the compressed bitmap to be loaded.
[in]	bufLen	Length of the buffer containing the compressed bitmap.
[in]	lpCImg	Compressed image information of the image to be loaded.
[out]	phPage	Pointer of a variable to store the handle of the page.

Return values:

RECERR

Note:

The returned HPAGE does not contain decompressed bitmap. See the details about possible operations and their working in the documentation of DataStream.

See details about size limits of input images.

The specification of this function in C# is:

 RECERR kRecLoadImgDataStreamMC(int sid, [In] byte[] lpBuf, [In] int bufLen, [In] COMPRESSED_IMG_INFO lpCImg, out IntPtr phPage);

RECERR RECAPIKRN kRecLoadImgF	(	int	sid,
		LPCTSTR	pFilename,
		HPAGE *	phPage,
		int	nPage
	)

Loading a page directly from an image file.

This function loads a page from the specified image file.

If the image source provides a gray-scale image, this function can convert it to B/W. If the image source provides a 24-bit color image, this function can convert it to gray-scale or B/W. The way this function handles the different image types (such as B/W, gray-scale or 24-bit color images) is called primary image conversion mode. The conversion mode to be applied can be set by the kRecSetImgConvMode API function. This function should also be used for subsequent access to pages of multi-page image files. The kRecLoadImgF function activates the PID_IMGINPUT process.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pFilename	Path of the image file.
[out]	phPage	Pointer of a variable to store the handle of the page.
[in]	nPage	The page number of the page to be loaded.

Return values:

RECERR

Note:

Not all the image formats are supported on all platforms. For details see the description of IMF_FORMAT.

See details about size limits of input images.

When loading, the 4-bit gray-scale images are converted into an 8-bit gray-scale format, and 4-bit palette color images are converted into the 8-bit palette color format.

If the bits per pixel value of the image file is not one of the supported values, the function returns IMG_BITSPERPIXEL_ERR. See the table of supported file formats.

When the page is no longer needed, the application should call the kRecFreeImg function which removes the page from the image management module.

This function is fairly fault-tolerant: an image is loaded even if some errors occur. If the phPage output parameter contains a NULL value, the image has not been loaded into the Engine. If the function returns an error but phPage is not NULL you may have a corrupted image loaded. It gives an IMG_DPI_WARN warning when the resolution is less than 75 DPI or greater than 2400 DPI, but of course the image is loaded and in this case it is not corrupted. It is strongly recommended to handle the return code of this function properly.

After an image has been successfully loaded, its attributes can be inquired by calling the kRecGetImgInfo function.

If the input is JPEG, JPEG2000 or TIFF using 'new style' JPEG, this function can load the compressed data stream without decompressing, See the details about possible operations and their working in the documentation of DataStream.

This function opens the file, loads the given page and closes the file as well. So it is typically used for loading only one page from the file. For subsequent processing of multiple pages from a file, the function kRecLoadImg can be used more efficiently.

The specification of this function in C# is:

 RECERR kRecLoadImgF(int sid, string filename, out IntPtr phPage, int page);

RECERR RECAPIKRN kRecLoadImgM	(	int	sid,
		BYTE *	lpBitmap,
		LPCIMG_INFO	lpImg,
		HPAGE *	phPage
	)

Loading a page directly from a memory buffer.

This function loads a page from the specified memory buffer.

If the image source provides a gray-scale image, this function can convert it to B/W. If the image source provides a 24-bit color image, this function can convert it to gray-scale or B/W. The way this function handles the different image types (such as B/W, gray-scale or 24-bit color images) is called primary image conversion mode. The conversion mode to be applied can be set by the kRecSetImgConvMode API function. The kRecLoadImgM function activates the PID_IMGINPUT process.

Parameters:

[in]	sid	Settings Collection ID.
[in]	lpBitmap	Buffer of the bitmap to be loaded.
[in]	lpImg	Image information of the image to be loaded.
[out]	phPage	Pointer of a variable to store the handle of the page.

Return values:

RECERR

Note:

See details about size limits of input images.

When loading B/W images, the CSDK considers the one (1) bits as black pixels, and the zero (0) bits as white pixels.

When loading, the 4-bit gray-scale images are converted into an 8-bit gray-scale format, and 4-bit palette color images are converted into 8-bit palette color format.

When loading a 24-bit color image the order of the components can be BGR or RGB and can be specified by calling kRecSetImgFormat.

When loading a 32-bit color image the order of the components can be BGRA or ARGB and can be specified by calling kRecSetImgFormat. In this case the alpha component is ignored and the image is converted to a 24-bit one.

When the page is no longer needed, the application should call the kRecFreeImg function which removes the page from the image management module.

This function is fairly fault-tolerant: an image is loaded even if some errors occur. If the phPage output parameter contains a NULL value, the image has not been loaded into the Engine. If the function returns an error but phPage is not NULL you may have a corrupted image loaded. It gives an IMG_DPI_WARN warning when the resolution is less than 75 DPI or greater than 2400 DPI, but of course the image is loaded and in this case it is not corrupted. It is strongly recommended to handle the return code of this function properly.

The specification of this function in C# is:

 RECERR kRecLoadImgM(int sid, [In] byte[] lpBitmap, [In] IMG_INFO lpImg, out IntPtr phPage);

RECERR RECAPIKRN kRecLoadImgMC	(	int	sid,
		BYTE *	lpBuf,
		size_t	bufLen,
		LPCCOMPRESSED_IMG_INFO	lpCImg,
		HPAGE *	phPage
	)

Loading a page directly from a compressed memory buffer.

This function loads a page from the specified compressed memory buffer. It decompresses the compressed memory buffer and directly calls kRecLoadImgM to load the page. See kRecLoadImgM for more details!

Parameters:

[in]	sid	Settings Collection ID.
[in]	lpBuf	Buffer of the compressed bitmap to be loaded.
[in]	bufLen	Length of the buffer containing the compressed bitmap.
[in]	lpCImg	Compressed image information of the image to be loaded.
[out]	phPage	Pointer of a variable to store the handle of the page.

Return values:

RECERR

Note:

See details about size limits of input images.

The specification of this function in C# is:

 RECERR kRecLoadImgMC(int sid, [In] byte[] lpBuf, [In] int bufLen, [In] COMPRESSED_IMG_INFO lpCImg, out IntPtr phPage);

RECERR RECAPIKRN kRecMatchImgFileFormat	(	int	sid,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		IMF_FORMAT	imgfileformat,
		INTBOOL *	match
	)

Checking whether an image is suitable for a file format.

The kRecMatchImgFileFormat function checks whether the specified image can be saved in the specified image file format.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page containing the image to be checked.
[in]	iiImg	Index of the image to be checked.
[in]	imgfileformat	Selected image file format.
[out]	match	Address of a Boolean variable to get the information. The returned value of TRUE means that the selected image file format can be used on the image.

Return values:

RECERR

Note:

There are various considerations to be taken into account for the different image types. They can be found in the reference for IMF_FORMAT.

The specification of this function in C# is:

 RECERR kRecMatchImgFileFormat(int sid, IntPtr hPage, IMAGEINDEX iiImg, IMF_FORMAT imgfileformat, out bool match);

RECERR RECAPIKRN kRecOpenImgFile	(	LPCTSTR	pFilename,
		HIMGFILE *	pHIMGFILE,
		int	mode,
		IMF_FORMAT	filetype
	)

Opening an image file.

This function opens an image file into the image file management module. Loading an image requires an additional loading step (kRecLoadImg).

Parameters:

[in]	pFilename	File name of the image file.
[out]	pHIMGFILE	Handle of the image file.
[in]	mode	Opening mode. See IMGF_READ and IMGF_RDWR.
[in]	filetype	Type of the created file. This parameter has meaning only when the opening mode is IMGF_RDWR. In this case, it means not the compression mode but the pure file type, for example, it determines that the file type is TIFF, but does not differentiate between FF_TIFG4 and FF_TIFLZW. The precise file format, including compression method, will be determined at saving time (e.g. kRecSaveImg, etc.)

Return values:

RECERR

Note:

Not all the image formats are supported on all platforms. For details see the description of IMF_FORMAT.

The specification of this function in C# is:

 RECERR kRecOpenImgFile(string pFilename, out IntPtr pHIMGFILE, FILEOPENMODE mode, IMF_FORMAT filetype);

RECERR RECAPIKRN kRecPackImgFile	(	int	sid,
		LPCTSTR	pFileName
	)

Packing a TIFF file.

The kRecPackImgFile function packs the selected multi-page TIFF image file. It removes any previously deleted or replaced pages from the TIFF file.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pFileName	Name of the TIFF image file to be packed.

Return values:

RECERR

Note:

The integrating application can delete, replace or update pages in a multi-page TIFF image file using the kRecDeleteImgFilePage, kRecReplaceImgFilePage and kRecUpdateImgFilePage functions, respectively. These functions work on an opened image file (HIMGFILE, kRecOpenImgFile), but packing MUST NOT be used on opened files. (For closing a file use kRecCloseImgFile.) The reason for using packing is that the packed image file is usually smaller and often provides better performance.

Calling this function may take several seconds for image files containing a lot of pages.

The kRecDeleteImgFilePage deletes the page logically also from a one-page TIFF file. In this last case, most image viewers cannot open the resulting file. But the CSDK functions can handle such a file, so it can be opened, closed and packed, its page count can be queried, pages can be inserted into it. If kRecPackImgFile gets such a file it removes the page physically and the resulting pageless file can be handled in the same way.

This function belongs to the Multi-page TIFF File Handling Function Group. To use these functions, the pages in the multi-page TIFF file must be stored in One-strip format and the StripBytesCount TIFF tag must exist in the page header. Note that TIFF image files created by OmniPage CSDK fulfils this requirement.

The specification of this function in C# is:

 RECERR kRecPackImgFile(int sid, string pFileName);

RECERR RECAPIKRN kRecReplaceImgFilePage	(	int	sid,
		HIMGFILE	hIFileDst,
		int	ndstPage,
		HIMGFILE	hIFileSrc,
		int	nsrcPage
	)

Replacing a page in a TIFF file.

The kRecReplaceImgFilePage function replaces a page in a destination multi-page TIFF image file by another page stored in a source TIFF image file.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hIFileDst	Handle of the destination image file to be changed.
[in]	ndstPage	Page number of the page in the destination image file to be deleted and replaced. To replace the first page, the value zero (0) should be specified.
[in]	hIFileSrc	Handle of the source image file.
[in]	nsrcPage	Page number of the page in the source image file to be copied from. For a single-page source image file a value of zero (0) should be specified.

Return values:

RECERR

Note:

In order to save time, this operation is performed without decompressing the page. The compression method of the source page is not changed.

This function belongs to the Multi-page TIFF File Handling Function Group. To use these functions, the pages in the multi-page TIFF file must be stored in One-strip format and the StripBytesCount TIFF tag must exist in the page header. TIFF image files created by OmniPage CSDK fulfil this requirement.

Deleted or replaced pages can be physically removed from the image file by kRecPackImgFile.

The specification of this function in C# is:

 RECERR kRecReplaceImgFilePage(int sid, IntPtr hIFileDst, int dstPage, IntPtr hIFileSrc, int nsrcPage);

RECERR RECAPIKRN kRecSaveImg	(	int	sid,
		HIMGFILE	hIFile,
		IMF_FORMAT	Imgfileformat,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		INTBOOL	bAppend
	)

Saving a page.

The kRecSaveImg function stores the Engine's page to disk into an image file. The kRecSaveImg function activates the PID_IMGSAVE process.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hIFile	Handle of the image file opened for writing by kRecOpenImgFile.
[in]	Imgfileformat	Image file format of the output file.
[in]	hPage	Handle of the page containing the image to be saved.
[in]	iiImg	Index of the image to be saved.
[in]	bAppend	Flag for image append mode. Its TRUE value indicates that the image will be appended to the image file specified by `hIFile`, if it exists. Appending is successful only if the image file format supports multi-page image files.

Return values:

RECERR

Note:

Not all the image formats are supported on all platforms. For details see the description of IMF_FORMAT.

If the given image file does not exist, it will be automatically created.

When the append flag is TRUE and the type of the given file format does not match the type of the existing multi-page image file, the function returns with an error. (I.e. it does not give an error when it appends e.g. an FF_TIFLZW to an FF_TIFG4.) To learn whether the Imgfileformat supports multi-page images kRecIsMultipageImgFileFormat can be called.

Not all of the image file types support all the possible BitsPerPixel (bit depth) values. The kRecMatchImgFileFormat function can be used to check whether the image can be saved in the specified format.

When a 8-bit palette color image is saved into JPEG format, it is converted to 24-bit color.

If hPage contains DataStream this function may save the page without recompression. See the details in the section about DataStream.

The specification of this function in C# is:

 RECERR kRecSaveImg(int sid, IntPtr hIFile, IMF_FORMAT Imgfileformat, IntPtr hPage, IMAGEINDEX iiImg, bool bAppend);

RECERR RECAPIKRN kRecSaveImgArea	(	int	sid,
		HIMGFILE	hIFile,
		IMF_FORMAT	format,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		LPCRECT	pRect,
		INTBOOL	append
	)

Saving an area of a page.

The kRecSaveImgArea function saves a rectangular area of the specified image of a page to an image file opened by kRecOpenImgFile. This function is derived from the kRecSaveImg function. The kRecSaveImgArea function activates the PID_IMGSAVE process.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hIFile	Handle of the image file opened for writing.
[in]	format	Image file format for the output file.
[in]	hPage	Handle of the page containing the image whose area will be saved.
[in]	iiImg	Index of the image whose area will be saved.
[in]	pRect	Pointer to the requested area of the image to be saved. If this parameter contains a NULL value, then the entire image will be saved.
[in]	append	Flag for image append mode. Its TRUE value indicates that the current image will be appended to the given image file, if it exists. Appending is successful only if the specified image file format supports multi-page image files.

Return values:

RECERR

Note:

Not all the image formats are supported on all platforms. For details see the description of IMF_FORMAT.

If the given image file does not exist, it will be automatically created.

When the append flag is TRUE and the type of the given file format does not match the type of the existing multi-page image file, the function returns with an error. (I.e. it does not give an error when it appends e.g. an FF_TIFLZW to an FF_TIFG4.) To learn whether the format supports multi-page images kRecIsMultipageImgFileFormat can be called.

Not all of the image file types support all the possible BitsPerPixel values. The kRecMatchImgFileFormat function can be used to check whether the image can be saved in the specified format.

When a 8-bit palette color image is saved into JPEG format, it is converted to 24-bit color.

If hPage contains DataStream this function may save the page without recompression. See the details in the section about DataStream.

The specification of this function in C# is:

    RECERR kRecSaveImgArea(int sid, IntPtr hIFile, IMF_FORMAT Imgfileformat, IntPtr hPage, IMAGEINDEX img, RECT pRect, bool bAppend);
    // or
    RECERR kRecSaveImgArea(int sid, IntPtr hIFile, IMF_FORMAT Imgfileformat, IntPtr hPage, IMAGEINDEX img, bool bAppend);   // pRect is NULL in C/C++

.

RECERR RECAPIKRN kRecSaveImgAreaF	(	int	sid,
		LPCTSTR	pFilename,
		IMF_FORMAT	format,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		LPCRECT	pRect,
		INTBOOL	append
	)

Saving an area of a page directly into a file.

The kRecSaveImgAreaF function saves a rectangular area of the specified image of a page to an image file directly. This function is a derivative of the kRecSaveImgF function. The kRecSaveImgAreaF function activates the PID_IMGSAVE process.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pFilename	Name of the image file to be saved.
[in]	format	Image file format for the output file.
[in]	hPage	Handle of the page containing the image whose area will be saved.
[in]	iiImg	Index of the image whose area will be saved.
[in]	pRect	Pointer to the requested area of the image to be saved. If this parameter contains a NULL value, then the entire image will be saved.
[in]	append	Flag for image append mode. Its TRUE value indicates that the current image will be appended to the given image file, if it exists. Appending is successful only if the specified image file format supports multi-page image files.

Return values:

RECERR

Note:

Not all the image formats are supported on all platforms. For details see the description of IMF_FORMAT.

If the given image file does not exist, it will be automatically created.

When the append flag is TRUE and the type of the given file format does not match the type of the existing multi-page image file, the function will return with an error. (I.e. it does not give an error when it appends e.g. an FF_TIFLZW to an FF_TIFG4.) To learn whether the format supports multi-page images kRecIsMultipageImgFileFormat can be called.

Not all of the image file types support all the possible BitsPerPixel values. The kRecMatchImgFileFormat function can be used to check whether the image can be saved in the specified format.

When a 8-bit palette color image is saved into JPEG format, it is converted to 24-bit color.

If hPage contains DataStream this function may save the page without recompression. See the details in the section about DataStream.

The specification of this function in C# is:

    RECERR kRecSaveImgAreaF(int sid, string pFilename, IMF_FORMAT Imgfileformat, IntPtr hPage, IMAGEINDEX img, RECT pRect, bool bAppend);
    // or
    RECERR kRecSaveImgAreaF(int sid, string pFilename, IMF_FORMAT Imgfileformat, IntPtr hPage, IMAGEINDEX img, bool bAppend);   // pRect is NULL in C/C++

.

RECERR RECAPIKRN kRecSaveImgF	(	int	sid,
		LPCTSTR	pFilename,
		IMF_FORMAT	Imgfileformat,
		HPAGE	hPage,
		IMAGEINDEX	img,
		INTBOOL	bAppend
	)

Saving a page directly into a file.

The kRecSaveImgF function stores the Engine's page to disk into an image file directly. The kRecSaveImgF function activates the PID_IMGSAVE process.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pFilename	Name of the image file to be saved.
[in]	Imgfileformat	Image file format of the output file.
[in]	hPage	Handle of the page containing the image to be saved.
[in]	img	Index of the image to be saved.
[in]	bAppend	Flag for image append mode. Its TRUE value indicates that the image will be appended to the image file specified by `pFilename`, if it exists. Appending is successful only if the image file format supports multi-page image files.

Return values:

RECERR

Note:

Not all the image formats are supported on all platforms. For details see the description of IMF_FORMAT.

If the given image file does not exist, it will be automatically created.

When the append flag is TRUE and the type of the given file format does not match the type of the existing multi-page image file, the function returns with an error. (I.e. it does not give an error when it appends e.g. an FF_TIFLZW to an FF_TIFG4.) To learn whether the Imgfileformat supports multi-page images kRecIsMultipageImgFileFormat can be called.

Not all of the image file types support all the possible BitsPerPixel (bit depth) values. The kRecMatchImgFileFormat function can be used to check whether the image can be saved in the specified format.

When a 8-bit palette color image is saved into JPEG format, it is converted to 24-bit color.

If hPage contains DataStream this function may save the page without recompression. See the details in the section about DataStream.

The specification of this function in C# is:

 RECERR kRecSaveImgF(int sid, string pFilename, IMF_FORMAT Imgfileformat, IntPtr hPage, IMAGEINDEX img, bool bAppend);

RECERR RECAPIKRN kRecSaveImgForce	(	int	sid,
		HIMGFILE	hIFile,
		IMF_FORMAT	Imgfileformat,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		INTBOOL	bAppend
	)

Saving a page with forcing the format.

The kRecSaveImgForce function stores the Engine's page to disk into an image file. When the selected image cannot be saved into the specified format the image is converted to one that can receive it. The kRecSaveImgForce function activates the PID_IMGSAVE process.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hIFile	Handle of the image file opened for writing by kRecOpenImgFile.
[in]	Imgfileformat	Image file format of the output file.
[in]	hPage	Handle of the page containing the image to be saved.
[in]	iiImg	Index of the image to be saved.
[in]	bAppend	Flag for image append mode. Its TRUE value indicates that the image will be appended to the image file specified by `hIFile`, if it exists. Appending is successful only if the image file format supports multi-page image files.

Return values:

RECERR

Note:

Not all the image formats are supported on all platforms. For details see the description of IMF_FORMAT.

If the given image file does not exist, it will be automatically created.

When the append flag is TRUE and the type of the given file format does not match the type of the existing multi-page image file, the function returns with an error. (I.e. it does not give an error when it appends e.g. an FF_TIFLZW to an FF_TIFG4.) To learn whether the Imgfileformat supports multi-page images kRecIsMultipageImgFileFormat can be called.

The kRecMatchImgFileFormat function can be used to check whether the image can be saved in the specified format.

If hPage contains DataStream this function may save the page without recompression. See the details in the section about DataStream.

The specification of this function in C# is:

 RECERR kRecSaveImgForce(int sid, IntPtr hIFile, IMF_FORMAT Imgfileformat, IntPtr hPage, IMAGEINDEX iiImg, bool bAppend);

RECERR RECAPIKRN kRecSaveImgForceF	(	int	sid,
		LPCTSTR	pFilename,
		IMF_FORMAT	Imgfileformat,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		INTBOOL	bAppend
	)

Saving a page directly into a file with forcing of the format.

The kRecSaveImgForceF function stores the Engine's page to disk into an image file. When the selected image cannot be saved into the specified format the image is converted to another similar one that can receive it. The kRecSaveImgForceF function activates the PID_IMGSAVE process.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pFilename	Name of the image file to be saved.
[in]	Imgfileformat	Image file format of the output file.
[in]	hPage	Handle of the page containing the image to be saved.
[in]	iiImg	Index of the image to be saved.
[in]	bAppend	Flag for image append mode. Its TRUE value indicates that the image will be appended to the image file specified by `pFilename`, if it exists. Appending is successful only if the image file format supports multi-page image files.

Return values:

RECERR

Note:

Not all the image formats are supported on all platforms. For details see the description of IMF_FORMAT.

If the given image file does not exist it, will be automatically created.

When the append flag is TRUE and the type of the given file format does not match the type of the existing multi-page image file, the function returns with an error. (I.e. it does not give an error when it appends e.g. an FF_TIFLZW to an FF_TIFG4.) To learn whether the Imgfileformat supports multi-page images kRecIsMultipageImgFileFormat can be called.

The kRecMatchImgFileFormat function can be used to check whether the image can be saved in the specified format.

If hPage contains DataStream this function may save the page without recompression. See the details in the section about DataStream.

The specification of this function in C# is:

 RECERR kRecSaveImgForceF(int sid, string pFilename, IMF_FORMAT Imgfileformat, IntPtr hPage, IMAGEINDEX img, bool bAppend);

RECERR RECAPIKRN kRecSetCompressionLevel	(	int	sid,
		int	CompressionLevel
	)

Setting the compression level.

This function specifies the compression level used when an image is saved to specific formats.

Parameters:

[in]	sid	Settings Collection ID.
[in]	CompressionLevel	The compression level to be set. This may be a value between 1 and 5, or 0. 0 means custom level, otherwise higher value means weaker compression. The default level is 3.

Return values:

RECERR

Note:

This function changes the value of the setting Kernel.Imf.CompressionLevel.

This setting is used when the image is saved to FF_JPG, FF_JPG2K, FF_PDF, FF_PDF_MRC file formats, or DTXT_IOTPDF, DTXT_IOTPDF_MRC direct text formats.

See details about usage of compression level and trade-off.

The specification of this function in C# is:

 RECERR kRecSetCompressionLevel(int sid, int CompressionLevel);

RECERR RECAPIKRN kRecSetCompressionTradeoff	(	int	sid,
		COMPRESSION_TRADEOFF	CompressionTradeoff
	)

Setting the compression trade-off.

This function specifies the compression trade-off used when an image is saved to specific formats.

Parameters:

[in]	sid	Settings Collection ID.
[in]	CompressionTradeoff	The compression tradeoff to be set. This may be COMPRESSION_FAST and COMPRESSION_ADVANCED (default).

Return values:

RECERR

Note:

This function changes the value of the setting Kernel.Imf.CompressionTradeoff.

This setting is used when the image is saved to FF_PDF, FF_PDF_MRC, or DTXT_IOTPDF, DTXT_IOTPDF_MRC formats with non-0 compression level.

See details about usage of compression level and trade-off.

The specification of this function in C# is:

 RECERR kRecSetCompressionTradeoff(int sid, COMPRESSION_TRADEOFF CompressionTradeoff);

RECERR RECAPIKRN kRecSetImfLoadFlags	(	int	sid,
		DWORD	fFlag
	)

Setting IMF PDF load flags.

The kRecSetImfLoadFlags function set an IMF Load Flags combination

Parameters:

[in]	sid	Settings Collection ID.
[in]	fFlag	The IMF PDF Load Flag combination. See the possible bits.

Return values:

RECERR

Note:

To process the PDF just as an image (without any PDF info) set it to IMF_PDF_AS_IMAGE | IMF_PDF_NO_TAGS. Please note that recognition accuracy is usually worse if the bit IMF_PDF_AS_IMAGE is switched on!

This function changes the setting Kernel.Imf.PDF.LoadFlags. This setting can be retrieved by kRecGetImfLoadFlags.

The specification of this function in C# is:

 RECERR kRecSetImfLoadFlags(int sid, uint fFlag);

RECERR RECAPIKRN kRecSetJPGQuality	(	int	sid,
		int	nQuality
	)

Setting JPEG quality.

This function changes the JPEG quality setting used when saving images into JPEG or JPEG2000 files.

Parameters:

[in]	sid	Settings Collection ID.
[in]	nQuality	JPEG quality to be set. This may be a value between 1 and 100, or -1 (default, see notes).

Return values:

RECERR

Note:

This function sets the value of the setting Kernel.Imf.JPG.Quality. This setting can be retrieved by kRecGetJPGQuality.

The quality differs from compression rate. The real compression rate cannot be calculated from the quality value, it depends on the content of the image as well.

Higher value means higher quality and weaker compression.

This setting is used when the image is saved to FF_JPG or FF_JPG2K formats and custom compression level is set (i.e. Kernel.Imf.CompressionLevel is 0, see: kRecSetCompressionLevel). When the compression level is not 0, this setting is disregarded, and the following predefined JPEG quality values are used:

FF_JPG:
- level 5 - 90
- level 4 - 82
- level 3 - 75
- level 2 - 62
- level 1 - 50
FF_JPG2K:
- level 5 - 75
- level 4 - 62
- level 3 - 50
- level 2 - 30
- level 1 - 10

The best quality can be achieved by setting Kernel.Imf.CompressionLevel = 0 and Kernel.Imf.JPG.Quality = 100. In this case FF_JPG2K applies lossless compression, FF_JPG has some negligible loss.

FF_JPG_MIN, FF_JPG_GOOD, FF_JPG_SUPERB, FF_JPG2K_MIN, FF_JPG2K_GOOD, FF_JPG2K_SUPERB can be used but they are deprecated. Use FF_JPG or FF_JPG2K instead.

If this setting is not default, the Image File Handling Module uses that value for FF_JPG_MIN, FF_JPG_GOOD, FF_JPG_SUPERB, FF_JPG2K_MIN, FF_JPG2K_GOOD, FF_JPG2K_SUPERB image formats (i.e. there is no difference between SUPERB, LOSSLESS, GOOD and MIN).

FF_JPG_SUPERB and FF_JPG2K_SUPERB has some negligible loss.

If this setting has its default value (-1), the different JPEG and JPEG2000 image formats represent the following qualities:

The specification of this function in C# is:

 RECERR kRecSetJPGQuality(int sid, int nQuality);

RECERR RECAPIKRN kRecSetMRCCompressionSettingsFromLevel	(	int	sid,
		int	CompressionLevel,
		COMPRESSION_TRADEOFF	CompressionTradeOff
	)

Modifying the MRC settings according to the given compression level and tradeoff.

This function can be used to set customized PDF MRC parameters. See notes below for the list of the modified settings.

Parameters:

[in]	sid	Settings Collection ID.
[in]	CompressionLevel	The compression level between 1 and 5.
[in]	CompressionTradeOff	The compression trade-off.

Return values:

RECERR

Note:

This function can be used for FF_PDF_MRC and DTXT_IOTPDF_MRC output. Compression level and compression trade-off together determine the value of the settings below. This function is useful when the User wants to change some of them and to use the predefined values for the remaining ones. For example, the following code uses level 3, in which the value of the setting Kernel.Imf.PDF.MRC.BGLayer.JPGQuality is 55 by default. However the code wants to use 30:

    rc = kRecSetCompressionLevel(sid, 0);       // using the customized values
    rc = kRecSetMRCCompressionSettingsFromLevel(sid, 3, COMPRESSION_ADVANCED);
    HSETTING hset;
    kRecSettingGetHandle(NULL, "Kernel.Imf.PDF.MRC.BGLayer.JPGQuality", &hset, NULL);
    kRecSettingSetInt(0, hset, 30);
    rc = kRecSaveImgF(sid, pFilename, FF_PDF_MRC, hPage, II_CURRENT, bAppend);

The following settings are changed by this function (see detailed descriptions):

Kernel.IMF.PDF.ColorFormat
Kernel.IMF.PDF.BWFormat
Kernel.IMF.PDF.MRC.EnableMultipleFG
Kernel.IMF.PDF.MRC.BGLayer.JPGQuality
Kernel.IMF.PDF.MRC.BGLayer.SubSampleRate
Kernel.IMF.PDF.MRC.BGLayer.Method
Kernel.IMF.PDF.MRC.BGLayer.ConsolidationStrength
Kernel.IMF.PDF.MRC.BGLayer.Smoothing
Kernel.IMF.PDF.MRC.BGLayer.DilatationSteps
Kernel.IMF.PDF.MRC.FGLayer.JPGQuality
Kernel.IMF.PDF.MRC.FGLayer.SubSampleRate
Kernel.IMF.PDF.MRC.FGLayer.Method
Kernel.IMF.PDF.MRC.SelLayer.SubSampleRate
Kernel.IMF.PDF.MRC.Selector.Method

The other MRC settings are independent of compression level and trade-off. They are not modified by this function.

The specification of this function in C# is:

 RECERR kRecSetMRCCompressionSettingsFromLevel(int sid, int CompressionLevel, COMPRESSION_TRADEOFF CompressionTradeOff);

RECERR RECAPIKRN kRecSetPdfPassword	(	HIMGFILE	hIFile,
		LPCTSTR	pwd
	)

Setting PDF password.

This function sets the password for a PDF file opened by kRecOpenImgFile. To learn whether a password is required for processing the PDF kRecGetPDFEncLevel can be called. kRecSetPdfPasswordA supposes the password to be in the current system code page. Thus we suggest to use kRecSetPdfPasswordW.

Parameters:

[in]	hIFile	Handle of the image file.
[in]	pwd	Password.

Return values:

RECERR

Note:

The specification of this function in C# is:

 RECERR kRecSetPdfPassword(IntPtr hIFile, string pwd);

RECERR RECAPIKRN kRecSetPdfTagInfo	(	int	sid,
		INTBOOL	bUseTagInfo
	)

Setting use of PDF tag information.

This function sets whether the Engine uses the tag information of the PDF file or not.

Parameters:

[in]	sid	Settings Collection ID.
[in]	bUseTagInfo	Use of tag information. If it is TRUE the tag information is used.

Return values:

RECERR

Note:

The tag information affects the page layout decomposition and thus the recognition result. It can give a special structure to the page, which may not be seen during decomposition, thus improving the result. Unfortunately, there can be absolutely wrong tag information in a PDF file even if it displays properly in the viewer. In this case, the recognition result may have worse quality using tag information and may be better without this.

The specification of this function in C# is:

 RECERR kRecSetPdfTagInfo(int sid, bool bUseTagInfo);

RECERR RECAPIKRN kRecUpdateImgFilePage	(	int	sid,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		HIMGFILE	hIFile,
		int	nPage,
		IMF_FORMAT	format
	)

Replacing a page in a TIFF file.

The kRecUpdateImgFilePage function replaces a page in a multi-page TIFF image file with a different image taken from the image management module.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page containing the image to be inserted.
[in]	iiImg	Index of the image to be inserted.
[in]	hIFile	Handle of the multi-page TIFF image file.
[in]	nPage	Page number of the page in the image file to be deleted and replaced. To replace the first page in the image file, the value zero (0) should be specified.
[in]	format	Image file format (compression) to be applied during the page replacement. Of course, only TIFF formats can be selected.

Return values:

RECERR

Note:

This function belongs to the Multi-page TIFF File Handling Function Group. To use these functions, the pages in the multi-page TIFF file must be stored in One-strip format and the StripBytesCount TIFF tag must exist in the page header. TIFF image files created by OmniPage CSDK fulfil this requirement.

Deleted or replaced pages can be physically removed from the image file calling kRecPackImgFile.

The specification of this function in C# is:

 RECERR kRecUpdateImgFilePage(int sid, IntPtr hPage, IMAGEINDEX iiImg, IntPtr hIFile, int nPage, IMF_FORMAT format);

Typedefs

Enumerations

Functions

Image file opening modes

IMF PDF Load Flags defines for loading PDF file

Pagenumber defines for loading a page

Detailed Description

Extended image size

Using images without decompression

Newer image formats

Customization of JPGQuality

Customization of quality for PDF formats

Orientation of page at saving a PDF

Enumeration Type Documentation

Function Documentation