Image handling tools. More...

Classes
struct	IMG_INFO
	Structure of an image containing basic physical information. More...
struct	COMPRESSED_IMG_INFO
	Basic physical information of a compressed image buffer. More...
struct	CUT_INFO
	Structure for book images. More...
struct	PREPROC_INFO
	Information about preprocessing. More...
struct	RLINE
	Structure of a line. More...
Defines
#define	PHOLE_DETECT 1
	Detect punch holes. It is combinable with PHOLE_REMOVE.
#define	PHOLE_REMOVE 2
	Remove punch holes. It is combinable with PHOLE_DETECT.
#define	CROP_CLEARMARGIN 1
#define	CONVIMG_PALETTE 1
	Create palette image.
#define	CONVIMG_ERRDIFF 2
	Use error diffusion to simulate shades.
Typedefs
typedef IMG_INFO *	LPIMG_INFO
	Pointer to a structure IMG_INFO.
typedef const IMG_INFO *	LPCIMG_INFO
	Const pointer to a structure IMG_INFO.
typedef COMPRESSED_IMG_INFO *	LPCOMPRESSED_IMG_INFO
	Pointer to a structure COMPRESSED_IMG_INFO.
typedef const COMPRESSED_IMG_INFO *	LPCCOMPRESSED_IMG_INFO
	Const pointer to a structure COMPRESSED_IMG_INFO.
typedef struct RECPAGESTRUCT *	HPAGE
	Handle of a page in memory.
typedef IMG_CONVERSION *	LPIMG_CONVERSION
	Pointer to an enum type IMG_CONVERSION.
typedef DWORD	REC_COLOR
	Color type.
Enumerations
enum	IMG_COMPRESSION { COMPRESS_TIFHU = 0, COMPRESS_TIFG31, COMPRESS_TIFG32, COMPRESS_TIFG4, COMPRESS_JPEG, COMPRESS_JPG2K, COMPRESS_SIZE }
	Image compression types. More...
enum	JPG_RESOLUTION { JPG_RES_USEDEFAULTDPI = 0, JPG_RES_USEEXIF }
	Image resolution for JPEG files. More...
enum	JPG_ORIENTATION { JPG_ORIENTATION_IGNOREEXIF = 0, JPG_ORIENTATION_USEEXIF }
	Image orientation for JPEG files. More...
enum	IMG_CONVERSION { CNV_AUTO = 0, CNV_SET, CNV_NO, CNV_GLOBAL, CNV_GRAY }
	Image conversion types. More...
enum	IMG_ROTATE { ROT_AUTO = 0, ROT_NO, ROT_RIGHT, ROT_DOWN, ROT_LEFT, ROT_FLIPPED = ROT_NO + 0x80, ROT_RIGHT_FLIPPED, ROT_DOWN_FLIPPED, ROT_LEFT_FLIPPED }
	Available image transformations (rotation and/or mirroring). More...
enum	IMG_LINEORDER { TOP_DOWN = 0, BOTTOM_UP }
	Image line order. More...
enum	IMG_PADDING { PAD_BYTEBOUNDARY = 1, PAD_WORDBOUNDARY = 2, PAD_DWORDBOUNDARY = 4 }
	Image padding. More...
enum	IMG_RGBORDER { COLOR_RGB = 0, COLOR_BGR, COLOR_BGRA, COLOR_ARGB }
	Image color order. More...
enum	IMG_RESENH { RE_NO, RE_YES, RE_LEGACY, RE_STANDARD, RE_AUTO }
	Image resolution enhancement. More...
enum	IMG_INVERT { INV_NO = 0, INV_YES, INV_AUTO }
	Image inversion mode. More...
enum	IMG_DESKEW { DSK_2D = 0, DSK_AUTO = DSK_2D, DSK_NO, DSK_SET, DSK_3D, DSK_AUTO3D }
	Image deskewing mode. More...
enum	IMG_STRETCHMODE { STRETCH_DELETE = 0, STRETCH_OR, STRETCH_AND, STRETCH_AVG }
	Image stretching mode. More...
enum	IMAGEINDEX { II_UNDEFINED = -1, II_BGLAYER, II_ORIGINAL, II_CURRENT, II_BW, II_OCR, II_THUMBNAIL, II_OUTPUT, II_SIZE }
	Index of each image type in HPAGE. More...
enum	PREPROC_INFO_FLAGS { PREPROC_INFO_FAXCORRECTION = 1, PREPROC_INFO_INVERSION = 2, PREPROC_INFO_3DDESKEW = 4, PREPROC_INFO_STRAIGHTENED = 8, PREPROC_INFO_HALFTONE = 16 }
	Flags for the structure PREPROC_INFO. More...
enum	PROCESSING_MODE { PROCESSING_NORMAL = 0, PROCESSING_BOOK = 1 }
	Switching between processing modes. More...
enum	FILLAREA_FLAGS { FILL_INSIDE = 0, FILL_OUTSIDE = 1, FILL_FLEXIBLEBPS = 2 }
	Determining the area to be filled by kRecFillImgArea. More...
enum	DESPECKLE_METHOD { DESPECKLE_AUTO = 0, DESPECKLE_NORMAL, DESPECKLE_INVERSE, DESPECKLE_HALFTONE, DESPECKLE_MEDIAN , DESPECKLE_PEPPER = 8, DESPECKLE_SALT = 16, DESPECKLE_PEPPERANDSALT = (DESPECKLE_PEPPER \| DESPECKLE_SALT) }
	Despeckle method used by kRecForceDespeckleImg. More...
enum	ERO_DIL_TYPE { ERO_DIL_3 = 0, ERO_DIL_4, ERO_DIL_8 }
	Type of neighborhood used by kRecImgErosion and kRecImgDilatation. More...
enum	IMG_FLAGS { IMG_FLAGS_CAMERAIMAGE = 0, IMG_FLAGS_NORESOLUTION }
	Image flags. More...
enum	RETAINCOLOR { RETAINCOLOR_NO, RETAINCOLOR_YES, RETAINCOLOR_INVERTED }
	Retain color. More...
Functions
RECERR RECAPIKRN	kRecSetImgDownsample (int sid, INTBOOL downsample)
	Changing the view downsample setting.
RECERR RECAPIKRN	kRecGetImgDownsample (int sid, INTBOOL *pdownsample)
	Getting the value of view downsample setting.
RECERR RECAPIKRN	kRecSetPreserveOriginalImg (int sid, INTBOOL preserve)
	Changing the keep original image setting.
RECERR RECAPIKRN	kRecGetPreserveOriginalImg (int sid, INTBOOL *pPreserve)
	Getting the value of the keep original image setting.
RECERR RECAPIKRN	kRecSetFaxCorrection (int sid, INTBOOL corr)
	Changing the fax correction setting.
RECERR RECAPIKRN	kRecGetFaxCorrection (int sid, INTBOOL *pCorr)
	Getting the value of fax correction setting.
RECERR RECAPIKRN	kRecSetThumbnailImgInfo (int sid, const IMG_INFO *pThumbnail, REC_COLOR color)
	Changing the thumbnail image info settings.
RECERR RECAPIKRN	kRecGetThumbnailImgInfo (int sid, IMG_INFO pThumbnail, REC_COLOR pColor)
	Getting the value of thumbnail image info settings.
RECERR RECAPIKRN	kRecSetImgBinarizationMode (int sid, IMG_CONVERSION BWConversion)
	Setting secondary image conversion mode.
RECERR RECAPIKRN	kRecGetImgBinarizationMode (int sid, LPIMG_CONVERSION pBWConversion)
	Getting secondary image conversion mode.
RECERR RECAPIKRN	kRecSetImgBrightness (int sid, int Brightness)
	Setting brightness.
RECERR RECAPIKRN	kRecGetImgBrightness (int sid, int *lpBrightness)
	Getting brightness.
RECERR RECAPIKRN	kRecSetImgThreshold (int sid, int Threshold)
	Setting the binarization threshold.
RECERR RECAPIKRN	kRecGetImgThreshold (int sid, int *pThreshold)
	Getting binarization threshold.
RECERR RECAPIKRN	kRecSetImgInvert (int sid, IMG_INVERT ImgInvert)
	Setting inversion mode.
RECERR RECAPIKRN	kRecGetImgInvert (int sid, IMG_INVERT *lpImgInvert)
	Getting inversion mode.
RECERR RECAPIKRN	kRecSetImgDeskew (int sid, IMG_DESKEW _ImgDeskew)
	Setting deskew mode.
RECERR RECAPIKRN	kRecGetImgDeskew (int sid, IMG_DESKEW *pImgDeskew)
	Getting deskew mode.
RECERR RECAPIKRN	kRecSetImgSlope (int sid, int Slope)
	Setting the slope.
RECERR RECAPIKRN	kRecGetImgSlope (int sid, int *lpSlope)
	Getting the slope.
RECERR RECAPIKRN	kRecSetImgRotation (int sid, IMG_ROTATE imgRotate)
	Setting rotation mode.
RECERR RECAPIKRN	kRecGetImgRotation (int sid, IMG_ROTATE *lpImgRotate)
	Getting rotation mode.
RECERR RECAPIKRN	kRecSetImgFormat (int sid, IMG_LINEORDER lineord, IMG_PADDING padding, IMG_RGBORDER ord)
	Setting image format.
RECERR RECAPIKRN	kRecGetImgFormat (int sid, IMG_LINEORDER plineord, IMG_PADDING ppadding, IMG_RGBORDER *pord)
	Getting image format.
RECERR RECAPIKRN	kRecSetImgStretchMode (int sid, IMG_STRETCHMODE ImgStretchMode)
	Setting stretching mode.
RECERR RECAPIKRN	kRecGetImgStretchMode (int sid, IMG_STRETCHMODE *pImgStretchMode)
	Getting stretching mode.
RECERR RECAPIKRN	kRecSetImgResolEnhancement (int sid, IMG_RESENH res)
	Setting resolution enhancement mode.
RECERR RECAPIKRN	kRecGetImgResolEnhancement (int sid, IMG_RESENH *res)
	Getting resolution enhancement mode.
RECERR RECAPIKRN	kRecSetImgDespeckleMode (int sid, INTBOOL bMode)
	Setting despeckle mode.
RECERR RECAPIKRN	kRecGetImgDespeckleMode (int sid, LPINTBOOL lpbMode)
	Getting despeckle mode.
RECERR RECAPIKRN	kRecSetImgConvMode (int sid, IMG_CONVERSION Conversion)
	Setting the primary image conversion mode.
RECERR RECAPIKRN	kRecGetImgConvMode (int sid, IMG_CONVERSION *pConversion)
	Getting primary image conversion mode.
RECERR RECAPIKRN	kRecPreprocessImg (int sid, HPAGE hPage)
	Image preprocessing.
RECERR RECAPIKRN	kRecGetPreprocessInfo (HPAGE hPage, PREPROC_INFO *pPreprocInfo)
	Returning information about the preprocessing.
RECERR RECAPIKRN	kRecRemovePunchHoles (int sid, HPAGE hPage, LPCRECT ROIs, int nROIs, LPRECT Holes, int nHoles, UINT flags, UINT minDiameter, UINT maxDiameter)
	Removing punch holes.
RECERR RECAPIKRN	kRecRemoveBorders (int sid, HPAGE hPage, UINT maxWidth)
	Removing marginal shadows.
RECERR RECAPIKRN	kRecDetectBook (int sid, HPAGE hPage, CUT_INFO *pInfo)
	Detecting facing book pages.
RECERR RECAPIKRN	kRecCreateBookPages (int sid, HPAGE hPage, HPAGE phPage1, HPAGE phPage2, const CUT_INFO *pInfo)
	Cutting each opened book image into two pages.
RECERR RECAPIKRN	kRecResetBookSize (int sid)
	Resetting the stored book page size.
RECERR RECAPIKRN	kRecDetectBlankPage (int sid, HPAGE hPage, INTBOOL *pIsBlank)
	Detecting blank pages.
RECERR RECAPIKRN	kRecAutoCropImg (int sid, HPAGE hPage, int lrMargin, int tbMargin, UINT flags)
	Cropping white border.
RECERR RECAPIKRN	kRecDetectFillingMethod (int sid, HPAGE hPage, FILLINGMETHOD *pocrType)
	Detection of filling method.
RECERR RECAPIKRN	kRecDetectImgSkew (int sid, HPAGE hPage, int pSlope, IMG_ROTATE pImgRotate)
	Detecting orientation and skew.
RECERR RECAPIKRN	kRecPutImgArea (int sid, LPCIMG_INFO lpImg, const BYTE *lpBitmap, HPAGE hPage, int xDst, int yDst, LPCSIZE pDstSize)
	Updating image area.
RECERR RECAPIKRN	kRecGetImgArea (int sid, HPAGE hPageIn, IMAGEINDEX iiImg, LPCRECT pSrcRect, LPCSIZE pDstSize, LPIMG_INFO pImg, BYTE **ppBitmap)
	Getting image area.
RECERR RECAPIKRN	kRecGetImgAreaEx (int sid, HPAGE hPageIn, IMAGEINDEX iiImg, LPCRECT pSrcRect, LPCSIZE pDstSize, IMG_STRETCHMODE StretchMode, IMG_LINEORDER LineOrder, IMG_RGBORDER RGBOrder, INTBOOL strict, IMG_PADDING Padding, LPIMG_INFO pImg, BYTE **ppBitmap)
	Getting image area.
RECERR RECAPIKRN	kRecStartReadImg (int sid, HPAGE hPage, IMAGEINDEX iiImg, LPCRECT pRect, IMG_ROTATE ImgRotation, LPWORD pBytes)
	Starting to read an image line-by-line.
RECERR RECAPIKRN	kRecReadImg (int sid, LPBYTE pBuff)
	Reading an image line-by-line.
RECERR RECAPIKRN	kRecStopReadImg (int sid)
	Stopping to read an image line-by-line.
RECERR RECAPIKRN	kRecStartWriteImg (int sid, LPCIMG_INFO pImg)
	Starting to write an image line-by-line.
RECERR RECAPIKRN	kRecWriteImg (int sid, const LPBYTE pBuff)
	Writing an image line-by-line.
RECERR RECAPIKRN	kRecStopWriteImg (int sid, HPAGE *phPage)
	Stopping the writing of an image line-by-line.
RECERR RECAPIKRN	kRecRotateImgArea (int sid, HPAGE hPage, IMAGEINDEX iiImg, LPCRECT pSrcRect, IMG_ROTATE Rotation, LPIMG_INFO lpImg, BYTE **lplpBitmap)
	Copying image area with rotation.
RECERR RECAPIKRN	kRecInvertImgArea (int sid, HPAGE hPage, LPCRECT lpRect)
	Inverting image area.
RECERR RECAPIKRN	kRecClearImgArea (int sid, HPAGE hPage, LPCRECT lpRect)
	Clearing image area.
RECERR RECAPIKRN	kRecFillImgArea (int sid, HPAGE hPage, LPCRECT lpRect, REC_COLOR color, FILLAREA_FLAGS flags)
	Filling image areas with a specified color.
RECERR RECAPIKRN	kRecDeskewImg (int sid, HPAGE hPage, int ImgSlope)
	Deskewing.
RECERR RECAPIKRN	kRec3DDeskewImg (int sid, HPAGE hPage)
	3D deskewing
RECERR RECAPIKRN	kRecEnhanceWhiteboardImg (HPAGE hPage)
	Enhancing images taken from whiteboards.
RECERR RECAPIKRN	kRecTransformImgByMatrix (int sid, HPAGE hPage, const SIZE newsize, const double matrix)
	Performing geometrical transformation determined by a matrix.
RECERR RECAPIKRN	kRecTransformImgByPoints (int sid, HPAGE hPage, const SIZE newsize, const POINT pOriginal, const POINT *pTransformed, int nPoints)
	Performing geometrical transformation determined by points.
RECERR RECAPIKRN	kRecIsImgPalette (int sid, HPAGE hPage, IMAGEINDEX iiImg, LPINTBOOL pbPal)
	Inquiring about palette of the image.
RECERR RECAPIKRN	kRecSetImgPalette (HPAGE hPage, const BYTE *pPal)
	Setting palette of the image.
RECERR RECAPIKRN	kRecGetImgPalette (int sid, HPAGE hPage, IMAGEINDEX iiImg, LPBYTE pPal)
	Getting the palette of the image.
RECERR RECAPIKRN	kRecDespeckleImg (int sid, HPAGE hPage)
	Despeckling.
RECERR RECAPIKRN	kRecForceDespeckleImg (int sid, HPAGE hPage, LPCRECT pRect, DESPECKLE_METHOD method, int level)
	Forcing despeckle.
RECERR RECAPIKRN	kRecImgErosion (int sid, HPAGE hPage, ERO_DIL_TYPE type)
	Erosion.
RECERR RECAPIKRN	kRecImgDilatation (int sid, HPAGE hPage, ERO_DIL_TYPE type)
	Dilatation.
RECERR RECAPIKRN	kRecConvertImg2BW (int sid, HPAGE hPageIn, IMG_CONVERSION Conversion, int Brightness, int Threshold, IMG_RESENH resolenh, HPAGE *phPageOut)
	Converting an image to a B/W image.
RECERR RECAPIKRN	kRecTransformImg (int sid, HPAGE hPage, IMAGEINDEX iiImg, LPCRECT pSrcRect, LPCSIZE pDstSize, WORD BitsPerPixel, HPAGE *phPageOut)
	Transforming an image.
RECERR RECAPIKRN	kRecTransformImgPalette (int sid, HPAGE hPage, IMAGEINDEX iiImg, LPCRECT pSrcRect, LPCSIZE pDstSize, HPAGE *phPageOut)
	Transforming palette-color images.
RECERR RECAPIKRN	kRecCopyImgArea (int sid, HPAGE hPageDst, LPCRECT pRectDst, HPAGE hPageSrc, LPCRECT pRectSrc)
	Copying an image area.
RECERR RECAPIKRN	kRecMergeImgArea (int sid, HPAGE hPageDst, LPCRECT pRectDst, HPAGE hPageSrc, LPCRECT pRectSrc, REC_COLOR tColor)
	Merging areas of images.
RECERR RECAPIKRN	kRecConvertImg (int sid, HPAGE hPage, WORD BitsPerPixel, UINT flags)
	Changing color depth.
RECERR RECAPIKRN	kRecLineRemoval (int sid, HPAGE hPage, const RECT *pRect)
	Removing lines.
RECERR RECAPIKRN	kRecRemoveLines (int sid, HPAGE hPage, IMAGEINDEX iiImg, const RECT *pRect)
	Removing lines.
RECERR RECAPIKRN	kRecGetLineCount (HPAGE hPage, int *pnLines)
	Getting the number of rule lines.
RECERR RECAPIKRN	kRecGetLineInfo (HPAGE hPage, IMAGEINDEX iiImg, PRLINE pLine, int nLine)
	Getting rule line information.
RECERR RECAPIKRN	kRecGetFrameCount (HPAGE hPage, int *pnFrames)
	Getting the number of frames.
RECERR RECAPIKRN	kRecGetFrameInfo (HPAGE hPage, IMAGEINDEX iiImg, LPCELL_INFO pFrame, int nFrame)
	Getting frame information.
RECERR RECAPIKRN	kRecSetDropoutColorWeights (int sid, int wred, int wgreen, int wblue)
	Changing the dropout color weight settings for binarization.
RECERR RECAPIKRN	kRecGetDropoutColorWeights (int sid, int pwred, int pwgreen, int *pwblue)
	Getting the dropout color weight settings.
RECERR RECAPIKRN	kRecDetectDropoutColorWeights (int sid, HPAGE hPage, IMAGEINDEX iiImg, RECT pRect, int pwred, int pwgreen, int pwblue)
	Detecting dropout color weights.
RECERR RECAPIKRN	kRecDropImg (HPAGE hPage, IMAGEINDEX iiImg)
	Removing an image from the page.
RECERR RECAPIKRN	kRecTransformCoordinates (HPAGE hPage, IMAGEINDEX iiDst, IMAGEINDEX iiSrc, int nP, LPPOINT pPoint)
	Transforming coordinates between images of a page.
RECERR RECAPIKRN	kRecRotateImg (int sid, HPAGE hPage, IMG_ROTATE Rotation)
	Rotating the page.
RECERR RECAPIKRN	kRecCreateImg (int sid, int sizeX, int sizeY, int dpiX, int dpiY, WORD BitsPerPixel, HPAGE *phPage)
	Creating an empty image.
RECERR RECAPIKRN	kRecFreeImg (HPAGE hPage)
	Removing a page.
RECERR RECAPIKRN	kRecGetImgInfo (int sid, HPAGE hPage, IMAGEINDEX iiImg, LPIMG_INFO pImg)
	Getting image information.
RECERR RECAPIKRN	kRecGetImgMetaData (HPAGE hPage, HSETTING *phMetaData)
	Getting additional information about the page.
RECERR RECAPIKRN	kRecGetImgFlags (HPAGE hPage, IMG_FLAGS Flag, INTBOOL *pbValue)
	Getting the value of image flags.
RECERR RECAPIKRN	kRecSetImgFlags (HPAGE hPage, IMG_FLAGS Flag, INTBOOL bValue)
	Setting the image flags.
RECERR RECAPIKRN	kRecSetImgResolution (HPAGE hPage, SIZE DPI)
	Changing the resolution of an image.
RECERR RECAPIKRN	kRecSetRetainColor (int sid, RETAINCOLOR RetainColor)
	Changing retain color setting.
RECERR RECAPIKRN	kRecGetRetainColor (int sid, RETAINCOLOR *pRetainColor)
	Getting retain color setting.
RECERR RECAPIKRN	kRecImgAutoEnhance (HPAGE hPage, BYTE blackPointred, BYTE whitePointred, BYTE blackPointgreen, BYTE whitePointgreen, BYTE blackPointblue, BYTE whitePointblue)
	Image auto-enhancement.
REC_COLOR flag values
Possible values of REC_COLOR type.
#define	REC_UNDEF_COLOR 0x01000000
	Undefined color.
#define	REC_TRANSPARENT_COLOR 0x02000000
	Transparent color (text on graphics)
#define	REC_DEFAULT_COLOR 0x80000000
	Default color.
#define	REC_DEFAULT_BGCOLOR 0x81000000
	Default background color.
#define	REC_BLACK 0x00000000
	Black color.
#define	REC_WHITE 0x00ffffff
	White color.
Flags of rule lines
See RLINE::flag.
#define	LF_HVMASK 0x03
	Mask of horizontal / vertical flags.
#define	LF_HORZ 0x01
	Horizontal rule line.
#define	LF_VERT 0x02
	Vertical rule line.

Detailed Description

Image handling tools.

The Capture SDK Engine is page-oriented: the basic unit used in processing is typically the image of the page, Most functions require a page (HPAGE) as an input parameter, but some API calls also operate on rectangular areas of the image (zones).

The Image handling module enables the Engine to handle several pages at the same time. The limit on the number of pages depends on the size of available physical memory and the size of the swap file used as virtual memory. The Engine can only manage and process pages within its own memory space: images must be loaded into the Engine first (by the Image File Handling Module, or the Scanning Module). Possible image sources include files, scanning devices or the memory of the integrating application.

HPAGE may contain different representations of the loaded image. These correspond to processing phases (loading, preprocessing, OCR) or to image use (view, thumbnail). The representations can be identified by IMAGEINDEX.

The best resolution for B/W images is 300 or 400 dpi. For grayscale or color images the optimal recogniton resolution is 150 to 300 dpi.

Before quitting, the application should free all pages created in the Image Handling Module (kRecFreeImg).

NOTE: In both the SDK and its documentation coordinates refer to grid-coordinates - i.e. the top or left borders of pixels. Thus a rectangle does not contain the pixels according to its right and bottom coordinates.

CSDK offers pre-recognition functions to apply image pre-processing procedures to images. These will enhance their quality, and yield more accurate auto-zoning and recognition. Preprocessing can include any or all of the following steps:

Inversion: automatic, programmed or none (kRecSetImgInvert)
Rotation: automatic, programmed or none (kRecSetImgRotation)
Deskewing: automatic, programmed or none (kRecSetImgDeskew)
FaxCorrection: automatic or none (kRecSetFaxCorrection)

In addition, image despeckling (kRecSetImgDespeckleMode) and resolution enhancements (kRecSetImgResolEnhancement) are also performed internally so that the above transformations can render better results.

Additional tasks in this module include

user modification of the loaded images,
detection and cutting of book pages (when the image contains two book pages),
line information detection (see RLINE) and
frame information detection (see kRecGetFrameInfo).

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

Notes on Deskew and Orientation

Operational conditions

The automatic orientation (ROT_AUTO) and automatic deskewing (DSK_AUTO) algorithm supports the following types of textual content (FILLINGMETHOD):

Omnifont,
Draft 24-pin dot-matrix printouts,
OCR-A,
OCR-B,
MICR (E-13B).

For the expected result of these automatic algorithms the image should be of good quality and it should include at least one text line which includes a machine printed text of at least 30 characters.

Neither handprinted text nor 9-pin draft dot-matrix printouts can be used for automatic deskewing or automatic orientation of the image.

Angle limits

Detecting the skew (kRecDetectImgSkew) is effective only on images with lower than 15-degree skew. However, the deskew operation uses different limits.

There are lower limits of performing deskew, because under these limits deskew does not help to improve accuracy, but may result in lower accuracy. These lower limits depend on the setting RMTRADEOFF as the following:

TO_ACCURATE and TO_BALANCED:
- for B/W and palette color images: 0.29 degrees,
- for grayscale and true color images: 0.17 degrees,
TO_FAST:
- for B/W and palette color images: 0.46 degrees,
- for grayscale and true color images: 0.29 degrees.

Under these limits, deskew is not run.

In fast mode, the thresholds are higher, because the used OCR engines are more sensitive to noise on the contours. In accurate and balanced mode, the higher layout accuracy requires lower thresholds (e.g. drawing splitters into a large gridded table).

On grayscale and true-color images an interpolation algorithm can be applied, so the deskewed characters contain less noise. On B/W and palette-color images interpolation cannot be applied, so if the slope is small, deskew method damages the character contours and does not help to improve accuracy.

The upper limit may also differ. Performing a programmed (DSK_SET) or an immediate (kRecDeskewImg) deskew, the upper limit is 30 degrees.

Reconstruct algorithm

There is a 'reconstruct' algorithm which is performed only on B/W images during deskew, if the slope of the image is less than the setting Kernel.Img.ReconstructAngle.

Normally, when this algorithm is not applied, deskew performs horizontal and vertical shearings on the image. Therefore shearing creates 'steps' on the contours of the characters.

The reconstruct algorithm restores the shapes of the small characters to their original state. So these small characters remain slanted but their positions will be deskewed. In this case, the OCR accuracy is little bit higher than without this reconstruction.

Arabic cases

The deskew and orientation detection work in a different way with Arabic language than in the case of other languages. The working of both operations can be adjusted through settings (Kernel.Img.Deskew.EnabledForArabic and Kernel.Img.Rotation.EnabledForArabic). If these settings are FALSE (in default), the AUTO methods (DSK_AUTO, ROT_AUTO) of these operations for Arabic OCR equal to the case when they are switched off (DSK_NO, ROT_NO). If the settings are TRUE, or the deskew and orientation are not set to AUTO, the working of these methods are the same for both the Arabic and the Western cases.

Digital camera input

OCR can now be performed on images containing texts that were captured by digital cameras with 2 megapixels and above. This is achieved with new pre-processing algorithms. Automatic digital camera preprocessing has three parts:

Resolution enhancement: This is applied if required, interpolating to yield a pixel density 1.5 or 2 times the original.
Text line straightening: This removes distortion when capturing book pages that cannot be completely flat.
Removing parallax distortion: This results if the camera is not perpendicular to the page. For best results, the image should contain at least six lines of text, preferably justified.

The following table shows the recommended minimum point size of text for different megapixel values – assuming focus is sharp, contrast is high and images are taken with care, as described below.

	A4 (8.27” x 11.69”)	A5 (8.27” x 5.85”)
Pixel size in a 300 dpi scan	2481 x 3507	1753 x 2481
2 megapixels (1600 x 1200)	18 pts	12 pts
3 megapixels (2048 x 1536)	14 pts	10 pts
4 megapixels (2272 x 1704)	12 pts	9 pts
5 megapixels (2560 x 1920)	11 pts	8 pts

The point sizes given for the European A4 size are also valid for the American Letter sized page (8.5” x 11”). A5 is similar to half a Letter-sized page.

As a general rule, an upper case letter must have at least 18 pixels vertically. Therefore, when capturing just several lines of large text, for instance from a label or notice, even a simple mobile phone camera under 0.5 megapixels can deliver good recognition if the rules given below are followed.

Of course these pre-processing algorithms can be applied to any image containing text distorted as described, irrespective of the capturing device. Conversely, text well captured by digital camera without distortions and good lighting may be successfully processed by the normal algorithms.

Automatic 3D-deskew

The preprocessing function or method IMG_DESKEW has a new parameter: DSK_3D, in addition to DSK_AUTO, DSK_NO, DSK_SET. When you call the preprocess method with DSK_3D, three-dimensional deskewing runs, as detailed above. If an Asian language (either CCJK, Arabic, Thai or Hebrew) is set for recognition before pre-processing, auto-deskew will not be available.

Manual 3D deskew

This feature can be accessed only from the IVC visual control of the CSDK. Please see the CSDK Visual Controls documentation for details.

How to capture good quality images

Lighting: Clear, even lighting with good contrast is important (no shaded parts).
Stable camera position: Use a tripod or other steadying device.
Camera axis: As close to perpendicular to the page as possible.
Correct distance: Minimum: 20-25 cm / 10-20 inches. In macro mode can be less. For fixed focus cameras, macro mode should be used, if available.
Resolution (pixel density): Depends on camera resolution, distance between camera and page, and character size. The higher the resolution, the sharper the image.

Inverse text and color lines

The detection of colored lines and inverse texts in the recognition process is improved in CSDK 16. Line color is detected only if the retain color setting is set to RETAINCOLOR_YES. See also: Kernel.OcrMgr.RetainColor and kRecSetRetainColor. Inverted text is automatically detected; it requires no special zone type, being expressed simply as a font color/background color combination. White letters on a black background will be detected in all cases; to conserve colored inverse text or backgrounds, RETAINCOLOR_YES must be set.

The line color attribute is stored in the color field of the RLINE structure and can be obtained by the function kRecGetLineInfo.

Despeckle for halftone images

Scanners often have the possibility of specifying whether the type of the document is 'text', 'photo' or 'text/photo' (mixed). When text/photo or photo is selected (and black-and-white scanning is choosen) the scanners apply a halftone or dithering algorithm to simulate gray levels. In this case the scanned image contains a lot of noise and a special despeckle algorithm is required to preprocess it before OCR. This special algorithm can be switched on and off with the setting Kernel.Img.Despeckle.Halftone. See also notes of kRecSetImgDespeckleMode.

Define Documentation

#define CROP_CLEARMARGIN 1

Fill the remaining margins white.

Typedef Documentation

typedef DWORD REC_COLOR

Color type.

This is 24-bit color information. The lower 8 bits are the red component, the next 8 bits are the green one and the third 8 bits the blue one. These components are intensity values from 0 to 255. Black is 0 (REC_BLACK) and white is 0xFFFFFF (REC_WHITE). There are some additional predefined colors: REC_UNDEF_COLOR and REC_DEFAULT_COLOR.

Enumeration Type Documentation

enum DESPECKLE_METHOD

Despeckle method used by kRecForceDespeckleImg.

Enumerator:

DESPECKLE_AUTO	The applied method is determined automatically. kRecForceDespeckleImg performs the same adaptive noise removal, as kRecDespeckleImg. Level is not used.
DESPECKLE_NORMAL	Black noise is removed, contours are smoothed. Level can be set between 1 and 4.
DESPECKLE_INVERSE	White noise is removed, contours are smoothed. Level can be set between 1 and 4.
DESPECKLE_HALFTONE	Despeckle half-tone image. Level can be set between 1 and 4.
DESPECKLE_MEDIAN	3*3 median filtering. Level is not used.
DESPECKLE_PEPPER	Remove small noise from contours. level is not used. Remove black dots whose width and height are less or equal to the given size. The contours of the other objects are not smoothed. The level parameter specifies the size, it must be between 1 and 256.
DESPECKLE_SALT	Remove white dots whose width and height are less or equal to the given size. The contours of the other objects are not smoothed. The level parameter specifies the size, it must be between 1 and 256.
DESPECKLE_PEPPERANDSALT	Remove both black and white dots whose width and height are less or equal to the given size.

enum ERO_DIL_TYPE

Type of neighborhood used by kRecImgErosion and kRecImgDilatation.

Enumerator:

ERO_DIL_3	Left, upper, and upper-left neighbors are tested.
ERO_DIL_4	Left, upper, right and lower neighbors are tested.
ERO_DIL_8	All eight neighbors are tested.

enum FILLAREA_FLAGS

Determining the area to be filled by kRecFillImgArea.

Enumerator:

FILL_INSIDE	Fill the image inside the rectangle.
FILL_OUTSIDE	Fill the image outside the rectangle.
FILL_FLEXIBLEBPS	Increase BitsPerPixel of the image if necessary. E.g.: the current image is gray-scale (BistPerPixel = 8) and the fill-color is red: if this flag is set the image is changed to 24-bit true-color, if this flag is not set the fill-color is converted down to gray. This parameter can be combined with `FILL_INSIDE` or `FILL_OUTSIDE`.

enum IMAGEINDEX

Index of each image type in HPAGE.

HPAGE may contain several images created from the same page source (e.g. scanner, image file, etc). These image types play different roles: distinct page processing phases run on them. You can refer to these image types using their indices.

Each image type of HPAGE may have different coordinate systems. In the page all the coordinates are stored referring to the coordinate system of the black-and-white image. However, coordinates passing to or getting from the functions can refer to the coordinate system of any image.

Due to the conversions between coordinate systems, a coordinate received from a function may differ from the previously set coordinate.

After preprocessing, rotating or deskewing, the difference between the coordinate systems of the current and original images is a geometric rotating transformation. Thus, if there is a rectangle (possibly a zone) specified with the coordinates from the original image its vertices are converted into the BW image and the bounding rectangle of the resulting points are stored. Therefore, the vertices of the stored rectangle can significantly differ from those of the original one.

The coordinate system of the BW image can differ from that of the current image only in a scalar factor viz. if the current one is not binary and resolution enhancement is used at binarization, the resulting image has a higher resolution.

The OCR and the BW images have the same coordinate systems.

Coordinates are specified in pixels. The origin is always in the top-left corner of the image with the coordinates (0,0). The bottom-right pixel has the coordinates (sx-1, sy-1), where sx is the horizontal and sy is the vertical size of the image in pixels.

When a function gets an IMAGEINDEX for specifying the coordinate system, II_THUMBNAIL cannot be passed. The functions accepting this index are as follows: kRecGetImgArea, kRecStartReadImg, kRecRotateImgArea, kRecIsImgPalette, kRecGetImgPalette, kRecTransformImg, kRecTransformImgPalette, kRecDropImg, kRecGetImgInfo, kRecSaveImg, kRecSaveImgForce, kRecSaveImgF, kRecSaveImgForceF, kRecSaveImgArea, kRecSaveImgAreaF, kRecInsertImgFilePage, kRecMatchImgFileFormat, kRecMatchImgFileFormat, kRecUpdateImgFilePage.

Lifetime of different images:

II_ORIGINAL: this is created when the image is loaded (on HPAGE creation). It is automatically deleted during the first operation that modifies the image (e.g. kRecPreprocessImg, kRecRotateImg, etc.). It can be kept by calling kRecSetPreserveOriginalImg. It can also be deleted any time by calling kRecDropImg.
II_CURRENT: this is created when the image is loaded (on HPAGE creation). It cannot be deleted even by calling kRecDropImg.
II_BW: It is created by the first operation that needs it. Preprocessing, page-layout decomposition and recognition processes always create it, but so does any other function that needs it providing that it receives the image index II_BW and they need this image (e.g. kRecGetImgInfo, kRecGetImgArea, etc.). II_BW can be deleted any time by calling kRecDropImg.
II_OCR: It exists exclusively during the recognition process. Even if there has already been an OCR image at the start of recognition, it is always recreated. To keep it, the setting "Kernel.OcrMgr.Images.KeepOcrImage" must be set to TRUE.
II_THUMBNAIL: It is created only when the image index II_THUMBNAIL is passed to a function and the function needs this image (e.g. kRecGetImgInfo, kRecGetImgArea, etc.). It can be deleted any time by calling kRecDropImg.

Enumerator:

II_UNDEFINED	Undefined type.
II_BGLAYER	Background layer. This image exists only for non-image-only PDF and XPS. It contains the background image without the text layer. Used internally by the PID_DECOMPOSITION process.
II_ORIGINAL	Original image from scanner or from file. Deskew, rotation, and other image manipulation functions do not modify this image. By default this image exists until `II_CURRENT` is generated from it and then it is deleted from the HPAGE. If you want to preserve this image, call kRecSetPreserveOriginalImg.
II_CURRENT	This is the current image. Most functions work on this image. This image always exists. After loading an image it corresponds with the original image. Deskew, rotation, and other image manipulation functions modify this image. To keep compatibility with the previous version of CSDK, use II_CURRENT.
II_BW	Black-and-white image generated from the current image during pre-processing or implicit secondary image conversion. This image is used e.g. by the PID_DECOMPOSITION process. It can have higher resolution than the current image.
II_OCR	OCR image generated from the BW one by the recognition process. This is a black-and-white image used by the OCR engines. It contains information only inside the zones to be recognized. These zones may be auto-inverted; underlines and graphical elements may be removed from them. The creation method depends on the current page parse, OCR settings and the properties of the zones
II_THUMBNAIL	Thumbnail image (miniature color image) generated from the current one. Its creation preserves aspect ratio, but the resulting image has the user-given size. Therefore empty areas may be generated at the top and bottom, or the left and right sides of that image. These empty areas will be filled with a given color called thumbnail color. See kRecSetThumbnailImgInfo.
II_OUTPUT	Used internally by output converters.
II_SIZE	Number of image types for verifying index validity and creating the image array.

enum IMG_COMPRESSION

Image compression types.

These types can be used at loading page from compressed memory buffer (kRecLoadImgMC and kRecLoadImgDataStreamMC).

Note:: DataStream supports only JPEG and JPEG2000 compression types.

Enumerator:

COMPRESS_TIFHU	Group 3 Modified TIFF image format.
COMPRESS_TIFG31	Standard G3 1D TIFF image format.
COMPRESS_TIFG32	Standard G3 2D TIFF image format.
COMPRESS_TIFG4	Standard G4 TIFF image format.
COMPRESS_JPEG	Standard JPEG image (file) format.
COMPRESS_JPG2K	Standard JPEG2000 image (file) format.
COMPRESS_SIZE	Number of compression types.

enum IMG_CONVERSION

Image conversion types.

Image conversion modes to be applied for conversions from grayscale or color image sources. These values specify how different image types will be converted either during primary image conversion ( loading an image into the Engine) or during secondary image conversion, (an image - already in the Engine's memory space - undergoes an image conversion step).

Note:: These modes can be set by kRecSetImgConvMode for primary and by kRecSetImgBinarizationMode for secondary image conversion.; Secondary image conversions are performed on an existing hPage page. This step is activated either directly (from within the kRecConvertImg2BW function) or implicitly. This latter case may occur when the application calls a KernelAPI API function whose operation requires a B/W image but the available image is not a B/W one, making an implicit image conversion necessary.; In primary image conversion, the default conversion type is CNV_NO. In secondary image conversion, the default conversion type is CNV_AUTO.; During primary image conversion CNV_SET and CNV_GLOBAL produce the same results as they do during secondary image conversion. However, CNV_AUTO method is faster in primary than in secondary conversion, but the result is less optimal for OCR. In general, it is true that the most optimal result for OCR can be achieved with the default values of these settings.

Enumerator:

CNV_AUTO	This affects grayscale or 24-bit color images: a B/W image will be created in the Engine's memory. Image binarization applies an automatic adaptive thresholding algorithm. The kRecSetImgBrightness function can be used to tune the threshold calculation.
CNV_SET	This affects grayscale or 24-bit color images: a B/W image will be created in the Engine's memory. Thresholding with a user-defined threshold value, set by the kRecSetImgThreshold function.
CNV_NO	There will be no conversion while image loading. The image will be loaded into the Engine's memory without any conversion (i.e. a color image will retain its color attributes).
CNV_GLOBAL	This affects grayscale or 24-bit color images: a B/W image will be created in the Engine's memory. For image binarization, an automatic thresholding algorithm with a page-level global threshold value is applied.
CNV_GRAY	For a color image: a grayscale image will be created in the Engine's memory. For a B/W or grayscale image: no conversion will be performed while loading the image.

enum IMG_DESKEW

Image deskewing mode.

This setting determines the deskewing mode during image preprocessing.

Note:: For additional information about deskew (e.g limits of page angle, Arabic differences) see Notes on Deskew and Orientation.

Enumerator:

DSK_2D	Automatic 2D deskewing (Default).
DSK_AUTO	Deprecated. Use DSK_2D instead.
DSK_NO	No deskewing applied.
DSK_SET	Deskew with a given angle set by the kRecSetImgSlope function.
DSK_3D	Automatic 3D deskewing applied.
DSK_AUTO3D	Automatic 2D or 3D deskewing: 2D deskewing applied on scanned images and 3D deskewing applied on digital camera images. see also: IMG_FLAGS

enum IMG_FLAGS

Image flags.

These flags can be inquired by kRecGetImgFlags, and used by kRecPreprocessImg

Enumerator:

IMG_FLAGS_CAMERAIMAGE	Source image file is captured by digital camera or phone.
IMG_FLAGS_NORESOLUTION	Source image file does not contain resolution info. Default resolution has been set.

enum IMG_INVERT

Image inversion mode.

Possible inversion modes. This setting determines the inversion mode used by kRecPreprocessImg on the whole image. Note that kRecPreprocessImg inverts the II_BW image only. The inversion means that the II_BW image is changed from white-on-black to black-on-white, because this is needed for successful recognition.

Enumerator:

INV_NO	No inversion required.
INV_YES	Image inversion should be performed. The II_BW image is inverted.
INV_AUTO	Automatically inverts the II_BW image, if necessary (Default): whether the image is inverse is determined during preprocessing.

enum IMG_LINEORDER

Image line order.

Line order setting determines the order of the lines in the passed or received buffer on calling kRecLoadImgM, kRecPutImgArea, kRecGetImgArea and kRecRotateImgArea. To specify this setting use kRecSetImgFormat before invoking any of the above functions.

Enumerator:

TOP_DOWN	First line is the top line of the image (Default).
BOTTOM_UP	First line is the bottom line of the image.

enum IMG_PADDING

Image padding.

Padding mode setting for the image in the application's memory space. The Padding mode setting determines how the lines in the image are to be padded on calling kRecGetImgArea and kRecRotateImgArea. To specify this setting use kRecSetImgFormat call before invoking any of these functions.

Enumerator:

PAD_BYTEBOUNDARY	Lines of the image are padded to byte boundaries.
PAD_WORDBOUNDARY	Lines of the image are padded to word (double byte) boundaries (Default).
PAD_DWORDBOUNDARY	Lines of the image are padded to double word boundaries.

enum IMG_RESENH

Image resolution enhancement.

Resolution enhancement is applied during the binarization of non-B/W images. It means that the resolution of the created binary image is larger than the resolution of the non-BW image. The ratio of the enhancement currently can be 1.5 or 2.0, depending on the current IMG_RESENH setting. For images from digital camera or phone the ratio can be 0.5 as well. To set resolution enhancement, use the kRecSetImgResolEnhancement function.

Enumerator:

RE_NO	No resolution enhancement applied.
RE_YES	Apply enhancement, ratio = 2.0.
RE_LEGACY	The ratio of the enhancement depends on the resolution of the non-BW image. The ratio is 2.0 if the resolution is less than or equal to 160 DPI, and 1.5 if the resolution is less than or equal to 210 DPI. Otherwise resolution enhancement is not applied (this mode is the same as RE_AUTO in version 12.6).
RE_STANDARD	The ratio is detected dynamically: it depends on the resolution of the non-BW image and on the detected average character size. Resolution enhancement is not applied above 210 DPI. The mentioned character size detection is performed only during image preprocessing, thus without calling kRecPreprocessImg `RE_STANDARD` is equivalent to `RE_LEGACY`.
RE_AUTO	Enhancement depends on the current trade-off setting: if trade-off is TO_FAST use RE_LEGACY, otherwise use RE_STANDARD. RE_AUTO is the default setting.

enum IMG_RGBORDER

Image color order.

Possible orders of the composite color components of a 24-bit color image. It defines how the image is to be interpreted on calling kRecLoadImgM, kRecPutImgArea, kRecGetImgArea kRecRotateImgArea and kRecGetImgAreaEx. To specify this setting, use the kRecSetImgFormat call before invoking the above functions (except for kRecGetImgAreaEx).

Enumerator:

COLOR_RGB	Defines that the order of the composite color components is R-G-B (Default).
COLOR_BGR	Defines that the order of the composite color components is B-G-R (used for Windows DiBitmap).
COLOR_BGRA	Defines that the order of the composite color components is B-G-R-A (blue-green-red-alpha). This value is used only by kRecGetImgAreaEx and kRecLoadImgM.
COLOR_ARGB	Defines that the order of the composite color components is A-R-G-B (alpha-red-green-blue). This value is used only by kRecGetImgAreaEx and kRecLoadImgM.

enum IMG_ROTATE

Available image transformations (rotation and/or mirroring).

Rotation is always carried out in 90-degree steps. The following table shows the results of the image transformation using different values.

Original image:

123

456

789
- Transformed image:
  
  ROT_NO: LEFT: RIGHT: DOWN:
  
  123 369 741 987
  
  456 258 852 654
  
  789 147 963 321
  
  FLIPPED: LEFT_FLIPPED: RIGHT_FLIPPED: DOWN_FLIPPED:
  
  321 147 963 789
  
  654 258 852 456
  
  987 369 741 123

Note:: Automatic image rotation settings (ROT_AUTO) can only be used with good quality machine-printed texts, but not with images containing 9-pin dot-matrix text or other non-machine printed text.; Mirroring values (those with the suffix FLIPPED) are ignored during image pre-processing kRecPreprocessImg. They are available only through kRecRotateImg and kRecRotateImgArea.; For additional information about rotation (e.g Arabic differences) see Notes on Deskew and Orientation.

Enumerator:

ROT_AUTO	Automatic image rotation (Default).
ROT_NO	Do not transform the image.
ROT_RIGHT	Rotate image to the right (clockwise).
ROT_DOWN	Rotate image down (rotate twice).
ROT_LEFT	Rotate image to the left (anti-clockwise).
ROT_FLIPPED	Mirror image without rotation (mirrored around the Y-axis).
ROT_RIGHT_FLIPPED	Mirror image, then rotate to the right.
ROT_DOWN_FLIPPED	Mirror image, then rotate twice.
ROT_LEFT_FLIPPED	Mirror image, then rotate to the left.

enum IMG_STRETCHMODE

Image stretching mode.

Possible values for the Image stretching mode setting. This setting is used by the kRecGetImgArea function if the destination rectangle size is definitely smaller than the source one. The setting specifies how the pixels of the input image are combined to get the resulting image during the operation of this function.

Enumerator:

STRETCH_DELETE	Deletes eliminated pixels. Information in the eliminated pixels is not preserved (Default).
STRETCH_OR	Uses the OR operator to combine eliminated pixels with the remaining ones. This mode preserves black pixels at the expense of white pixels. (Assuming that black is coded as 1.)
STRETCH_AND	Uses the AND operator to combine eliminated pixels with the remaining ones. This mode preserves white pixels at the expense of black pixels.
STRETCH_AVG	If the image is B/W, 4-bit grayscale or 8-bit grayscale use 256-level grayscale to combine eliminated pixels. This results in an output of an 8-bit grayscale bitmap. If the image is palette-color or 24-bit color, use 24-bit color to combine eliminated pixels. This produces an output of a 24-bit color bitmap. Note, that if the destination rectangle size is greater than the source rectangle size, the BitsPerPixel of the output bitmap will be the same as the BitsPerPixel of the input image. Use the returned IMG_INFO from kRecGetImgArea to obtain the correct BitsPerPixel value of the created bitmap.

enum JPG_ORIENTATION

Image orientation for JPEG files.

Possible values of Kernel.Imf.JPG.Orientation setting. This setting specifies the orientation of the image when JPEG file is loaded.

Enumerator:

JPG_ORIENTATION_IGNOREEXIF	Do not use the orientation tag of the EXIF info.
JPG_ORIENTATION_USEEXIF	Apply the orientation tag of the EXIF info if exists.

enum JPG_RESOLUTION

Image resolution for JPEG files.

Possible values of Kernel.Imf.JPG.Resolution setting. This setting specifies how to set image resolution if the header of the input JPEG file does not contain DPI information.

Enumerator:

JPG_RES_USEDEFAULTDPI	Use the resolution specified by Kernel.IMF.DefaultDPI setting.
JPG_RES_USEEXIF	If JPEG header does not contain resolution info, read the resolution tag of the EXIF info if exists.

enum PREPROC_INFO_FLAGS

Flags for the structure PREPROC_INFO.

Enumerator:

PREPROC_INFO_FAXCORRECTION	Fax-correction applied.
PREPROC_INFO_INVERSION	II_BW image inverted.
PREPROC_INFO_3DDESKEW	3D deskew applied.
PREPROC_INFO_STRAIGHTENED	Line straightening applied by 3D deskew.
PREPROC_INFO_HALFTONE	Halftone image, see kRecSetImgDespeckleMode

enum PROCESSING_MODE

Switching between processing modes.

Generally, a load-prerprocess-zoning-recognition-conversion workflow is built up to do anything it can for the best result of any type of output. However, there are some cases when certain steps can be skipped. E.g. if the required output is an ePub document, it is not important to do any true page formatting. The setting Processing.Mode can switch on such a restricted processing mode.

Enumerator:

PROCESSING_NORMAL

This is the normal workflow and the default setting.

PROCESSING_BOOK

This is the e-book mode. If this mode is switched on, the real position of the paragraphs are not important. The whole document is a flowing text with strongly normalized (not exact) linespacing. If a paragraph breaks across pages, their parts are connected. Footnotes and their references are marked. Of course any output format can also be used in this mode, but some of them do not fulfil all their original requirements due to these restrictions. E.g. in a true-page mode Word output the paragraph positions may be different from their original ones.

enum RETAINCOLOR

Retain color.

The recognition result can contain color information about letters, lines, frames, etc. The retain color setting indicates whether the color information from the image is used or not.

Note:: The page layout decomposition and recognition are faster when color is not retained, but the result of zoning may be worse (e.g. an indistinct graphic may vanish or zones with different background colors may be merged)

Enumerator:

RETAINCOLOR_NO	All the resulting items contain a white background and a black foreground color.
RETAINCOLOR_YES	The real color of the given item is used in the result. This is the default value.
RETAINCOLOR_INVERTED	The color of the given item is determined in the BW image of the page (II_BW).

Function Documentation

RECERR RECAPIKRN kRec3DDeskewImg	(	int	sid,
		HPAGE	hPage
	)

3D deskewing

The kRec3DDeskewImg function performs 3D deskew on the II_CURRENT image of the given page. The function tries to correct the skew and perspective distortion of an image taken by a digital camera. Parallel text lines are transformed to be horizontal and column edges are transformed to be vertical. The algorithm does not detect that a page is upside down therefore the transformed image may remain upside down. If there are BW (II_BW) and thumbnail (II_THUMBNAIL) images they are deskewed as well.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of page containing the image(s) to be deskewed.

Return values:

RECERR

Note:

The 3D deskew algorithm requires a certain number of characters, text lines and column edges. Column edges mean that the beginning and/or end of consecutive text lines have identical positions, i.e. the left edge of a column aligned left or both edges of a justified column. The minimal quantities are approximately 10 text lines and the edges of two columns or both edges of one column. The accuracy of the algorithm increases when there are a good number of lines and column edges and when these are not confined to a small area of the image. If the image contains only figures or graphics, no transformation occurs.

The specification of this function in C# is:

 RECERR kRec3DDeskewImg(int sid, IntPtr hPage);

RECERR RECAPIKRN kRecAutoCropImg	(	int	sid,
		HPAGE	hPage,
		int	lrMargin,
		int	tbMargin,
		UINT	flags
	)

Cropping white border.

This function detects the excessive border areas, and if they are greater than the given margins, it decreases them to that size. The image is resized to the new rectangle.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page to be processed.
[in]	lrMargin	Left and right margin (pixels).
[in]	tbMargin	Top and bottom margin (pixels).
[in]	flags	Set the CROP_CLEARMARGIN flag to have the margins remaining after cropping filled with the color white.

Return values:

RECERR

Note:

For a blank page this function gives ZONE_NOTFOUND_WARN.

The specification of this function in C# is:

 RECERR kRecAutoCropImg(int sid, IntPtr hPage, int lrMargin, int tbMargin, CROP_FLAGS flags);

RECERR RECAPIKRN kRecClearImgArea	(	int	sid,
		HPAGE	hPage,
		LPCRECT	lpRect
	)

Clearing image area.

The kRecClearImgArea function clears a rectangular area of all the images of a page except II_ORIGINAL. The image with a rectangle cleared replaces its origin and is available to the Engine and the application. The function assumes that the coordinates are given in the coordinate system of the current image (II_CURRENT).

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page containing the image to be modified.
[in]	lpRect	Pointer to a rectangle to be cleared by setting its bits to zero (0). A NULL value means the entire image.

Return values:

RECERR

Note:

For a B/W image, setting each bit to zero (0) results in an entirely white image. In any other case the resulting image will be entirely black. When a white image area is required in these latter cases, call kRecFillImgArea or kRecInvertImgArea.

The specification of this function in C# is:

    RECERR kRecClearImgArea(int sid, IntPtr hPage, RECT pRect);
    // or when pRect is NULL in C/C++
    RECERR kRecClearImgArea(int sid, IntPtr hPage);

RECERR RECAPIKRN kRecConvertImg	(	int	sid,
		HPAGE	hPage,
		WORD	BitsPerPixel,
		UINT	flags
	)

Changing color depth.

This function changes the color depth (bits per pixel) of the given image.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page to be processed. The II_CURRENT image of this page will be modified.
[in]	BitsPerPixel	New value of the bits per pixel. Possible values are: 1, 8, 24.
[in]	flags	The following parameters can be specified: CONVIMG_PALETTE, CONVIMG_ERRDIFF.

Return values:

RECERR

Note:

If BitsPerPixel is not 8, CONVIMG_PALETTE flag is ignored.

CONVIMG_ERRDIFF can be specified only when BitsPerPixel is 1 or when BitsPerPixel is 8 and CONVIMG_PALETTE is set.

The specification of this function in C# is:

 RECERR kRecConvertImg(int sid, IntPtr hPage, ushort bitsPerPixel, CONVIMG_FLAGS flags);

RECERR RECAPIKRN kRecConvertImg2BW	(	int	sid,
		HPAGE	hPageIn,
		IMG_CONVERSION	Conversion,
		int	Brightness,
		int	Threshold,
		IMG_RESENH	resolenh,
		HPAGE *	phPageOut
	)

Converting an image to a B/W image.

The kRecConvertImg2BW function creates a new image from an existing one. The function converts color or gray-scale images to Black-and-white (B/W) ones. It converts the current image (II_CURRENT) of the given input page. The resulting image will be the original image (II_ORIGINAL) of the given output page. This function performs a direct secondary image conversion step.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPageIn	Handle of the source page.
[in]	Conversion	Image conversion mode to be applied during the conversion of the image. Possible values are: CNV_AUTO, CNV_SET, CNV_GLOBAL.
[in]	Brightness	Brightness of the image (range is 0 to 100, where 0 means the darkest and 100 means the lightest resulting image). This parameter has an effect only if the `Conversion` parameter is CNV_AUTO.
[in]	Threshold	Threshold value to be set. Its range should be between 0 and 255. This parameter has an effect only if the `Conversion` parameter is CNV_SET.
[in]	resolenh	The resolution enhancement mode to be used during binarization.
[out]	phPageOut	Pointer of a variable to store the handle of the destination page.

Return values:

RECERR

Note:

If the output page is no longer needed it should be removed from the image management module by invoking the kRecFreeImg function.

The specification of this function in C# is:

 RECERR kRecConvertImg2BW(int sid, IntPtr hPageIn, IMG_CONVERSION Conversion, int Brightness, int Threshold, IMG_RESENH resolenh, out IntPtr phPageOut);

RECERR RECAPIKRN kRecCopyImgArea	(	int	sid,
		HPAGE	hPageDst,
		LPCRECT	pRectDst,
		HPAGE	hPageSrc,
		LPCRECT	pRectSrc
	)

Copying an image area.

This function copies a rectangular area of the II_CURRENT image of the given source page into a rectangular area of the II_CURRENT image of the given destination page. The function compresses or stretches the area if necessary to fit the dimensions of the destination size.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPageDst	Handle of the page which contains the destination image.
[in]	pRectDst	Coordinates of the destination rectangular area. NULL means the whole image.
[in]	hPageSrc	Handle of the page which contains the source image.
[in]	pRectSrc	Coordinates of the source rectangular area. NULL means the whole image.

Return values:

RECERR

Note:

If the destination size is smaller or greater than the original source area, the function compresses or stretches the area into the destination.

The BitsperSample of the source and the destination image must be the same.

The specification of this function in C# is:

    RECERR kRecCopyImgArea(int sid, IntPtr hPageDst, RECT rectDst, IntPtr hPageSrc, RECT rectSrc);
    // or when pRectDst is NULL in C/C++
    RECERR kRecCopyImgArea(int sid, IntPtr hPageDst, IntPtr hPageSrc, RECT rectSrc);
    // or when pRectSrc is NULL in C/C++
    RECERR kRecCopyImgArea(int sid, IntPtr hPageDst, RECT rectDst, IntPtr hPageSrc);
    // or when pRectDst and pRectSrc are NULL in C/C++
    RECERR kRecCopyImgArea(int sid, IntPtr hPageDst, IntPtr hPageSrc);

RECERR RECAPIKRN kRecCreateBookPages	(	int	sid,
		HPAGE	hPage,
		HPAGE *	phPage1,
		HPAGE *	phPage2,
		const CUT_INFO *	pInfo
	)

Cutting each opened book image into two pages.

This function cuts the two-page opened book images into two pages using the cutting information resulting from kRecDetectBook. It uses the page size stored by the first kRecDetectBook after a kRecInit or a kRecResetBookSize. The resulting HPAGEs should be preprocessed even if the pre-process operation was called before kRecDetectBook, because the skew of one page may differ from that of the other.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the two-part opened book page image.
[out]	phPage1	Pointer of a variable to store the handle of the left page cut from the book page.
[out]	phPage2	Pointer of a variable to store the handle of the right page cut from the book page.
[in]	pInfo	The cutting information resulting from kRecDetectBook.

Return values:

RECERR

Note:

Every call of this function should be preceded by a kRecDetectBook, which creates the cutting information for the given HPAGE.

To reset the stored size of the resulting pages (e.g. before scanning another book), use kRecResetBookSize.

This function uses the settings Kernel.Img.BookSize.X and Kernel.Img.BookSize.Y.

The specification of this function in C# is:

 RECERR kRecCreateBookPages(int sid, IntPtr hPage, out IntPtr phPage1, out IntPtr phPage2, [In] CUT_INFO pInfo);

RECERR RECAPIKRN kRecCreateImg	(	int	sid,
		int	sizeX,
		int	sizeY,
		int	dpiX,
		int	dpiY,
		WORD	BitsPerPixel,
		HPAGE *	phPage
	)

Creating an empty image.

The kRecCreateImg function creates a new, empty image by filling out a describing structure for the image management module and by allocating the proper amount of memory for the raw image data. This image will be attached to the page as both current and original image (II_CURRENT, II_ORIGINAL).

Parameters:

[in]	sid	Settings Collection ID.
[in]	sizeX	Horizontal size of the image to be created, in pixels.
[in]	sizeY	Vertical size of the image to be created, in pixels.
[in]	dpiX	Horizontal resolution of the image (Dots Per Inch).
[in]	dpiY	Vertical resolution of the image.
[in]	BitsPerPixel	Bits per pixel (bit depth). Possible values are: 1, 4, 8, 24 (B/W, 4-bit gray-scale, 8-bit gray-scale and 24-bit color images, respectively).
[out]	phPage	Pointer of the handle of the new page returned by the image management module.

Return values:

RECERR

Note:

The created image is filled with 0 (0 is white if the image is B/W and black otherwise).

To create a palette-color image, first create an 8-bit gray-scale image. Then call the kRecSetImgPalette function with a pointer to a palette to declare the image as a palette-color one.

The specification of this function in C# is:

 RECERR kRecCreateImg(int sid, int sizeX, int sizeY, int dpiX, int dpiY, ushort BitsPerPixel, out IntPtr phPage);

RECERR RECAPIKRN kRecDeskewImg	(	int	sid,
		HPAGE	hPage,
		int	ImgSlope
	)

Deskewing.

The kRecDeskewImg function performs immediate deskewing on the original image. The resulting image will be the current one (II_CURRENT). If there are BW (II_BW) and thumbnail (II_THUMBNAIL) images they are deskewed as well.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of a page containing the image(s) to be deskewed.
[in]	ImgSlope	Integer slope value for deskewing. The value given here is the number of pixels of vertical ascent on 1000 horizontal pixels. That is, the tangent of the deskew angle multiplied by 1000.

Return values:

RECERR

Note:

For information about limits of page angle using deskew operations see Notes on Deskew.

The coordinates of all user zones will be recalculated. The OCR zones will be removed.

The image to be deskewed can be of any type (B/W, grayscale or color).

This function ignores the current Image deskewing mode setting as set by a previous kRecSetImgDeskew call and also the value in kRecSetImgSlope. Those settings relate only to deskewing performed during pre-processing initiated by kRecPreprocessImg, which supports programmed or auto-deskewing.

The specification of this function in C# is:

 RECERR kRecDeskewImg(int sid, IntPtr hPage, int ImgSlope);

RECERR RECAPIKRN kRecDespeckleImg	(	int	sid,
		HPAGE	hPage
	)

Despeckling.

The kRecDespeckleImg function performs an immediate adaptive noise removal on the current (II_CURRENT) image, irrespective of its resolution. If the current image is not black-and-white the function returns IMG_BITSPERPIXEL_ERR.

Parameters:

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

Return values:

RECERR

Note:

This function is useful for images which originally had a grayed or colored background that was not completely removed by preprocessing. It can be useful also for faxed pages or those with a spotted background.

The algorithm runs at any resolution, however, it is optimized for images with at least 180 dpi resolution.

As an alternative, the setting kRecSetImgDespeckleMode is available.

See also: kRecLineRemoval.

The specification of this function in C# is:

RECERR kRecRemoveLines(int sid, IntPtr hPage, IMAGEINDEX iiImg, RECT pRect);
// or
RECERR kRecRemoveLines(int sid, IntPtr hPage);

RECERR RECAPIKRN kRecRemovePunchHoles	(	int	sid,
		HPAGE	hPage,
		LPCRECT	ROIs,
		int	nROIs,
		LPRECT *	Holes,
		int *	nHoles,
		UINT	flags,
		UINT	minDiameter,
		UINT	maxDiameter
	)

Removing punch holes.

Detecting punch hole image defects and transforming them to the background color.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page to be processed.
[in]	ROIs	Array of rectangles inside which the punch holes should be detected. If it is NULL then the whole image is processed.
[in]	nROIs	The number of rectangles in the ROIs array.
[in,out]	Holes	Pointer to a variable for storing the bounding boxes of the holes. It can be NULL. For details see the description of parameter `flags` below. If PHOLE_DETECT flag is set and Holes parameter is not NULL this array is allocated by the function and can be freed calling the function kRecFree.
[in,out]	nHoles	Pointer to a variable for storing the number of the holes. It can be NULL if `Holes` is NULL.
[in]	flags	The following flags can be set: PHOLE_DETECT : If this flag is set, the function automatically detects the punch holes. The bounding boxes of the detected punch holes are returned in the `Holes` array if the `Holes` parameter is not NULL. PHOLE_REMOVE : If this flag is set the function removes the punch holes from the image. If only this flag is set, the parameters `Holes` and `nHoles` must contain the bounding boxes and the number of holes (i.e. they are input parameters). `PHOLE_DETECT` and `PHOLE_REMOVE` flags can be combined.
[in]	minDiameter	Reserved for future versions. Must be 0.
[in]	maxDiameter	Reserved for future versions. Must be 0.

Return values:

RECERR

Note:

The function searches for sizes declared in punch hole standards.

The specification variations of this function in C# are:

    // Only removing
    RECERR kRecRemovePunchHoles(int sid, IntPtr hPage, RECT[] Holes);
    // Only detecting
    RECERR kRecDetectPunchHoles(int sid, IntPtr hPage, RECT[] ROIs, out RECT[] Holes, uint minDiameter, uint maxDiameter);
    RECERR kRecDetectPunchHoles(int sid, IntPtr hPage, out RECT[] Holes, uint minDiameter, uint maxDiameter);
    // Detecting and removing 
    RECERR kRecDetectAndRemovePunchHoles(int sid, IntPtr hPage, RECT[] ROIs, out RECT[] Holes, uint minDiameter, uint maxDiameter);
    RECERR kRecDetectAndRemovePunchHoles(int sid, IntPtr hPage, out RECT[] Holes, uint minDiameter, uint maxDiameter);

RECERR RECAPIKRN kRecResetBookSize ( int sid )

Resetting the stored book page size.

This function resets the book page size stored by kRecDetectBook. This function should be called every time you want to process more than one book and the page size of the next book differs from that of the previous one.

Parameters:

[in] sid Settings Collection ID.

Return values:

RECERR

Note:

This function is typically followed by a kRecDetectBook call.

This function resets the settings Kernel.Img.BookSize.X and Kernel.Img.BookSize.Y.

The specification of this function in C# is:

 RECERR kRecResetBookSize(int sid);

RECERR RECAPIKRN kRecRotateImg	(	int	sid,
		HPAGE	hPage,
		IMG_ROTATE	Rotation
	)

Rotating the page.

The kRecRotateImg function rotates and/or mirrors the page according to the given parameter. It can be perform rotation by 90 degrees or its multiples.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page containing the image to be rotated.
[in]	Rotation	Image transformation to be performed. Possible values can be any value of IMG_ROTATE except ROT_AUTO.

Return values:

RECERR

Note:

The coordinates of all user zones will be recalculated. The OCR zones will be removed.

The specification of this function in C# is:

 RECERR kRecRotateImg(int sid, IntPtr hPage, IMG_ROTATE Rotation);

RECERR RECAPIKRN kRecRotateImgArea	(	int	sid,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		LPCRECT	pSrcRect,
		IMG_ROTATE	Rotation,
		LPIMG_INFO	lpImg,
		BYTE **	lplpBitmap
	)

Copying image area with rotation.

The kRecRotateImgArea function copies and rotates a rectangular area of the current image (II_CURRENT) of a page into a buffer available to the application. The function assumes that the coordinates are given in the coordinate system of the current image (II_CURRENT).

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page which contains the source image.
[in]	iiImg	Index to the image in the page.
[in]	pSrcRect	Dimensions of the source area. NULL means: the whole image will be copied.
[in]	Rotation	Image rotation mode to be applied as the area is copied. All the values of the IMG_ROTATE can be used except ROT_AUTO.
[out]	lpImg	Address of a structure to get information about the output image area.
[out]	lplpBitmap	Address of a pointer to the rotated bitmap.

Return values:

RECERR

Note:

If the resulting bitmap is no longer needed the application should call the kRecFree function in order to free its memory.

This function takes into account the Line order (IMG_LINEORDER), the Padding mode (IMG_PADDING) and - with color images - the RGBorder (IMG_RGBORDER) settings of the Engine. These settings should be consistent with the appropriate attributes of the destination bitmap to be created. A preceding call to the kRecSetImgFormat is necessary to change these settings.

The coordinates of the leftmost pixel of the uppermost line of the image is (0,0).

Calling this function with ROT_NO parameter is equivalent to calling the kRecGetImgArea function.

If the source image is B/W, the representation of black pixels in the created bitmap will be one (1), and white is zero (0), i.e. for displaying the image use the NOTSRCCOPY raster operation code.

The specification of this function in C# is:

    RECERR kRecRotateImgArea(int sid, IntPtr hPage, IMAGEINDEX iiImg, RECT pSrcRect, IMG_ROTATE Rotation, out IMG_INFO pImg, out byte[] ppBitmap);
    // or when pSrcRect is NULL in C/C++
    RECERR kRecRotateImgArea(int sid, IntPtr hPage, IMAGEINDEX iiImg, IMG_ROTATE Rotation, out IMG_INFO pImg, out byte[] ppBitmap);
    // or
    RECERR kRecRotateImgArea(int sid, IntPtr hPage, IMAGEINDEX iiImg, RECT pSrcRect, IMG_ROTATE Rotation, out IMG_INFO pImg, out Bitmap bmp);
    // or when pSrcRect is NULL in C/C++
    RECERR kRecRotateImgArea(int sid, IntPtr hPage, IMAGEINDEX iiImg, IMG_ROTATE Rotation, out IMG_INFO pImg, out Bitmap bmp);

RECERR RECAPIKRN kRecSetDropoutColorWeights	(	int	sid,
		int	wred,
		int	wgreen,
		int	wblue
	)

Changing the dropout color weight settings for binarization.

The kRecSetDropoutColorWeights function sets the weights used to calculate the gray-level intensity values from the color components during binarization. In default mode these weights are (77, 150, 29). By setting the weights before preprocessing and/or binarization, objects of a particular color (the drop-out color) can be dropped from the binary image, therefore filled forms can be binarized so that the BW image does not contain the preprinted text. E.g. using (1, 0, 0) as weights, the red preprinted text can be dropped from the white background. In practice the best weights can be calculated by the function kRecDetectDropoutColorWeights. To process drop-out color images the CNV_GLOBAL binarization method is suggested (see kRecSetImgBinarizationMode).

Parameters:

[in]	sid	Settings Collection ID.
[in]	wred	Weight of the red component.
[in]	wgreen	Weight of the green component.
[in]	wblue	Weight of the blue component.

Return values:

RECERR

Note:

The B/W image is created if it does not exist, except with kRecPreprocessImg, which creates it in any case. These settings affect only the primary image conversion (i.e. conversion during loading, see kRecSetImgConvMode) and kRecPreprocessImg. Otherwise, the weights stored in the HPAGE are used for binarization. At loading, these settings are stored in the HPAGE and they can be changed by kRecDetectDropoutColorWeights.

When processing empty forms using a drop-out color, it is recommended to apply auto-deskewing (if desired) when the original image enters into the Engine's responsibility, or at least before the OCR image is created. Typically with forms, auto-deskew relies on finding printed lines or text lines that are usually form labels. Precisely these elements are removed by applying a drop-out color, so calling auto-deskew when the OCR image is already created is liable to fail. A possible workaround may be the following:

Set drop-out color weights to default (77,150,29).
Detect skew (kRecDetectImgSkew)
Set drop-out color weights
Set slope and rotation (kRecSetImgDeskew, kRecSetImgSlope, kRecSetImgRotation)
Pre-process the image

This function sets the settings Kernel.Img.DropoutColor.Blue and ...Green and ...Red. These settings can be retrieved by kRecGetDropoutColorWeights.

The specification of this function in C# is:

 RECERR kRecSetDropoutColorWeights(int sid, int wred, int wgreen, int wblue);

RECERR RECAPIKRN kRecSetFaxCorrection	(	int	sid,
		INTBOOL	corr
	)

Changing the fax correction setting.

This function changes the setting Kernel.Img.FaxCorrectionEnabled, which determines whether the fax correction operation is enabled during preprocessing (PID_IMGPREPROCESS) or not.

Parameters:

[in]	sid	Settings Collection ID.
[in]	corr	If this is TRUE, the fax correction is enabled.

Return values:

RECERR

Note:

If fax correction is enabled (this is the default), the resolution of B/W images with an approximate resolution of 200 x 100 dpi is doubled in the y direction (vertically). The result of this process appears on II_CURRENT (thus also on II_BW and II_OCR) images. This is in contrast to the resolution enhancement performed during 3D deskew, which is applied to both the x and y directions.

This function sets the setting Kernel.Img.FaxCorrectionEnabled. This setting can be retrieved by kRecGetFaxCorrection.

The specification of this function in C# is:

 RECERR kRecSetFaxCorrection(int sid, bool corr);

RECERR RECAPIKRN kRecSetImgBinarizationMode	(	int	sid,
		IMG_CONVERSION	BWConversion
	)

Setting secondary image conversion mode.

The kRecSetImgBinarizationMode function specifies which Image conversion mode is used during an implicit secondary image conversion step. This step is performed automatically when the application calls a KernelAPI API function whose operation requires the II_BW image, but it does not exist. This setting influences how a non-B/W image stored in the Engine is converted to a B/W one.

Parameters:

[in]	sid	Settings Collection ID.
[in]	BWConversion	Secondary image conversion mode to be set. Valid values are: CNV_AUTO, CNV_SET and CNV_GLOBAL. If another one has been specified, the function returns with API_PARAMETER_ERR.

Return values:

RECERR

Note:

Note that both the kRecSetImgConvMode and the kRecSetImgBinarizationMode functions specify Image conversion modes.

The kRecSetImgConvMode specifies the mode to be applied during the PID_IMGINPUT process (primary image conversion). The result of this process is an image under the authority of the Engine. Depending on the original image source AND the Primary image conversion mode setting (specified with kRecSetImgConvMode), the created image is a B/W, gray-scale or 24-bit color one.

On the other hand, a secondary image conversion with BWConversion mode might be performed on existing images. In this case a second, B/W image is created and stored in the page on index II_BW. This step is called either directly (from within the kRecConvertImg2BW function) or implicitly, as described above. E.g. when the kRecRecognize function has been called for a non-B/W image, an implicit secondary image conversion is performed automatically. The kRecRecognize function may implicitly include the conversion of the image, if necessary. A previous kRecSetImgBinarizationMode call allows you to specify how this implicit conversion is performed.

If this function is not called, the default value of CNV_AUTO is applied.

This function toggles the setting Kernel.Img.Binarization.SecondaryMode. This setting can be retrieved by kRecGetImgBinarizationMode.

B/W images also undergo their own implicit secondary image conversion during pre-process or the first time when the II_BW image is required. This conversion applies a despeckle operation, so this setting is not applied to them.

The specification of this function in C# is:

 RECERR kRecSetImgBinarizationMode(int sid, IMG_CONVERSION BWConversion);

RECERR RECAPIKRN kRecSetImgBrightness	(	int	sid,
		int	Brightness
	)

Setting brightness.

The kRecSetImgBrightness function fine-tunes the threshold calculation in the automatic adaptive image conversion mode (i.e. when CNV_AUTO has been specified). This influences the brightness/darkness of the resulting B/W image during both the primary and the secondary image conversion.

Parameters:

[in]	sid	Settings Collection ID.
[in]	Brightness	Brightness control of the automatic image conversion algorithm. The value range is between zero (0) and 100. A value of 0 tunes the conversion to give a lighter image, while a value of 100 results in a darker image. The default value is 50.

Return values:

RECERR

Note:

This function influences both the primary and the secondary image conversions. It has no effect if other than CNV_AUTO image conversion mode has been specified.

This function sets the setting Kernel.Img.Binarization.Brightness. This setting can be retrieved by kRecGetImgBrightness.

The specification of this function in C# is:

 RECERR kRecSetImgBrightness(int sid, int Brightness);

RECERR RECAPIKRN kRecSetImgConvMode	(	int	sid,
		IMG_CONVERSION	Conversion
	)

Setting the primary image conversion mode.

The kRecSetImgConvMode function specifies which Image conversion mode is used during the primary image conversion step. While loading an image to the Engine's authority (PID_IMGINPUT process), an image conversion is also performed according to the current image conversion mode setting. The setting specified here influences what kind of image will be created in the Engine's memory.

Parameters:

[in]	sid	Settings Collection ID.
[in]	Conversion	Primary image conversion mode to be set. Possible values are: CNV_AUTO, CNV_SET, CNV_NO, CNV_GLOBAL and CNV_GRAY.

Return values:

RECERR

Note:

The following situations can occur here, depending on the setting specified:

B/W, Gray-scale or 24-bit color image created without any conversion,
B/W image created, converted from gray-scale image source,
B/W image created, converted from 24-bit color image source or
Gray-scale image created, converted from 24-bit color image source. See IMG_CONVERSION.

If this function is not called, the default value of this setting is CNV_NO.

This function toggles the setting Kernel.Img.Binarization.PrimaryMode. This setting can be retrieved by kRecGetImgConvMode.

The specification of this function in C# is:

 RECERR kRecSetImgConvMode(int sid, IMG_CONVERSION Conversion);

RECERR RECAPIKRN kRecSetImgDeskew	(	int	sid,
		IMG_DESKEW	_ImgDeskew
	)

Setting deskew mode.

The kRecSetImgDeskew function specifies which Image deskewing mode is used during a forthcoming PID_IMGPREPROCESS process. Deskewing mode can be automatic, switched off or programmable.

Parameters:

[in]	sid	Settings Collection ID.
[in]	_ImgDeskew	Select deskewing mode.

Return values:

RECERR

Note:

This function toggles the setting Kernel.Img.Deskew.Mode. This setting can be retrieved by kRecGetImgDeskew.

The specification of this function in C# is:

 RECERR kRecSetImgDeskew(int sid, IMG_DESKEW ImgDeskew);

RECERR RECAPIKRN kRecSetImgDespeckleMode	(	int	sid,
		INTBOOL	bMode
	)

Setting despeckle mode.

The kRecSetImgDespeckleMode function specifies the Engine's Image despeckle mode setting, i.e. whether the adaptive noise removal algorithm is to be activated during implicit primary and secondary image conversion when the current image (II_CURRENT) is a B/W one. The noise removal algorithm runs only on B/W images with a resolution of 180 dpi or higher. This setting might influence the recognition accuracy.

Parameters:

[in]	sid	Settings Collection ID.
[in]	bMode	Image despeckle mode to be set.

Return values:

RECERR

Note:

When this setting is enabled, B/W images with a resolution above 180 dpi automatically undergo an implicit secondary image conversion whenever the application calls a KernelAPI API function whose operation requires a B/W or despeckled image, e.g. the kRecLocateZones, the kRecPreprocessImg or the kRecRecognize functions.

Grayscale or color images undergo their own implicit secondary image conversion during pre-process or the first time when the II_BW image is required. When this setting is enabled, this conversion performs an adaptive image smoothing algorithm before the binarization.

If this function is not called to specify the Image despeckle mode setting, by default this setting is enabled.

Immediate despeckling of a B/W image in the Engine's memory space (regardless of its resolution) is available by calling kRecDespeckleImg. The despeckled image replaces the original one and is available to the application. Note that kRecDespeckleImg applies despeckle on the II_CURRENT image while kRecPreprocessImg and implicit secondary image conversion applies despeckle on the II_BW image.

This function sets the setting Kernel.Img.DespeckleMode. This setting can be retrieved by kRecGetImgDespeckleMode.

Scanners often have the possibility of specifying whether the type of the document is 'text', 'photo' or 'text/photo' (mixed). When text/photo or photo is selected (and black-and-white scanning is chosen) the scanners apply a halftone (dithering, error diffusion) algorithm to simulate gray levels. In this case the scanned image contains a lot of noise and a special despeckle algorithm is required to pre-process it before OCR. By default despeckle detects whether the image has been scanned in halftone mode and applies halftone removal if so. The halftone detection and removal can be switched on or off by Kernel.Img.Despeckle.Halftone setting. The default value of this setting is -1, which means that the current pre-process trade-off (Settings of the Recognition Module Kernel.OcrMgr.TradeOff.Preproc) determines whether halftone detection and removal are applied or not: not applied if trade-off is TO_FAST, and applied otherwise. Set this setting to 0 if you are sure that your image does not contain this type of noise and you want to switch these algorithms off. Set this setting to 1 if your image might contain this type of noise and you want to switch these algorithms on independently of the current trade-off. The halftone detection and removal algorithms are not applied if the image resolution is less than 180 dpi. After pre-process, you can ask whether the image contains halftone noise by calling kRecGetPreprocessInfo.

Barcode specific notes: Despeckle (particularly halftone removal) may remove or deteriorate the thin lines of barcodes, especially if the resolution of the image is less than 300 dpi. If you want to recognize barcodes, check the recognition accuracy on your images using the different despeckle settings in order to select the best one.

The specification of this function in C# is:

 RECERR kRecSetImgDespeckleMode(int sid, bool bMode);

RECERR RECAPIKRN kRecSetImgDownsample	(	int	sid,
		INTBOOL	downsample
	)

Changing the view downsample setting.

This function changes the setting Kernel.Img.ViewDownsample, which determines whether the current image (II_CURRENT) is created in the same resolution as the original (II_ORIGINAL) one or in a resolution reduced to 100-150 DPI (depends on the original resolution) while running kRecPreprocessImg. For more information about this setting see Settings of the Image Handling Module. For information about the lifetime of the current image see IMAGEINDEX.

Parameters:

[in]	sid	Settings Collection ID.
[in]	downsample	If this is `TRUE`, the view image is created with reduced resolution. Its default is `FALSE`.

Return values:

RECERR

Note:

This function sets the setting Kernel.Img.ViewDownsample. This setting can be retrieved by kRecGetImgDownsample.

The specification of this function in C# is:

 RECERR kRecSetImgDownsample(int sid, bool downsample);

RECERR RECAPIKRN kRecSetImgFlags	(	HPAGE	hPage,
		IMG_FLAGS	Flag,
		INTBOOL	bValue
	)

Setting the image flags.

The kRecSetImgFlags function sets the specified flag of the given HPAGE.

Parameters:

[in]	hPage	Handle of the page.
[in]	Flag	The flag to set. See: IMG_FLAGS.
[in]	bValue	The new value of the flag.

RECERR RECAPIKRN kRecSetImgFormat	(	int	sid,
		IMG_LINEORDER	lineord,
		IMG_PADDING	padding,
		IMG_RGBORDER	ord
	)

Setting image format.

The kRecSetImgFormat function specifies the line order, the padding mode and (in the case of a 24-bit color image) the order of the composite color components of the images in the application's authority. The settings of this function affect the following API functions: kRecGetImgArea, kRecPutImgArea, kRecRotateImgArea, kRecReadImg, kRecWriteImg and the kRecLoadImgM functions.

Parameters:

[in]	sid	Settings Collection ID.
[in]	lineord	Line order selection. Possible values are: TOP_DOWN, BOTTOM_UP. This parameter is not considered during kRecReadImg and kRecWriteImg, because they work only on one line at a time.
[in]	padding	Padding the scan lines to byte, word or double word boundaries. The values of this parameter therefore can be PAD_BYTEBOUNDARY, PAD_WORDBOUNDARY or PAD_DWORDBOUNDARY. This parameter is not considered during kRecReadImg and kRecWriteImg, because they work only on one line at a time.
[in]	ord	Order of the composite color components. Possible values are: COLOR_RGB or COLOR_BGR.

Return values:

RECERR

Note:

The Padding mode setting is taken into account only in conjunction with exporting functions, i.e with kRecGetImgArea and kRecRotateImgArea.

The default values are:

lineord = TOP_DOWN
padding = PAD_WORDBOUNDARY
ord = COLOR_RGB. If the application is going to create a Windows bitmap, these default values are correct (i.e. there is no need to call this function at all).

If you want to create a Windows DIB (device-independent bitmap), you should set the image format as follows:

lineord = BOTTOM_UP
padding = PAD_DWORDBOUNDARY
ord = COLOR_BGR.

This function toggles the settings Kernel.Img.LineOrder and ...Padding and ...RGBOrder. These settings can be retrieved by kRecGetImgFormat.

The specification of this function in C# is:

 RECERR kRecSetImgFormat(int sid, IMG_LINEORDER lineord, IMG_PADDING padding, IMG_RGBORDER ord);

RECERR RECAPIKRN kRecSetImgInvert	(	int	sid,
		IMG_INVERT	ImgInvert
	)

Setting inversion mode.

The kRecSetImgInvert function specifies which Image inversion mode is used during the forthcoming PID_IMGPREPROCESS processes. The Image inversion mode can be either automatic, switched on or switched off (white-on-black to black-on-white).

Parameters:

[in]	sid	Settings Collection ID.
[in]	ImgInvert	Image inversion mode to be set. Possible values are: INV_NO, INV_YES, INV_AUTO.

Return values:

RECERR

Note:

This function toggles the setting Kernel.Img.Invert. This setting can be retrieved by kRecGetImgInvert.

The specification of this function in C# is:

 RECERR kRecSetImgInvert(int sid, IMG_INVERT ImgInvert);

RECERR RECAPIKRN kRecSetImgPalette	(	HPAGE	hPage,
		const BYTE *	pPal
	)

Setting palette of the image.

This function sets the palette of the current (II_CURRENT) image of the given page.

Parameters:

[in]	hPage	Handle of the page containing the image.
[in]	pPal	Array of the palette to be set. See notes.

Return values:

RECERR

Note:

Only the 8-bit palette-color images are supported, so the size of the palette is always 3*256 bytes. The order of the composite color objects in the palette is always red, green, blue. If the number of bits per pixel of the image is not 8 the function returns API_PARAMETER_ERR.

The specification of this function in C# is:

 RECERR kRecSetImgPalette(IntPtr hPage, byte[] pPal);

RECERR RECAPIKRN kRecSetImgResolEnhancement	(	int	sid,
		IMG_RESENH	res
	)

Setting resolution enhancement mode.

The kRecSetImgResolEnhancement function specifies the Image resolution enhancement mode. This setting is applied only to non-B/W and non palette color images stored in the Engine's memory space. The value specifies whether the image resolution enhancement is to be activated during the secondary image conversion, i.e. during image pre-processing, auto-zoning or recognition. The resolution enhancement algorithm results in a B/W image whose resolution is higher than the resolution of the original image. This setting might influence recognition accuracy.

Parameters:

[in]	sid	Settings Collection ID.
[in]	res	The Image resolution enhancement value to be set.

Return values:

RECERR

Note:

When the Image resolution enhancement value RE_YES is set, all non-B/W and non palette color images undergoing an implicit secondary image conversion to B/W also have their resolution increased (see IMG_RESENH), regardless of their original resolution. This is done on the basis of information taken from the extra pixel depth in the grayscale and color images. These secondary image conversions occur whenever the application calls a KernelAPI API function whose operation requires a B/W image, e.g. the kRecLocateZones, the kRecPreprocessImg or the kRecRecognize functions.

If this function is not called to specify the Image resolution enhancement mode setting, by default RE_AUTO is applied.

This function toggles the setting Kernel.Img.ResolutionEnhancement. This setting can be retrieved by kRecGetImgResolEnhancement.

The specification of this function in C# is:

 RECERR kRecSetImgResolEnhancement(int sid, IMG_RESENH res);

RECERR RECAPIKRN kRecSetImgResolution	(	HPAGE	hPage,
		SIZE	DPI
	)

Changing the resolution of an image.

This function sets the resolution of the current (II_CURRENT) image of the given page.

Parameters:

[in]	hPage	Handle of the page containing the image.
[in]	DPI	The new horizontal and vertical resolution (Dots Per Inch) of the current image.

Return values:

RECERR

Note:

This function clears the IMG_FLAGS_NORESOLUTION flag (IMG_FLAGS) and modifies the resolution of the II_ORIGINAL, II_BW, II_OCR and II_THUMBNAIL images too.

The specification of this function in C# is:

 RECERR kRecSetImgResolution(IntPtr hPage, SIZE DPI);

RECERR RECAPIKRN kRecSetImgRotation	(	int	sid,
		IMG_ROTATE	imgRotate
	)

Setting rotation mode.

The kRecSetImgRotation function specifies which Image rotation mode is used during a forthcoming PID_IMGPREPROCESS process. The Image rotation mode can be automatic, switched off or programmable.

Parameters:

[in]	sid	Settings Collection ID.
[in]	imgRotate	Image rotation mode to be set. Possible values are: ROT_AUTO, ROT_NO, ROT_RIGHT, ROT_DOWN, ROT_LEFT.

Return values:

RECERR

Note:

This function toggles the setting Kernel.Img.Rotation. This setting can be retrieved by kRecGetImgRotation.

The specification of this function in C# is:

 RECERR kRecSetImgRotation(int sid, IMG_ROTATE ImgRotate);

RECERR RECAPIKRN kRecSetImgSlope	(	int	sid,
		int	Slope
	)

Setting the slope.

The kRecSetImgSlope function specifies the value of the skew slope. This value is used during the PID_IMGPREPROCESS process when the Image deskewing mode is set to DSK_SET.

Parameters:

[in]	sid	Settings Collection ID.
[in]	Slope	Slope value for deskewing. The value given here is the number of pixels of vertical ascent on 1000 horizontal pixels i.e. the tangent of the deskew angle multiplied by 1000.

Return values:

RECERR

Note:

Note that to detect the skew of an image containing machine printed text, the application should call the kRecDetectImgSkew function.

For information about limits of page angle using deskew operations see Notes on Deskew.

This function toggles the setting Kernel.Img.Deskew.Slope. This setting can be retrieved by kRecGetImgSlope.

The specification of this function in C# is:

 RECERR kRecSetImgSlope(int sid, int Slope);

RECERR RECAPIKRN kRecSetImgStretchMode	(	int	sid,
		IMG_STRETCHMODE	ImgStretchMode
	)

Setting stretching mode.

The kRecSetImgStretchMode function specifies which Image stretching mode is used while executing the kRecGetImgArea or kRecPutImgArea functions.

Parameters:

[in]	sid	Settings Collection ID.
[in]	ImgStretchMode	Image stretching mode to be applied. Possible values are: STRETCH_DELETE, STRETCH_OR, STRETCH_AND and STRETCH_AVG.

Return values:

RECERR

Note:

If this function is not called by the integrating application to specify the Image stretching mode, the default value of this setting, STRETCH_DELETE are applied.

This function toggles the setting Kernel.Img.StretchMode. This setting can be retrieved by kRecGetImgStretchMode.

The specification of this function in C# is:

 RECERR kRecSetImgStretchMode(int sid, IMG_STRETCHMODE ImgStretchMode);

RECERR RECAPIKRN kRecSetImgThreshold	(	int	sid,
		int	Threshold
	)

Setting the binarization threshold.

The kRecSetImgThreshold function specifies the threshold parameter of an image conversion to a B/W image. This parameter has an effect only when the CNV_SET image conversion mode has been set. This setting is used during both the primary and the secondary image conversion.

Parameters:

[in]	sid	Settings Collection ID.
[in]	Threshold	The image conversion threshold value to be set. It ranges between zero (0) and 255, default: 128.

Return values:

RECERR

Note:

This setting is applied to both the primary and the secondary image conversions.

The function has no effect if other than CNV_SET image conversion mode has been specified.

This function sets the setting Kernel.Img.Binarization.Threshold. This setting can be retrieved by kRecGetImgThreshold.

The specification of this function in C# is:

 RECERR kRecSetImgThreshold(int sid, int Threshold);

RECERR RECAPIKRN kRecSetPreserveOriginalImg	(	int	sid,
		INTBOOL	preserve
	)

Changing the keep original image setting.

This function changes the setting Kernel.Img.KeepOriginalImage, which determines whether the original image (II_ORIGINAL) is kept after the preprocessing step or not. The original image is used only as an input image of the preprocessing step PID_IMGPREPROCESS, thus after preprocessing it can be deleted for saving memory. For more information about this setting see Settings of the Image Handling Module. For information about the lifetime of the thumbnail image see IMAGEINDEX.

Parameters:

[in]	sid	Settings Collection ID.
[in]	preserve	If this is TRUE, the original image is kept.

Return values:

RECERR

Note:

This function toggles the setting Kernel.Img.KeepOriginalImage. This setting can be retrieved by kRecGetPreserveOriginalImg.

The specification of this function in C# is:

 RECERR kRecSetPreserveOriginalImg(int sid, bool preserve);

RECERR RECAPIKRN kRecSetRetainColor	(	int	sid,
		RETAINCOLOR	RetainColor
	)

Changing retain color setting.

This function changes the retain color setting.

Parameters:

[in]	sid	Settings Collection ID.
[in]	RetainColor	The retain color value to be set.

Return values:

RECERR

Note:

This function sets the setting Kernel.OcrMgr.RetainColor. This setting can be retrieved by kRecGetRetainColor.

The specification of this function in C# is:

 RECERR kRecSetRetainColor(int sid, RETAINCOLOR RetainColor);

RECERR RECAPIKRN kRecSetThumbnailImgInfo	(	int	sid,
		const IMG_INFO *	pThumbnail,
		REC_COLOR	color
	)

Changing the thumbnail image info settings.

This function changes the settings under the node Kernel.Img.Thumbnail, which determines the image info used at the creation of the thumbnail image. For more information about this setting see Settings of the Image Handling Module. For information about the lifetime of the thumbnail image see IMAGEINDEX.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pThumbnail	This is the image information to be set. Only its fields IMG_INFO::BitsPerPixel and IMG_INFO::Size are considered. The `BitsPerPixel` can be 1, 8 or 24. The `Size` is the width and height of the thumbnail image. If either the horizontal or vertical size is set to zero, its value is automatically determined so as to preserve the aspect ratio of the source page. If both size values are given, the aspect ratio is still preserved, with the thumbnail color placed in the unused space (see II_THUMBNAIL).
[in]	color	This thumbnail color is placed in the background if the thumbnail image does not cover the whole thumbnail area. See II_THUMBNAIL.

Return values:

RECERR

Note:

This function toggles the settings Kernel.Img.Thumbnail.BitsPerPixel, ...Color, ...Size.X and ...Size.Y. These settings can be retrieved by kRecGetThumbnailImgInfo.

The specification of this function in C# is:

 RECERR kRecSetThumbnailImgInfo(int sid, [In] IMG_INFO pThumbnail, uint color);

RECERR RECAPIKRN kRecStartReadImg	(	int	sid,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		LPCRECT	pRect,
		IMG_ROTATE	ImgRotation,
		LPWORD	pBytes
	)

Starting to read an image line-by-line.

The kRecStartReadImg function initiates the line-by-line reading process to export an image stored in the image management module.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page which contains the image to be processed.
[in]	iiImg	Index to the image in the page.
[in]	pRect	Pointer to the structure defining the requested area of the image or NULL for the entire image.
[in]	ImgRotation	Orientation of the lines during reading. Possible values are all the values of the type IMG_ROTATE except ROT_AUTO.
[out]	pBytes	Pointer to a variable to hold the length of the lines to be read in bytes.

Return values:

RECERR

Note:: Using different Settings Collections you can open several images at the same time by this function.; This function is the first in a series of calls to read an image line-by-line. It should be followed by calls to kRecReadImg, which is usually called repeatedly. The kRecStopReadImg function should be used to signal the completion of this reading process. These functions should be used instead of kRecGetImgArea, if the full image is too large to store in the application's memory.; Three analogous functions kRecStartWriteImg, kRecWriteImg and kRecStopWriteImg perform image import.; With 24-bit color images, this function takes into account the RGBorder (IMG_RGBORDER) setting of the Engine. This setting defines how the destination bitmap's color representation is created. To change this setting, a preceding call to the kRecSetImgFormat function is necessary.; This function is insecure for managed code. In C# use the more advanced kRecGetImgArea function.

RECERR RECAPIKRN kRecStartWriteImg	(	int	sid,
		LPCIMG_INFO	pImg
	)

Starting to write an image line-by-line.

The kRecStartWriteImg function initiates a line-by-line bitmap transfer for direct raw image download from the application's image source. The kRecStartWriteImg function sends pertinent information about the image to the Engine and prepares for creating a new HPAGE.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pImg	Pointer to a filled IMG_INFO structure describing the image to be transferred.

Return values:

RECERR

Note:: Using different Settings Collections you can open several images at the same time by this function.; This function is the first in a series of calls to send an image in lines to the Engine. It should be followed by calls to kRecWriteImg, which is usually called repeatedly to send successive lines of the image to an image in the image management module. After the full image has been sent, the clean-up function kRecStopWriteImg needs to be called to complete the process. kRecStopWriteImg creates the mentioned new HPAGE and returns with it.; Use these functions instead of the direct method kRecLoadImgM when the image is too large to place in memory.; There is no need to specify the BytesPerLine field of the passed image info and if the number of lines is not known in advance or it is uncertain, zero (0) can be used for the vertical size.; Three analogous functions kRecStartReadImg, kRecReadImg and kRecStopReadImg perform image export.; With 24-bit color images, this function takes into account the RGBorder (IMG_RGBORDER) setting of the Engine. This setting describes the source bitmap's color representation. To change this setting, a preceding call to the kRecSetImgFormat function is necessary.; This function is insecure for managed code. In C# use the more advanced kRecPutImgArea or kRecCreateImg functions.

RECERR RECAPIKRN kRecStopReadImg ( int sid )

Stopping to read an image line-by-line.

The kRecStopReadImg function stops the line-by-line image exporting process started and performed with the functions kRecStartReadImg and kRecReadImg.

Parameters:

[in] sid Settings Collection ID.

Return values:

RECERR

Note:: Typically this function should be called when no more lines remain in the defined image area. This is signaled by a returned value of IMG_NOMORE_WARN from a kRecReadImg call.; This function is insecure for managed code. In C# use the more advanced kRecGetImgArea function.

RECERR RECAPIKRN kRecStopWriteImg	(	int	sid,
		HPAGE *	phPage
	)

Stopping the writing of an image line-by-line.

The kRecStopWriteImg function completes the image download operation started with kRecStartWriteImg and kRecWriteImg calls. It stores the downloaded image in a newly created HPAGE.

Parameters:

[in]	sid	Settings Collection ID.
[out]	phPage	Address of a variable to store the handle of the created page.

Return values:

RECERR

Note:: This function is insecure for managed code. In C# use the more advanced kRecPutImgArea or kRecCreateImg functions.

RECERR RECAPIKRN kRecTransformCoordinates	(	HPAGE	hPage,
		IMAGEINDEX	iiDst,
		IMAGEINDEX	iiSrc,
		int	nP,
		LPPOINT	pPoint
	)

Transforming coordinates between images of a page.

This function retrieves the coordinates of the destination image according to those of the source image. The transformation used is able to convert the coordinate system of the source image into that of the destination image of the same page.

Parameters:

[in]	hPage	Handle of the page.
[in]	iiDst	Index of the destination image.
[in]	iiSrc	Index of the source image.
[in]	nP	Number of points in the buffer.
[in,out]	pPoint	Buffer of the points to be converted. The result will rewrite the coordinates in place.

Return values:

RECERR

Note:

The specification of this function in C# is:

 RECERR kRecTransformCoordinates(IntPtr hPage, IMAGEINDEX iiDst, IMAGEINDEX iiSrc, POINT[] pPoint);

RECERR RECAPIKRN kRecTransformImg	(	int	sid,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		LPCRECT	pSrcRect,
		LPCSIZE	pDstSize,
		WORD	BitsPerPixel,
		HPAGE *	phPageOut
	)

Transforming an image.

The kRecTransformImg function creates a new image from an existing one. During this transformation, a rectangular area of the selected image of the input page is copied to the original image (II_ORIGINAL) of the output page. This area is compressed or stretched according to the ratio of the source rectangular area and the destination size.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the input page.
[in]	iiImg	Index of the input image whose area should be transformed.
[in]	pSrcRect	Rectangular area of the image to be transformed. NULL means: the whole image is transformed.
[in]	pDstSize	Size of the image to be created in pixels. A value of NULL here means that the destination size is equal to the size of the source rectangle.
[in]	BitsPerPixel	Type of the image (number of bits per pixel). Possible values are: 1, 4, 8, 24 for B/W, 4-bit gray-scale, 8-bit gray-scale and 24-bit color image, respectively.
[out]	phPageOut	Pointer of a variable to store the handle of the output page to be created.

Return values:

RECERR

Note:

To create a B/W image from the current one without changing the size of the image, call the function kRecConvertImg2BW instead.

If the input image is a B/W one and the output image is specified as an 8-bit gray-scale one, and the area should be compressed, a scale-to-gray image conversion will be applied.

The resolution of the target image is calculated according to the compression/stretching ratio.

When the target page is no longer needed, remove it from the image management module by invoking the kRecFreeImg function.

The specification of this function in C# is:

    RECERR kRecTransformImg(int sid, IntPtr hPage, IMAGEINDEX iiImg, RECT pSrcRect, SIZE pDstSize, ushort BitsPerPixel, out IntPtr phPageOut);
    // or when pSrcRect is NULL in C/C++
    RECERR kRecTransformImg(int sid, IntPtr hPage, IMAGEINDEX iiImg, SIZE pDstSize, ushort BitsPerPixel, out IntPtr phPageOut);
    // or when pDstSize is NULL in C/C++
    RECERR kRecTransformImg(int sid, IntPtr hPage, IMAGEINDEX iiImg, RECT pSrcRect, ushort BitsPerPixel, out IntPtr phPageOut);
    // or when both are NULL
    RECERR kRecTransformImg(int sid, IntPtr hPage, IMAGEINDEX iiImg, ushort BitsPerPixel, out IntPtr phPageOut);

RECERR RECAPIKRN kRecTransformImgByMatrix	(	int	sid,
		HPAGE	hPage,
		const SIZE *	newsize,
		const double *	matrix
	)

Performing geometrical transformation determined by a matrix.

The kRecTransformImgByMatrix function performs a geometrical transformation on the II_CURRENT image of the given page. If there are BW (II_BW) and thumbnail (II_THUMBNAIL) images they are regenerated from the transformed current image.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the page containing the image(s) to be transformed.
[in]	newsize	The new size of the current image. The size is not changed if it is `NULL`.
[in]	matrix	The transformation matrix containing 8 elements.

Return values:

RECERR

Note:

The matrix is the first 8 elements of a 3x3 M matrix in the following order: M[0][0], M[0][1], M[0][2], M[1][0], M[1][1], M[1][2], M[2][0], M[2][1]. The last (M[2][2]) element is always supposed to be 1.0. The function uses the following algorithm,
(x0,y0) is the original point and (x2,y2) is the transformed point, [x, y, z] is a column vector:

    [x1, y1, z1]    =   M * [x0,y0,1]
    x2              =   x1 / z1
    y2              =   y1 / z1

Using this function rotation, translation, enlargement, reducing, shearing, perspective transformations and their combinations can be performed.

Rotation by x degrees: cos(x),sin(x),0,-sin(x),cos(x),0,0,0
Translation by (x,y): 1,0,x,0,1,y,0,0
Scaling by scalefactor s: s,0,0,0,s,0,0,0
Note:
Applying 2 transformations on the image (T2 given by matrix M2 after T1 given by matrix M1) can be performed in one step calculating and passing the combined matrix M2 * M1. If the M[2][2] element of the combined matrix is not 1.0 the matrix should be normalized (i.e. its elements should be divided by M[2][2]).
The specification of this function in C# is:
```
    RECERR kRecTransformImgByMatrix(int sid, IntPtr hPage, SIZE newsize, double[] pMatrix);
    // or when newsize is NULL in C/C++
    RECERR kRecTransformImgByMatrix(int sid, IntPtr hPage, double[] pMatrix);
```

RECERR RECAPIKRN kRecTransformImgByPoints	(	int	sid,
		HPAGE	hPage,
		const SIZE *	newsize,
		const POINT *	pOriginal,
		const POINT *	pTransformed,
		int	nPoints
	)

Performing geometrical transformation determined by points.

The kRecTransformImgByPoints function performs a geometrical transformation on the II_CURRENT image of the given page. It creates a transformation matrix which transforms the pOriginal points to pTransformed, and applies it to the image. If there are BW (II_BW) and thumbnail (II_THUMBNAIL) images they are regenerated from the transformed current image.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of page containing the image(s) to be transformed.
[in]	newsize	The new size of the current image. The size is not changed if it is NULL.
[in]	pOriginal	Array of original points.
[in]	pTransformed	Array of transformed points.
[in]	nPoints	The number of given points in `pOriginal` and `pTransformed` array.

Return values:

RECERR

Note:

- The transformation is a translation if nPoints == 1,

it is a similarity transformation if nPoints == 2,
it is a similarity transformation combined with a shearing if nPoints == 3, and
it is a perspective transformation if nPoints >= 4.
If nPoints > 4 the transformation does not exactly transform all original points to transformed ones.

The specification of this function in C# is:

    RECERR kRecTransformImgByPoints(int sid, IntPtr hPage, SIZE newsize, POINT[] pOriginal, POINT[] pTransformed);
    // or when newsize is NULL in C/C++
    RECERR kRecTransformImgByPoints(int sid, IntPtr hPage, POINT[] pOriginal, POINT[] pTransformed);

RECERR RECAPIKRN kRecTransformImgPalette	(	int	sid,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		LPCRECT	pSrcRect,
		LPCSIZE	pDstSize,
		HPAGE *	phPageOut
	)

Transforming palette-color images.

The kRecTransformImgPalette function creates a new palette-color image from an existing image. During this transformation, a rectangular area of the selected image of the input page is copied to the original image (II_ORIGINAL) of the output page. This area is compressed or stretched according to the ratio of the source rectangular area's size and that of the destination image.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Handle of the source page.
[in]	iiImg	Index of the image in the source page to be transformed.
[in]	pSrcRect	Rectangular area of the selected image to be transformed. NULL means the whole image is transformed.
[in]	pDstSize	Size of the output image to be created in pixels. A value of NULL here means that the destination size is equal to the size of the source rectangle.
[out]	phPageOut	Pointer of a variable to store the handle of the output page.

Return values:

RECERR

Note:

To create images other than color-palette ones, use the function kRecTransformImg.

The resolution of the output image is calculated according to the compression/stretching ratio.

When the output page is no longer needed it has to be removed from the image management module by invoking the kRecFreeImg function.

The specification of this function in C# is:

    RECERR kRecTransformImgPalette(int sid, IntPtr hPage, IMAGEINDEX iiImg, RECT pSrcRect, SIZE pDstSize, out IntPtr phPageOut);
    // or when  pSrcRect is NULL in C/C++
    RECERR kRecTransformImgPalette(int sid, IntPtr hPage, IMAGEINDEX iiImg, SIZE pDstSize, out IntPtr phPageOut);
    // or when pDstSize is NULL in C/C++
    RECERR kRecTransformImgPalette(int sid, IntPtr hPage, IMAGEINDEX iiImg, RECT pSrcRect, out IntPtr phPageOut);
    // or when both are NULL
    RECERR kRecTransformImgPalette(int sid, IntPtr hPage, IMAGEINDEX iiImg, out IntPtr phPageOut);

RECERR RECAPIKRN kRecWriteImg	(	int	sid,
		const LPBYTE	pBuff
	)

Writing an image line-by-line.

The kRecWriteImg function downloads a line of raw image data from the application's buffer to the Engine. It should be repeatedly called to send successive lines of the image to an image in the image management module.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pBuff	Pointer to a buffer containing the line of image data to be downloaded to the Engine.

Return values:

RECERR

Note:: This function is the second part in a three-part series for downloading lines of image data to the Engine. The first call in the series is kRecStartWriteImg, which prepares the Engine for the incoming image. The kRecStopWriteImg is called after the image has been completely sent to the Engine to perform clean-up. Use these functions instead of the direct method kRecLoadImgM when the image is too large to place in memory.; The line-by-line image transfer must start with the top line of the image and end with the bottom line.; This function is insecure for managed code. In C# use the more advanced kRecPutImgArea or kRecCreateImg functions.

ROT_NO:	LEFT:	RIGHT:	DOWN:
123	369	741	987
456	258	852	654
789	147	963	321

FLIPPED:	LEFT_FLIPPED:	RIGHT_FLIPPED:	DOWN_FLIPPED:
321	147	963	789
654	258	852	456
987	369	741	123

RECERR RECAPIKRN kRecDetectBlankPage	(	int	sid,
		HPAGE	hPage,
		INTBOOL *	pIsBlank
	)

RECERR RECAPIKRN kRecDetectBook	(	int	sid,
		HPAGE	hPage,
		CUT_INFO *	pInfo
	)

RECERR RECAPIKRN kRecDetectDropoutColorWeights	(	int	sid,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		RECT *	pRect,
		int *	pwred,
		int *	pwgreen,
		int *	pwblue
	)

RECERR RECAPIKRN kRecDetectFillingMethod	(	int	sid,
		HPAGE	hPage,
		FILLINGMETHOD *	pocrType
	)

RECERR RECAPIKRN kRecDetectImgSkew	(	int	sid,
		HPAGE	hPage,
		int *	pSlope,
		IMG_ROTATE *	pImgRotate
	)

RECERR RECAPIKRN kRecDropImg	(	HPAGE	hPage,
		IMAGEINDEX	iiImg
	)

RECERR RECAPIKRN kRecFillImgArea	(	int	sid,
		HPAGE	hPage,
		LPCRECT	lpRect,
		REC_COLOR	color,
		FILLAREA_FLAGS	flags
	)

RECERR RECAPIKRN kRecForceDespeckleImg	(	int	sid,
		HPAGE	hPage,
		LPCRECT	pRect,
		DESPECKLE_METHOD	method,
		int	level
	)

RECERR RECAPIKRN kRecGetDropoutColorWeights	(	int	sid,
		int *	pwred,
		int *	pwgreen,
		int *	pwblue
	)

RECERR RECAPIKRN kRecGetFaxCorrection	(	int	sid,
		INTBOOL *	pCorr
	)

RECERR RECAPIKRN kRecGetFrameCount	(	HPAGE	hPage,
		int *	pnFrames
	)

RECERR RECAPIKRN kRecGetFrameInfo	(	HPAGE	hPage,
		IMAGEINDEX	iiImg,
		LPCELL_INFO	pFrame,
		int	nFrame
	)

RECERR RECAPIKRN kRecGetImgArea	(	int	sid,
		HPAGE	hPageIn,
		IMAGEINDEX	iiImg,
		LPCRECT	pSrcRect,
		LPCSIZE	pDstSize,
		LPIMG_INFO	pImg,
		BYTE **	ppBitmap
	)

RECERR RECAPIKRN kRecGetImgAreaEx	(	int	sid,
		HPAGE	hPageIn,
		IMAGEINDEX	iiImg,
		LPCRECT	pSrcRect,
		LPCSIZE	pDstSize,
		IMG_STRETCHMODE	StretchMode,
		IMG_LINEORDER	LineOrder,
		IMG_RGBORDER	RGBOrder,
		INTBOOL	strict,
		IMG_PADDING	Padding,
		LPIMG_INFO	pImg,
		BYTE **	ppBitmap
	)

RECERR RECAPIKRN kRecGetImgBinarizationMode	(	int	sid,
		LPIMG_CONVERSION	pBWConversion
	)

RECERR RECAPIKRN kRecGetImgBrightness	(	int	sid,
		int *	lpBrightness
	)

RECERR RECAPIKRN kRecGetImgConvMode	(	int	sid,
		IMG_CONVERSION *	pConversion
	)

RECERR RECAPIKRN kRecGetImgDeskew	(	int	sid,
		IMG_DESKEW *	pImgDeskew
	)

RECERR RECAPIKRN kRecGetImgDespeckleMode	(	int	sid,
		LPINTBOOL	lpbMode
	)

Classes

Defines

Typedefs

Enumerations

Functions

REC_COLOR flag values

Flags of rule lines

Detailed Description

Notes on Deskew and Orientation

Operational conditions

Angle limits

Reconstruct algorithm

Arabic cases

Digital camera input

Automatic 3D-deskew

Manual 3D deskew

How to capture good quality images

Inverse text and color lines

Despeckle for halftone images

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

RECERR RECAPIKRN kRecGetImgDownsample	(	int	sid,
		INTBOOL *	pdownsample
	)

RECERR RECAPIKRN kRecGetImgFlags	(	HPAGE	hPage,
		IMG_FLAGS	Flag,
		INTBOOL *	pbValue
	)

RECERR RECAPIKRN kRecGetImgFormat	(	int	sid,
		IMG_LINEORDER *	plineord,
		IMG_PADDING *	ppadding,
		IMG_RGBORDER *	pord
	)

RECERR RECAPIKRN kRecGetImgInfo	(	int	sid,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		LPIMG_INFO	pImg
	)

RECERR RECAPIKRN kRecGetImgInvert	(	int	sid,
		IMG_INVERT *	lpImgInvert
	)

RECERR RECAPIKRN kRecGetImgMetaData	(	HPAGE	hPage,
		HSETTING *	phMetaData
	)

RECERR RECAPIKRN kRecGetImgPalette	(	int	sid,
		HPAGE	hPage,
		IMAGEINDEX	iiImg,
		LPBYTE	pPal
	)

RECERR RECAPIKRN kRecGetImgResolEnhancement	(	int	sid,
		IMG_RESENH *	res
	)

RECERR RECAPIKRN kRecGetImgRotation	(	int	sid,
		IMG_ROTATE *	lpImgRotate
	)

RECERR RECAPIKRN kRecGetImgStretchMode	(	int	sid,
		IMG_STRETCHMODE *	pImgStretchMode
	)