RecAPI
Image Handling Module

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_INFOLPIMG_INFO
 Pointer to a structure IMG_INFO.
typedef const IMG_INFOLPCIMG_INFO
 Const pointer to a structure IMG_INFO.
typedef COMPRESSED_IMG_INFOLPCOMPRESSED_IMG_INFO
 Pointer to a structure COMPRESSED_IMG_INFO.
typedef const COMPRESSED_IMG_INFOLPCCOMPRESSED_IMG_INFO
 Const pointer to a structure COMPRESSED_IMG_INFO.
typedef struct RECPAGESTRUCT * HPAGE
 Handle of a page in memory.
typedef IMG_CONVERSIONLPIMG_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:

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

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):

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:

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:

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

  1. Lighting: Clear, even lighting with good contrast is important (no shaded parts).
  2. Stable camera position: Use a tripod or other steadying device.
  3. Camera axis: As close to perpendicular to the page as possible.
  4. 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.
  5. 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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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]sidSettings Collection ID.
[in]hPageHandle 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]sidSettings Collection ID.
[in]hPageHandle of the page to be processed.
[in]lrMarginLeft and right margin (pixels).
[in]tbMarginTop and bottom margin (pixels).
[in]flagsSet 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]sidSettings Collection ID.
[in]hPageHandle of the page containing the image to be modified.
[in]lpRectPointer 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]sidSettings Collection ID.
[in]hPageHandle of the page to be processed. The II_CURRENT image of this page will be modified.
[in]BitsPerPixelNew value of the bits per pixel. Possible values are: 1, 8, 24.
[in]flagsThe 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]sidSettings Collection ID.
[in]hPageInHandle of the source page.
[in]ConversionImage conversion mode to be applied during the conversion of the image. Possible values are: CNV_AUTO, CNV_SET, CNV_GLOBAL.
[in]BrightnessBrightness 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]ThresholdThreshold 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]resolenhThe resolution enhancement mode to be used during binarization.
[out]phPageOutPointer 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]sidSettings Collection ID.
[in]hPageDstHandle of the page which contains the destination image.
[in]pRectDstCoordinates of the destination rectangular area. NULL means the whole image.
[in]hPageSrcHandle of the page which contains the source image.
[in]pRectSrcCoordinates 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]sidSettings Collection ID.
[in]hPageHandle of the two-part opened book page image.
[out]phPage1Pointer of a variable to store the handle of the left page cut from the book page.
[out]phPage2Pointer of a variable to store the handle of the right page cut from the book page.
[in]pInfoThe 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]sidSettings Collection ID.
[in]sizeXHorizontal size of the image to be created, in pixels.
[in]sizeYVertical size of the image to be created, in pixels.
[in]dpiXHorizontal resolution of the image (Dots Per Inch).
[in]dpiYVertical resolution of the image.
[in]BitsPerPixelBits 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]phPagePointer 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]sidSettings Collection ID.
[in]hPageHandle of a page containing the image(s) to be deskewed.
[in]ImgSlopeInteger 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]sidSettings Collection ID.
[in]hPageHandle 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 kRecForceDespeckleImg.
The specification of this function in C# is:
 RECERR kRecDespeckleImg(int sid, IntPtr hPage); 
RECERR RECAPIKRN kRecDetectBlankPage ( int  sid,
HPAGE  hPage,
INTBOOL *  pIsBlank 
)

Detecting blank pages.

Detects if a given page is a blank page.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page.
[out]pIsBlankPointer to a variable to store the result. It is TRUE, if the image is blank.
Return values:
RECERR
Note:
This function considers a page as blank if there is only some noise on it. It still returns TRUE if the image contains edge noise as a result of scanning. It returns FALSE if it finds some text or graphics on the page.
The specification of this function in C# is:
 RECERR kRecDetectBlankPage(int sid, IntPtr hPage, out bool IsBlank); 
RECERR RECAPIKRN kRecDetectBook ( int  sid,
HPAGE  hPage,
CUT_INFO pInfo 
)

Detecting facing book pages.

This function detects the place where the page image can be cut into two pages. It is useful when scanning two facing pages of a book simultaneously. First time after kRecInit or kRecResetBookSize, it stores the size of the resulting pages in settings. This size can always include both pages.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page.
[out]pInfoPointer of a variable to store the detected cutting information.
Return values:
RECERR
Note:
This function should be called before every kRecCreateBookPages, which performs the cutting on the given HPAGE.
The input HPAGE has to contain horizontal text lines, or it has to be rotated to such position (kRecPreprocessImg, kRecRotateImg).
This function sets the settings Kernel.Img.BookSize.X and Kernel.Img.BookSize.Y.
The specification of this function in C# is:
 RECERR kRecDetectBook(int sid, IntPtr hPage, out CUT_INFO info); 
RECERR RECAPIKRN kRecDetectDropoutColorWeights ( int  sid,
HPAGE  hPage,
IMAGEINDEX  iiImg,
RECT *  pRect,
int *  pwred,
int *  pwgreen,
int *  pwblue 
)

Detecting dropout color weights.

The kRecDetectDropoutColorWeights function calculates the best weights that can be used for drop-out color binarization. This detection operates on the current image (II_CURRENT) of the given HPAGE. Typical filled form documents contain three main colors: background color, preprinted drop-out color, and fill color. The goal of the drop-out color binarization is to create a binary image that does not contain the preprinted texts, lines, etc. You should define a rectangle, as large as possible, that contains the drop-out color and the background color, but should not contain the fill color. The returned weights can be passed to kRecSetDropoutColorWeights function.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page containing the image, on which the detection runs.
[in]iiImgThe index of the image, in which the coordinates of the input rectangle are to be given. Possible values are II_CURRENT and II_BW.
[in,out]pRectThe rectangular area of the image in which the detection runs. If this rectangle is given in the BW image, the output rectangle is converted to the current image. This pointer must not be NULL.
[out]pwredPointer of a variable to store the suggested weight of the red component.
[out]pwgreenPointer of a variable to store the suggested weight of the green component.
[out]pwbluePointer of a variable to store the suggested weight of the blue component.
Return values:
RECERR
Note:
This function only stores the recommended drop-out color weights of the given HPAGE and does not set these values. If you find the recommendations correct, you can set them with kRecSetDropoutColorWeights. Thus the detected values will not be used in primary image conversion and kRecPreprocessImg unless they are set. For more information, see kRecSetDropoutColorWeights.
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:
  1. Set drop-out color weights to default (77,150,29).
  2. Detect skew (kRecDetectImgSkew)
  3. Set drop-out color weights
  4. Set slope and rotation (kRecSetImgDeskew, kRecSetImgSlope, kRecSetImgRotation)
  5. Pre-process the image
The specification of this function in C# is:
 RECERR kRecDetectDropoutColorWeights(int sid, IntPtr hPage, IMAGEINDEX iiImg, [In, Out] ref RECT pRect, out int pwred, out int pwgreen, out int pwblue); 
RECERR RECAPIKRN kRecDetectFillingMethod ( int  sid,
HPAGE  hPage,
FILLINGMETHOD pocrType 
)

Detection of filling method.

This function tries to determine the type of content in the OCR zones of a page. If there is no OCR zone, the function works on user zones. It can identify handprinted, machine printed or dot-matrix printed text (9 and 24 pin) and barcodes. The function only looks into zones with the FM_DEFAULT value in their ZONE::fm field. If an output parameter address is passed the CSDK fills it with one general filling method based on the examined zones of the page. The integrating application can pass this value to the end-user for evaluation or can use it directly. Another use of this function is when it is called with NULL in its output parameter. In this case, the function performs a zone-by-zone analysis (on zones with FM_DEFAULT) and replaces the filling method of each zone with the determined one.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page.
[out]pocrTypeAddress of a variable to get the detected method or NULL.
Return values:
RECERR
Note:
Important details can be found in the section Detection of filling method.
If the zone contains objects from more than one filling method, it is indeterminate which filling method is selected.
To categorize text zones, there must be preferably more than 50 representative characters in the zone: the more characters are in a zone, the more accurate the detection is.
The specification of this function in C# is:
    RECERR kRecDetectFillingMethod(int sid, IntPtr hPage, out FILLINGMETHOD pocrType);
    // or when pocrType is NULL in C/C++
    RECERR kRecDetectFillingMethod(int sid, IntPtr hPage);
RECERR RECAPIKRN kRecDetectImgSkew ( int  sid,
HPAGE  hPage,
int *  pSlope,
IMG_ROTATE pImgRotate 
)

Detecting orientation and skew.

The kRecDetectImgSkew function detects the orientation and the skew of the image.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page which contains the image.
[out]pSlopePointer to a variable to get the slope value.
[out]pImgRotatePointer to a variable to get the orientation of the image.
Return values:
RECERR
Note:
If the current Image rotation mode (kRecSetImgRotation) is
  • ROT_AUTO : this function really provides the detected orientation of the image,
  • otherwise: the current Image rotation mode setting is retrieved.
If the current Image deskewing mode (kRecSetImgDeskew) is
  • DSK_2D: this function really detects the image skew
  • DSK_SET: the current slope value is retrieved (as it was set by the last kRecSetImgSlope call),
  • DSK_NO: the function provides zero (0).
  • DSK_3D: the function provides zero (0).
For information about limits of page angle using deskew operations see Notes on Deskew.
The retrieved slope value (pSlope) is the number of pixels of vertical ascent on 1000 horizontal pixels. That is, the tangent of the deskew angle multiplied by 1000.
The detected skew value can be placed in kRecDeskewImg to immediately perform the specified amount of deskewing on a single image.
The slope value can also be placed in kRecSetImgSlope, which makes it available to kRecSetImgDeskew when DSK_SET is specified. Then all images are deskewed by the given value whenever kRecPreprocessImg is called.
When detecting the image rotation with Image rotation mode setting ROT_AUTO, one of the following values is returned: ROT_NO, ROT_RIGHT, ROT_DOWN, ROT_LEFT. This is the value by which the image should be rotated to reach the orientation which the program considers correct. This value can be placed in the kRecRotateImg function to explicitly perform the image rotation.
The specification of this function in C# is:
 RECERR kRecDetectImgSkew(int sid, IntPtr hPage, out int pSlope, out IMG_ROTATE pImgRotate); 
RECERR RECAPIKRN kRecDropImg ( HPAGE  hPage,
IMAGEINDEX  iiImg 
)

Removing an image from the page.

The kRecDropImg function removes an image from the given page.

Parameters:
[in]hPageHandle of the page.
[in]iiImgIndex of the image to be removed.
Return values:
RECERR
Note:
The current image (II_CURRENT) cannot be dropped.
The specification of this function in C# is:
 RECERR kRecDropImg(IntPtr hPage, IMAGEINDEX iiImg); 
RECERR RECAPIKRN kRecEnhanceWhiteboardImg ( HPAGE  hPage)

Enhancing images taken from whiteboards.

Improving the readability of text and diagrams on whiteboards, when captured by digital camera.

Parameters:
[in]hPageHandle of the page.
Return values:
RECERR
Note:
The function returns an error if the II_CURRENT image is not a 24-bit true-color image.
The function uses Kernel.Img.Whiteboard.Strength setting.
The specification of this function in C# is:
 RECERR kRecEnhanceWhiteboardImg(IntPtr hPage); 
RECERR RECAPIKRN kRecFillImgArea ( int  sid,
HPAGE  hPage,
LPCRECT  lpRect,
REC_COLOR  color,
FILLAREA_FLAGS  flags 
)

Filling image areas with a specified color.

The kRecFillImgArea function fills the image within (or outside) the given rectangle with the specified color.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page containing the image to be modified.
[in]lpRectPointer to a rectangle to be filled in. A NULL value means the entire image.
[in]colorThe area is filled in with this color. The color contains red, green, blue and alpha components. The red, green and blue components are intensity values from 0 to 255. The alpha component defines the opacity: 0 means that the color is totally transparent. The image is not changed if the alpha component is 0.
[in]flagsThe flags determining how the given rectangle is used.
Return values:
RECERR
Note:
The color is converted to the nearest possible value.
This function modifies the II_CURRENT image of the page.
The specification of this function in C# is:
    RECERR kRecFillImgArea(int sid, IntPtr hPage, RECT lpRect, uint color, FILLAREA_FLAGS flags);
    // or when lpRect is NULL in C/C++
    RECERR kRecFillImgArea(int sid, IntPtr hPage, uint color, FILLAREA_FLAGS flags);
RECERR RECAPIKRN kRecForceDespeckleImg ( int  sid,
HPAGE  hPage,
LPCRECT  pRect,
DESPECKLE_METHOD  method,
int  level 
)

Forcing despeckle.

This function performs noise removal on the given area within the current (II_CURRENT) image of a page. The method and the level of the noise removal can be specified.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page.
[in]pRectPointer to the rectangle to be processed. A NULL value means the entire image.
[in]methodApplied despeckle method.
[in]levelDespeckle level. The possible values depend on the despeckle method.
Return values:
RECERR
Note:
If the image is not black-and-white the function returns IMG_BITSPERPIXEL_ERR.
The possible despeckle level depends on the despeckle method.
See also kRecDespeckleImg.
The specification of this function in C# is:
    RECERR kRecForceDespeckleImg(int sid, IntPtr hPage, RECT pRect, DESPECKLE_METHOD method, int level);
    // or when pRect is NULL in C/C++
    RECERR kRecForceDespeckleImg(int sid, IntPtr hPage, DESPECKLE_METHOD method, int level);
RECERR RECAPIKRN kRecFreeImg ( HPAGE  hPage)

Removing a page.

The kRecFreeImg function removes a page from the image management module. All internal images relating to the page and any recognition results are removed.

Parameters:
[in]hPageHandle of the page to be removed.
Return values:
RECERR
Note:
The specification of this function in C# is:
 RECERR kRecFreeImg(IntPtr hPage); 
RECERR RECAPIKRN kRecGetDropoutColorWeights ( int  sid,
int *  pwred,
int *  pwgreen,
int *  pwblue 
)

Getting the dropout color weight settings.

The kRecGetDropoutColorWeights function inquires the current value of the drop-out color weights. See kRecSetDropoutColorWeights.

Parameters:
[in]sidSettings Collection ID.
[in]pwredPointer of a variable to store the weight of the red component.
[in]pwgreenPointer of a variable to store the weight of the green component.
[in]pwbluePointer of a variable to store the 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.
This function gets the settings Kernel.Img.DropoutColor.Blue and ...Green and ...Red. These settings can be changed by kRecSetDropoutColorWeights.
The specification of this function in C# is:
 RECERR kRecGetDropoutColorWeights(int sid, out int wred, out int wgreen, out int wblue); 
RECERR RECAPIKRN kRecGetFaxCorrection ( int  sid,
INTBOOL *  pCorr 
)

Getting the value of fax correction setting.

This function retrieves the setting Kernel.Img.FaxCorrectionEnabled.

Parameters:
[in]sidSettings Collection ID.
[in]pCorrPointer of a variable to get the value of the setting.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.FaxCorrectionEnabled. This setting can be changed by kRecSetFaxCorrection.
The specification of this function in C# is:
 RECERR kRecGetFaxCorrection(int sid, out bool pCorr); 
RECERR RECAPIKRN kRecGetFrameCount ( HPAGE  hPage,
int *  pnFrames 
)

Getting the number of frames.

This function gets the number of frames detected previously by kRecRecognize functions.

Parameters:
[in]hPageHandle of the page.
[out]pnFramesAddress of an integer variable to get the number of frames.
Return values:
RECERR
Note:
The specification of this function in C# is:
 RECERR kRecGetFrameCount(IntPtr hPage, out int pnFrames); 
RECERR RECAPIKRN kRecGetFrameInfo ( HPAGE  hPage,
IMAGEINDEX  iiImg,
LPCELL_INFO  pFrame,
int  nFrame 
)

Getting frame information.

This function can be used for getting information about any frame detected previously by kRecRecognize functions.

Parameters:
[in]hPageHandle of the page.
[in]iiImgIndex of the image in the page, whose coordinate system is used to report the frames.
[out]pFramePointer to a variable for storing the requested frame information.
[in]nFrameIndex of the frame in the frame list, from which the information is requested.
Return values:
RECERR
Note:
The frame is a homogeneous color rectangular area with or without border lines. It may contain zones (ZONE). Frames are detected by kRecRecognize, only when the used decomp method is DCM_STANDARD. If the image is colored and the setting Kernel.OcrMgr.RetainColor is RETAINCOLOR_YES (see kRecSetRetainColor) it tries to detect the colored frames in the color image as well. Otherwise, the detection runs on the II_BW image. The structure CELL_INFO is used for describing frames.
The index of the first frame in the frame list is zero (0).
The specification of this function in C# is:
 RECERR kRecGetFrameInfo(IntPtr hPage, IMAGEINDEX iiImg, out CELL_INFO pFrame, int nFrame); 
RECERR RECAPIKRN kRecGetImgArea ( int  sid,
HPAGE  hPageIn,
IMAGEINDEX  iiImg,
LPCRECT  pSrcRect,
LPCSIZE  pDstSize,
LPIMG_INFO  pImg,
BYTE **  ppBitmap 
)

Getting image area.

The kRecGetImgArea function copies and exports a rectangular area of the given image of the page stored in the Engine's image management module into a buffer available to the application. It results in a bitmap in the application's memory space. The function compresses or stretches the area if necessary to fit the dimensions of the destination size.

Parameters:
[in]sidSettings Collection ID.
[in]hPageInHandle of the page which contains the source image.
[in]iiImgIndex of the source image in the page.
[in]pSrcRectCoordinates of the source rectangular area. NULL means: the whole image will be copied.
[in]pDstSizePointer to the dimensions of the destination area. A value of NULL here means that the destination size will be equal to the original one.
[out]pImgAddress of a structure to get information about the output image area.
[out]ppBitmapAddress of a pointer to the resulting bitmap.
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. During exporting the bitmap will be stretched or compressed according to the current setting of the Image stretching mode. The stretching mode can be set by a previous kRecSetImgStretchMode.
After having called this function, the application should call the kRecFree function to free the memory area containing the bitmap, when it is no longer needed.
The coordinates of the leftmost pixel of the uppermost line of the image are (0,0).
In B/W images created by this function the representation of black pixels is one (1), and white is zero (0). So, for displaying the image, use the NOTSRCCOPY raster operation code.
Instead of using this function, the application may prefer to call kRecStartReadImg, kRecReadImg, kRecStopReadImg, which transfer an image from the Engine to the application line-by-line.
If the image area to be copied also needs to be rotated and/or mirrored, use kRecRotateImgArea as an alternative to this function.
See also kRecGetImgAreaEx.
It is recommended to check the resulting image info, since it is not guaranteed that the type (BitsPerPixel) parameter will be the same as for the image given by the image index. While enlarging the image always results in a bitmap of the same type as the specified one, when image compressing/stretching is necessary, the BitsPerPixel field of the resulting image will depend on the current Image stretching mode setting.
Some attributes of the new image to be created, like the Line order (IMG_LINEORDER), the Padding mode (IMG_PADDING) and - for color images - the RGBorder (IMG_RGBORDER) can be specified by a preceding call of kRecSetImgFormat.
Getting an image area for display:
    RECERR rc;
    HPAGE hPage;
    IMG_INFO img;
    RECT rect;
    BYTE *pBitmap;
    HBITMAP hBitmap;
    . . .
    rect.left = 0;
    rect.top = 0;
    rect.right = 200;
    rect.bottom = 180;
    rc = kRecGetImgArea(sid, hPage, II_ORIGINAL, &rect, NULL, &img, &pBitmap);
    hBitmap = CreateBitmap(img.Size.cx, img.Size.cy, 1, img.BitsPerPixel, pBitmap);
    rc = kRecFree(pBitmap);
    . . .
The specification of this function in C# is:
    RECERR kRecGetImgArea(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, RECT pSrcRect, SIZE pDstSize, out IMG_INFO pImg,
                            out byte[] pBitmap);
    // or when pSrcRect is NULL in C/C++
    RECERR kRecGetImgArea(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, SIZE pDstSize, out IMG_INFO pImg, out byte[] pBitmap);
    // or when pDstSize is NULL in C/C++
    RECERR kRecGetImgArea(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, RECT pSrcRect, out IMG_INFO pImg, out byte[] pBitmap);
    // or when both are NULL
    RECERR kRecGetImgArea(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, out IMG_INFO pImg, out byte[] pBitmap);
    // or
    RECERR kRecGetImgArea(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, RECT pSrcRect, SIZE pDstSize, out IMG_INFO pImg,
                            out Bitmap bmp);
    // or when pSrcRect is NULL in C/C++
    RECERR kRecGetImgArea(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, SIZE pDstSize, out IMG_INFO pImg, out Bitmap bmp);
    // or when pDstSize is NULL in C/C++
    RECERR kRecGetImgArea(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, RECT pSrcRect, out IMG_INFO pImg, out Bitmap bmp);
    // or when both are NULL
    RECERR kRecGetImgArea(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, out IMG_INFO pImg, out Bitmap bmp);
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.

The kRecGetImgAreaEx function copies and exports a rectangular area of the given image of the page stored in the Engine's image management module into a buffer available to the application. It results in a bitmap in the application's memory space. The function compresses or stretches the area if necessary to fit the dimensions of the destination size.

Parameters:
[in]sidSettings Collection ID.
[in]hPageInHandle of the page which contains the source image.
[in]iiImgIndex of the source image in the page.
[in]pSrcRectCoordinates of the source rectangular area. NULL means: the whole image will be copied.
[in]pDstSizePointer to the dimensions of the destination area. A value of NULL here means that the destination size will be equal to the original one.
[in]StretchModeStretching mode.
[in]LineOrderOrder of the lines in the received buffer.
[in]RGBOrderOrder of the composite color components (COLOR_RGB, COLOR_BGR or COLOR_BGRA).
[in]strictIf TRUE: the received buffer will contain 24-bit RGB, 24-bit BGR, 32-bit BGRA or 32-bit ARGB bitmap depending on RGBOrder. If FALSE: the received buffer may contain 1-bit or 8-bit bitmap too if the input is 1-bit or 8-bit image (just like kRecGetImgArea)
[in]PaddingThis parameter determines how the lines are to be padded in the received buffer.
[out]pImgAddress of a structure to get information about the output image area.
[out]ppBitmapAddress of a pointer to the resulting bitmap.
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. During exporting the bitmap will be stretched or compressed according to the StretchMode parameter.
After having called this function, the application should call the kRecFree function to free the memory area containing the bitmap, when it is no longer needed.
The coordinates of the leftmost pixel of the uppermost line of the image are (0,0).
See also kRecGetImgArea.
The specification variations of this function in C# are:
    RECERR kRecGetImgAreaEx(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, RECT pSrcRect, SIZE pDstSize,
            IMG_STRETCHMODE StretchMode, IMG_LINEORDER LineOrder, IMG_RGBORDER RGBOrder,
            [MarshalAs(UnmanagedType.Bool)] bool strict, IMG_PADDING Padding, out IMG_INFO Img, out IntPtr pBitmap);
    RECERR kRecGetImgAreaEx(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, RECT pSrcRect, SIZE pDstSize,
            IMG_STRETCHMODE StretchMode, IMG_LINEORDER LineOrder, IMG_RGBORDER RGBOrder,
            [MarshalAs(UnmanagedType.Bool)] bool strict, IMG_PADDING Padding, out IMG_INFO Img, out byte[] pBitmap);
    RECERR kRecGetImgAreaEx(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, SIZE pDstSize,
            IMG_STRETCHMODE StretchMode, IMG_LINEORDER LineOrder, IMG_RGBORDER RGBOrder,
            [MarshalAs(UnmanagedType.Bool)] bool strict, IMG_PADDING Padding, out IMG_INFO Img, out byte[] pBitmap);
    RECERR kRecGetImgAreaEx(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, RECT pSrcRect,
            IMG_STRETCHMODE StretchMode, IMG_LINEORDER LineOrder, IMG_RGBORDER RGBOrder,
            [MarshalAs(UnmanagedType.Bool)] bool strict, IMG_PADDING Padding, out IMG_INFO Img, out byte[] pBitmap);
    RECERR kRecGetImgAreaEx(int sid, IntPtr hPageIn, IMAGEINDEX iiImg,
            IMG_STRETCHMODE StretchMode, IMG_LINEORDER LineOrder, IMG_RGBORDER RGBOrder,
            [MarshalAs(UnmanagedType.Bool)] bool strict, IMG_PADDING Padding, out IMG_INFO Img, out byte[] pBitmap);
    RECERR kRecGetImgAreaEx(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, RECT pSrcRect, SIZE pDstSize,
            IMG_STRETCHMODE StretchMode, IMG_LINEORDER LineOrder, IMG_RGBORDER RGBOrder,
            [MarshalAs(UnmanagedType.Bool)] bool strict, IMG_PADDING Padding, out IMG_INFO Img, out Bitmap bmp);
    RECERR kRecGetImgAreaEx(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, SIZE pDstSize,
            IMG_STRETCHMODE StretchMode, IMG_LINEORDER LineOrder, IMG_RGBORDER RGBOrder,
            [MarshalAs(UnmanagedType.Bool)] bool strict, IMG_PADDING Padding, out IMG_INFO Img, out Bitmap bmp);
    RECERR kRecGetImgAreaEx(int sid, IntPtr hPageIn, IMAGEINDEX iiImg, RECT pSrcRect,
            IMG_STRETCHMODE StretchMode, IMG_LINEORDER LineOrder, IMG_RGBORDER RGBOrder,
            [MarshalAs(UnmanagedType.Bool)] bool strict, IMG_PADDING Padding, out IMG_INFO Img, out Bitmap bmp);
    RECERR kRecGetImgAreaEx(int sid, IntPtr hPageIn, IMAGEINDEX iiImg,
            IMG_STRETCHMODE StretchMode, IMG_LINEORDER LineOrder, IMG_RGBORDER RGBOrder,
            [MarshalAs(UnmanagedType.Bool)] bool strict, IMG_PADDING Padding, out IMG_INFO Img, out Bitmap bmp);
RECERR RECAPIKRN kRecGetImgBinarizationMode ( int  sid,
LPIMG_CONVERSION  pBWConversion 
)

Getting secondary image conversion mode.

The kRecGetImgBinarizationMode function inquires the current secondary image conversion mode setting.

Parameters:
[in]sidSettings Collection ID.
[out]pBWConversionAddress of a variable to receive the current secondary image conversion mode setting.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.Binarization.SecondaryMode. This setting can be changed by kRecSetImgBinarizationMode.
The specification of this function in C# is:
 RECERR kRecGetImgBinarizationMode(int sid, out IMG_CONVERSION pBWConversion); 
RECERR RECAPIKRN kRecGetImgBrightness ( int  sid,
int *  lpBrightness 
)

Getting brightness.

The kRecGetImgBrightness function inquires the current value of the threshold fine-tuning setting.

Parameters:
[in]sidSettings Collection ID.
[out]lpBrightnessAddress of the variable to get the current brightness setting.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.Binarization.Brightness. This setting can be changed by kRecSetImgBrightness.
The specification of this function in C# is:
 RECERR kRecGetImgBrightness(int sid, out int pBrightness); 
RECERR RECAPIKRN kRecGetImgConvMode ( int  sid,
IMG_CONVERSION pConversion 
)

Getting primary image conversion mode.

The kRecGetImgConvMode function inquires the current primary image conversion mode setting.

Parameters:
[in]sidSettings Collection ID.
[out]pConversionAddress of a variable to receive the current setting of the primary image conversion mode.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.Binarization.PrimaryMode. This setting can be changed by kRecSetImgConvMode.
The specification of this function in C# is:
 RECERR kRecGetImgConvMode(int sid, out IMG_CONVERSION pConversion); 
RECERR RECAPIKRN kRecGetImgDeskew ( int  sid,
IMG_DESKEW pImgDeskew 
)

Getting deskew mode.

The kRecGetImgDeskew function inquires the current Image deskewing mode setting.

Parameters:
[in]sidSettings Collection ID.
[out]pImgDeskewPointer to a variable to get the current deskewing mode.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.Deskew.Mode. This setting can be changed by kRecSetImgDeskew.
The specification of this function in C# is:
 RECERR kRecGetImgDeskew(int sid, out IMG_DESKEW pImgDeskew); 
RECERR RECAPIKRN kRecGetImgDespeckleMode ( int  sid,
LPINTBOOL  lpbMode 
)

Getting despeckle mode.

The kRecGetImgDespeckleMode function inquires the current Image despeckle mode setting of the Engine.

Parameters:
[in]sidSettings Collection ID.
[out]lpbModePointer to a variable to get the current setting.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.DespeckleMode. This setting can be changed by kRecSetImgDespeckleMode.
The specification of this function in C# is:
 RECERR kRecGetImgDespeckleMode(int sid, out bool pbMode); 
RECERR RECAPIKRN kRecGetImgDownsample ( int  sid,
INTBOOL *  pdownsample 
)

Getting the value of view downsample setting.

This function retrieves the setting Kernel.Img.ViewDownsample. For more information about this setting see Settings of the Image Handling Module. See kRecSetImgDownsample.

Parameters:
[in]sidSettings Collection ID.
[in]pdownsamplePointer of a variable to get the value of the setting.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.ViewDownsample. This setting can be changed by kRecSetImgDownsample.
The specification of this function in C# is:
 RECERR kRecGetImgDownsample(int sid, out bool pdownsample); 
RECERR RECAPIKRN kRecGetImgFlags ( HPAGE  hPage,
IMG_FLAGS  Flag,
INTBOOL *  pbValue 
)

Getting the value of image flags.

The kRecGetImgFlags function retrieves the current value of the specified flag of the given HPAGE.

Parameters:
[in]hPageHandle of the page.
[in]FlagThe flag to get. See: IMG_FLAGS.
[in]pbValueAddress of the pointer to get the flag. /note These flags are automatically set during image loading process. The IMG_FLAGS_CAMERAIMAGE flag is set to 1 when the source is JPG file, and the exif info contains tags that suggest that the image is from digital camera or phone. You can change this flag by kRecSetImgFlags.
RECERR RECAPIKRN kRecGetImgFormat ( int  sid,
IMG_LINEORDER plineord,
IMG_PADDING ppadding,
IMG_RGBORDER pord 
)

Getting image format.

The kRecGetImgFormat function inquires the current setting of the line order, the padding mode and the order of the composite color components of the image.

Parameters:
[in]sidSettings Collection ID.
[out]plineordAddress to a variable to hold the current line order setting.
[out]ppaddingAddress to a variable to hold the current padding mode setting.
[out]pordAddress to a variable to hold the current RGB order setting.
Return values:
RECERR
Note:
This function gets the settings Kernel.Img.LineOrder and ...Padding and ...RGBOrder. These settings can be changed by kRecSetImgFormat.
The specification of this function in C# is:
 RECERR kRecGetImgFormat(int sid, out IMG_LINEORDER plineord, out IMG_PADDING ppadding, out IMG_RGBORDER pord); 
RECERR RECAPIKRN kRecGetImgInfo ( int  sid,
HPAGE  hPage,
IMAGEINDEX  iiImg,
LPIMG_INFO  pImg 
)

Getting image information.

The kRecGetImgInfo function retrieves information about any image of the page. This includes e.g. dimensions, resolution, image type (number of bits per pixel), etc. of the specified image.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page containing the requested image.
[in]iiImgIndex to the requested image in the page.
[in]pImgAddress of a IMG_INFO structure to get the image information.
Return values:
RECERR
Note:
For palette-color images, a further call of kRecGetImgPalette provides the palette.
The specification of this function in C# is:
 RECERR kRecGetImgInfo(int sid, IntPtr hPage, IMAGEINDEX iiImg, out IMG_INFO pImg); 
RECERR RECAPIKRN kRecGetImgInvert ( int  sid,
IMG_INVERT lpImgInvert 
)

Getting inversion mode.

The kRecGetImgInvert function inquires the current Image inversion mode setting.

Parameters:
[in]sidSettings Collection ID.
[out]lpImgInvertPointer to a variable to get the current inversion mode.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.Invert. This setting can be changed by kRecSetImgInvert.
The specification of this function in C# is:
 RECERR kRecGetImgInvert(int sid, out IMG_INVERT pImgInvert); 
RECERR RECAPIKRN kRecGetImgMetaData ( HPAGE  hPage,
HSETTING phMetaData 
)

Getting additional information about the page.

The kRecGetImgMetaData function retrieves additional information attached to the page in the image file. This includes exif info for JPG files, the tags of TIF files and several properties of PDF files.

Parameters:
[in]hPageHandle of the page.
[out]phMetaDataThe returned handle is the root of the metadata.
Return values:
RECERR
Note:
If hPage does not contain metadata, the function returns a NULL handle.
Metadata is organized into a tree. This tree corresponds to a tree of settings. The handle returned by this function is a setting handle pointing to the root of the metadata tree. Use the functions of the Settings Manager Module to access information embedded to the tree.
The specification of this function in C# is:
 RECERR kRecGetImgMetaData(IntPtr hPage, out IntPtr phMetaData); 
RECERR RECAPIKRN kRecGetImgPalette ( int  sid,
HPAGE  hPage,
IMAGEINDEX  iiImg,
LPBYTE  pPal 
)

Getting the palette of the image.

This function retrieves the palette of the selected image of the given page.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page containing the inquired image.
[in]iiImgIndex of the inquired image.
[out]pPalPointer of a buffer to store the palette. It must be large enough to hold 768 bytes. 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 image does not contain palette the function returns API_PARAMETER_ERR.
The specification of this function in C# is:
 RECERR kRecGetImgPalette(int sid, IntPtr hPage, IMAGEINDEX iiImg, out byte[] pPal); 
RECERR RECAPIKRN kRecGetImgResolEnhancement ( int  sid,
IMG_RESENH res 
)

Getting resolution enhancement mode.

The kRecGetImgResolEnhancement function inquires the current Image resolution enhancement mode setting of the Engine.

Parameters:
[in]sidSettings Collection ID.
[out]resPointer to a variable to get the current setting.
Return values:
RECERR.
Note:
This function gets the setting Kernel.Img.ResolutionEnhancement. This setting can be changed by kRecSetImgResolEnhancement.
The specification of this function in C# is:
 RECERR kRecGetImgResolEnhancement(int sid, out IMG_RESENH res); 
RECERR RECAPIKRN kRecGetImgRotation ( int  sid,
IMG_ROTATE lpImgRotate 
)

Getting rotation mode.

The kRecGetImgRotation function inquires the current Image rotation mode setting.

Parameters:
[in]sidSettings Collection ID.
[out]lpImgRotatePointer to a variable to get the current Image rotation mode setting.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.Rotation. This setting can be changed by kRecSetImgRotation.
The specification of this function in C# is:
 RECERR kRecGetImgRotation(int sid, out IMG_ROTATE pImgRotate); 
RECERR RECAPIKRN kRecGetImgSlope ( int  sid,
int *  lpSlope 
)

Getting the slope.

The kRecGetImgSlope function returns the current slope value setting set by a previous kRecSetImgSlope function call.

Parameters:
[in]sidSettings Collection ID.
[out]lpSlopePointer to a variable to get current slope value.
Return values:
RECERR
Note:
Call kRecDetectImgSkew to detect the skew of an image containing machine printed text.
This function gets the setting Kernel.Img.Deskew.Slope. This setting can be changed by kRecSetImgSlope.
The specification of this function in C# is:
 RECERR kRecGetImgSlope(int sid, out int pSlope); 
RECERR RECAPIKRN kRecGetImgStretchMode ( int  sid,
IMG_STRETCHMODE pImgStretchMode 
)

Getting stretching mode.

The kRecGetImgStretchMode function gets the current Image stretching mode setting.

Parameters:
[in]sidSettings Collection ID.
[out]pImgStretchModePointer to a variable to get the current Image stretching mode setting.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.StretchMode. This setting can be changed by kRecSetImgStretchMode.
The specification of this function in C# is:
 RECERR kRecGetImgStretchMode(int sid, out IMG_STRETCHMODE pImgStretchMode); 
RECERR RECAPIKRN kRecGetImgThreshold ( int  sid,
int *  pThreshold 
)

Getting binarization threshold.

The kRecGetImgThreshold function inquires the current value of the image conversion threshold setting.

Parameters:
[in]sidSettings Collection ID.
[out]pThresholdAddress of the variable that holds the current threshold value.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.Binarization.Threshold. This setting can be changed by kRecSetImgThreshold.
The specification of this function in C# is:
 RECERR kRecGetImgThreshold(int sid, out int pThreshold); 
RECERR RECAPIKRN kRecGetLineCount ( HPAGE  hPage,
int *  pnLines 
)

Getting the number of rule lines.

This function gets the number of rule lines detected previously by kRecLineRemoval, kRecLocateZones or kRecRecognize functions.

Parameters:
[in]hPageHandle of the page.
[out]pnLinesAddress of an integer variable to get the number of rule lines.
Return values:
RECERR
Note:
The specification of this function in C# is:
 RECERR kRecGetLineCount(IntPtr hPage, out int pnLines); 
RECERR RECAPIKRN kRecGetLineInfo ( HPAGE  hPage,
IMAGEINDEX  iiImg,
PRLINE  pLine,
int  nLine 
)

Getting rule line information.

This function can be used for getting information about any rule line detected previously by kRecLineRemoval, kRecLocateZones or kRecRecognize functions.

Parameters:
[in]hPageHandle of the page.
[in]iiImgIndex of the image in the page, whose coordinate system is to be used to report the lines.
[out]pLinePointer to a variable for storing the requested line information.
[in]nLineIndex of the line in the line list, from which the information is requested.
Return values:
RECERR
Note:
The index of the first line in the line list is zero (0).
The specification of this function in C# is:
 RECERR kRecGetLineInfo(IntPtr hPage, IMAGEINDEX iiImg, out RLINE pLine, int nLine); 
RECERR RECAPIKRN kRecGetPreprocessInfo ( HPAGE  hPage,
PREPROC_INFO pPreprocInfo 
)

Returning information about the preprocessing.

After preprocessing the image, you can ask information about the applied operations.

Parameters:
[in]hPageHandle of the page.
[out]pPreprocInfoPointer to a variable to get the information.
Return values:
RECERR
Note:
HPAGE keeps a record about the operations applied by kRecPreprocessImg. This function returns the current state of this record, see PREPROC_INFO.
kRecDespeckleImg, kRecRotateImg, kRecDeskewImg, kRec3DDeskewImg and kRecApplyFormTemplate functions also modify this record.
The specification of this function in C# is:
 RECERR kRecGetPreprocessInfo(IntPtr hPage, out PREPROC_INFO pPreprocInfo); 
RECERR RECAPIKRN kRecGetPreserveOriginalImg ( int  sid,
INTBOOL *  pPreserve 
)

Getting the value of the keep original image setting.

This function retrieves the setting Kernel.Img.KeepOriginalImage. For more information about this setting see Settings of the Image Handling Module. See kRecSetPreserveOriginalImg.

Parameters:
[in]sidSettings Collection ID.
[in]pPreservePointer of a variable to get the value of the setting.
Return values:
RECERR
Note:
This function gets the setting Kernel.Img.KeepOriginalImage. This setting can be changed by kRecSetPreserveOriginalImg.
The specification of this function in C# is:
 RECERR kRecGetPreserveOriginalImg(int sid, out bool pPreserve); 
RECERR RECAPIKRN kRecGetRetainColor ( int  sid,
RETAINCOLOR pRetainColor 
)

Getting retain color setting.

This function gets the retain color setting.

Parameters:
[in]sidSettings Collection ID.
[out]pRetainColorPointer of a variable to store the retain color value.
Return values:
RECERR
Note:
This function gets the setting Kernel.OcrMgr.RetainColor. This setting can be changed by kRecSetRetainColor.
The specification of this function in C# is:
 RECERR kRecGetRetainColor(int sid, out RETAINCOLOR pRetainColor); 
RECERR RECAPIKRN kRecGetThumbnailImgInfo ( int  sid,
IMG_INFO pThumbnail,
REC_COLOR pColor 
)

Getting the value of thumbnail image info settings.

This function retrieves the value of settings under the node Kernel.Img.Thumbnail. For more information about this setting see Settings of the Image Handling Module. See kRecSetThumbnailImgInfo.

Parameters:
[in]sidSettings Collection ID.
[out]pThumbnailThis is the size and the bits per pixel information of the thumbnail image. Only these fields will be filled.
[out]pColorThis is the thumbnail color. See II_THUMBNAIL.
Return values:
RECERR
Note:
This function gets the settings Kernel.Img.Thumbnail.BitsPerPixel, ...Color, ...Size.X and ...Size.Y. These settings can be changed by kRecSetThumbnailImgInfo.
The specification of this function in C# is:
 RECERR kRecGetThumbnailImgInfo(int sid, out IMG_INFO pThumbnail, out uint color); 
RECERR RECAPIKRN kRecImgAutoEnhance ( HPAGE  hPage,
BYTE  blackPointred,
BYTE  whitePointred,
BYTE  blackPointgreen,
BYTE  whitePointgreen,
BYTE  blackPointblue,
BYTE  whitePointblue 
)

Image auto-enhancement.

This function performs a gray-level enhancement transformation on the current image (II_CURRENT) of the given page. It works for both color and gray-scale images. It sets all the input gray-levels under the lower (black point) threshold to black and all of them over the higher (white point) threshold to white output level. The remaining interval of the input levels is expanded into the interval of the remaining output levels (between 1 and 254). If the input image is colored, the output image is also colored.

Parameters:
[in]hPageHandle of the page.
[in]blackPointredThe lower (black point) threshold of the red component.
[in]whitePointredThe higher (white point) threshold of the red component.
[in]blackPointgreenThe lower (black point) threshold of the green component.
[in]whitePointgreenThe higher (white point) threshold of the green component.
[in]blackPointblueThe lower (black point) threshold of the blue component.
[in]whitePointblueThe higher (white point) threshold of the blue component.
Return values:
RECERR
Note:
Only blackPointred and whitePointred are used on gray-scale images.
The specification of this function in C# is:
 RECERR kRecImgAutoEnhance(IntPtr hPage, byte blackPointRed, byte whitePointRed, byte blackPointGreen, byte whitePointGreen, byte blackPointBlue, byte whitePointBlue); 
RECERR RECAPIKRN kRecImgDilatation ( int  sid,
HPAGE  hPage,
ERO_DIL_TYPE  type 
)

Dilatation.

This function performs dilatation on binary images. Dilatation changes a white pixel to black if at least one of its neighbors is black. Black pixels remain unchanged. This tends to thicken character shapes, thus it can be used for visual enhancement of some images. However, this operation is typically not useful for images to be OCR-ed. The opposite process is erosion.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page to be processed.
[in]typeThis parameter determines which neighbours are tested during the operation.
Return values:
RECERR
Note:
If the II_CURRENT image is not black-and-white the function returns IMG_BITSPERPIXEL_ERR.
The specification of this function in C# is:
 RECERR kRecImgDilatation(int sid, IntPtr hPage, ERO_DIL_TYPE typeint); 
RECERR RECAPIKRN kRecImgErosion ( int  sid,
HPAGE  hPage,
ERO_DIL_TYPE  type 
)

Erosion.

This function performs erosion on binary images. Erosion changes a black pixel to white if at least one of its neighbors is white. White pixels remain unchanged. This tends to make character shapes thinner, thus it can be used for visual enhancement of some images. This operation is typically not useful for images to be OCR-ed. The opposite process is dilatation.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page to be processed.
[in]typeThis parameter determines which neighbours are tested during the operation.
Return values:
RECERR
Note:
If the II_CURRENT image is not black-and-white the function returns IMG_BITSPERPIXEL_ERR.
The specification of this function in C# is:
 RECERR kRecImgErosion(int sid, IntPtr hPage, ERO_DIL_TYPE typeint); 
RECERR RECAPIKRN kRecInvertImgArea ( int  sid,
HPAGE  hPage,
LPCRECT  lpRect 
)

Inverting image area.

The kRecInvertImgArea function performs immediate image inversion of all the images of the page except II_ORIGINAL or a rectangular area inside them. This function ignores the image inversion mode setting. The inverted image (or the image with a rectangle inverted) 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]sidSettings Collection ID.
[in]hPageHandle of the page containing the image to be modified.
[in]lpRectPointer to the rectangular area to be inverted. If it is NULL the entire image is inverted.
Return values:
RECERR
Note:
For B/W images, the most usual inversion is from white-on-black to black-on-white, because the latter is needed for successful recognition.
For grayscale images, each pixel value is transformed to its complementary value. E.g. for a 4-bit image, a value of 11 is inverted to 4.
For color images, each color component is inverted to its complementary value. For instance:
  • R was 000 becomes 255
  • G was 253 becomes 002
  • B was 120 becomes 135.
The specification of this function in C# is:
    RECERR kRecInvertImgArea(int sid, IntPtr hPage, RECT pRect);
    // or when pRect is NULL in C/C++
    RECERR kRecInvertImgArea(int sid, IntPtr hPage);
RECERR RECAPIKRN kRecIsImgPalette ( int  sid,
HPAGE  hPage,
IMAGEINDEX  iiImg,
LPINTBOOL  pbPal 
)

Inquiring about palette of the image.

This function retrieves whether the selected image of the given page has a palette or not.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page containing the inquired image.
[in]iiImgIndex of the inquired image.
[out]pbPalPointer of a variable to store the retrieved value. TRUE when the image has a palette.
Return values:
RECERR
Note:
The specification of this function in C# is:
 RECERR kRecIsImgPalette(int sid, IntPtr hPage, IMAGEINDEX iiImg, out bool pbPal); 
RECERR RECAPIKRN kRecLineRemoval ( int  sid,
HPAGE  hPage,
const RECT *  pRect 
)

Removing lines.

The kRecLineRemoval function removes horizontal and vertical rule lines from the II_BW image of the page inside the given rectangle. The detected rule lines are stored in the line list of HPAGE, and can be obtained by kRecGetLineCount and kRecGetLineInfo functions.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page.
[in]pRectThe rectangular area inside which lines are removed from the image. The function assumes that the coordinates are given in the coordinate system of the II_BW image. NULL means the whole image.
Return values:
RECERR
Note:
Not all line occurrences are handled in the same way. See RLINE for more information.
See also: kRecRemoveLines.
The specification of this function in C# is:
    RECERR kRecLineRemoval(int sid, IntPtr hPage, RECT pRect);
    // or
    RECERR kRecLineRemoval(int sid, IntPtr hPage);
RECERR RECAPIKRN kRecMergeImgArea ( int  sid,
HPAGE  hPageDst,
LPCRECT  pRectDst,
HPAGE  hPageSrc,
LPCRECT  pRectSrc,
REC_COLOR  tColor 
)

Merging areas of images.

This function merges a rectangular area of the II_CURRENT image of the given source page and a rectangular area of the II_CURRENT image of the given destination page. One color can be designated as being transparent (see also notes). Where the color of the source pixel corresponds to the transparent color the destination pixel is not changed. The function compresses or stretches the area if necessary to fit the dimensions of the destination size.

Parameters:
[in]sidSettings Collection ID.
[in]hPageDstHandle of the page which contains the destination image.
[in]pRectDstCoordinates of the destination rectangular area. NULL means the whole image.
[in]hPageSrcHandle of the page which contains the source image.
[in]pRectSrcCoordinates of the source rectangular area. NULL means the whole image.
[in]tColorThe color designated as being transparent.
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.
This function accepts 32 bit image (BGRA format) as source image and REC_TRANSPARENT_COLOR as tColor. In this case the function uses the alpha channel of the source image.
The specification of this function in C# is:
    RECERR kRecMergeImgArea(int sid, IntPtr hPageDst, RECT rectDst, IntPtr hPageSrc, RECT rectSrc, uint color);
    // or when pRectDst is NULL in C/C++
    RECERR kRecMergeImgArea(int sid, IntPtr hPageDst, IntPtr hPageSrc, RECT rectSrc, uint color);
    // or when pRectSrc is NULL in C/C++
    RECERR kRecMergeImgArea(int sid, IntPtr hPageDst, RECT rectDst, IntPtr hPageSrc, uint color);
    // or when pRectDst and pRectSrc are NULL in C/C++
    RECERR kRecMergeImgArea(int sid, IntPtr hPageDst, IntPtr hPageSrc, uint color);
RECERR RECAPIKRN kRecPreprocessImg ( int  sid,
HPAGE  hPage 
)

Image preprocessing.

The function kRecPreprocessImg performs a series of image pre-processing steps by activating the PID_IMGPREPROCESS process. Performing these image pre-processing steps may improve the quality of the image from an OCR point of view, which may have an impact on the overall page recognition accuracy. If pre-processing is desired, it should be done before performing auto-zoning and recognition. The available pre-processing steps are despeckle, fax correction, image inversion, deskewing, and rotation. (Using the Visual Toolbox, further preprocessing can be done by SET tools. For more information, see the Visual Toolbox help system.)

The preprocessing performs fax correction, rotation and deskew operations on II_CURRENT image, creates the image II_BW (implicit secondary image conversion) and does the image inversion and the despeckle operations on the latter image. (Despeckle runs only when the current image is a B/W one.) After these steps, it deletes the II_ORIGINAL image except when kRecSetPreserveOriginalImg has been called with TRUE parameter. The executing mode of these steps depends on the settings that can be changed by kRecSetImgInvert, kRecSetImgDeskew, kRecSetImgRotation, kRecSetImgDownsample, kRecSetFaxCorrection, kRecSetImgBinarizationMode, kRecSetImgDespeckleMode, kRecSetImgBinarizationMode, kRecSetImgBrightness, kRecSetImgThreshold, kRecSetImgResolEnhancement, kRecSetRMTradeoff, kRecSetLanguages and kRecSetDefaultFillingMethod. The value needed for programmed deskewing (DSK_SET) can be detected by kRecDetectImgSkew and defined in kRecSetImgSlope. Under certain circumstances, image despeckling and resolution enhancement are also performed internally. These depend on the settings that can be changed by kRecSetImgDespeckleMode, kRecSetImgResolEnhancement.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page.
Return values:
RECERR
Note:
If the original image is grayscale or color, an implicit secondary image conversion step is performed to generate a hidden, clean B/W image on which the pre-processing tasks will operate. The parameters for this conversion can be specified through the functions kRecSetImgBinarizationMode and kRecSetImgResolEnhancement.
If the original image is B/W over 180 dpi and the Engine's Image despeckle mode setting is enabled, an implicit secondary image conversion step is also performed, to specifically despeckle the image. This is enabled through the function kRecSetImgDespeckleMode. By default despeckle detects if the image has been scanned in halftone mode and applies halftone removal if so. The halftone detection and removal can be switched off by Kernel.Img.Despeckle.Halftone setting.
As an alternative to this function, image modifications can be performed separately and immediately on a single defined image, by the functions kRecInvertImgArea, kRecDeskewImg, kRecRotateImg, kRecDespeckleImg. The first three functions can be used with any image type (B/W, grayscale or color). All these functions ignore the image mode settings, e.g. kRecDeskewImg will deskew a given image, even if kRecSetImgDeskew is set to DSK_NO. The modified images created by these functions are available to the application.
This function may change the resolution of the image:
  • if the resolution of the image is less than 50 DPI or greater than 19200 DPI,
  • if the resolution of the image is 72 DPI or 96 DPI,
  • if the image is captured by digital camera and it does not contain resolution (see: IMG_FLAGS). In these cases kRecPreprocessImg estimates the resolution: determines the average character size and supposes that the text contains 12 point fonts. The estimated resolution is rounded to 150, 200, 300, 450 or 600. The resolution of the image will be restored to the original value at the end of kRecRecognize if the Kernel.Img.Resolution.Restore setting is TRUE.
The coordinates of all user zones are recalculated. The OCR zones are removed.
If applicable, please set the required recognition language(s) before calling the kRecPreprocessImg function. This increases the efficiency of automatic image rotation.
Trade-off (RMTRADEOFF) specific notes:
  • If resolution enhancement is set to RE_AUTO the enhancement depends on the current trade-off setting according to the following: if trade-off is TO_FAST the resolution enhancement is RE_LEGACY, otherwise it is RE_STANDARD.
  • If trade-off is TO_FAST, pre-process uses a faster, but less accurate deskew, binarization and despeckle algorithm than otherwise.
  • The trade-off used by preprocessing can be set by setting the general trade-off (kRecSetRMTradeoff) or by setting the specific Settings of the Recognition Module Kernel.OcrMgr.TradeOff.Preproc setting.
This function uses the default filling method (kRecSetDefaultFillingMethod).
At processing dot matrix text, this function may give better result if the default filling method is set to FM_DRAFTDOT9.
Preprocessing digital camera images: HPAGE contains a flag (IMG_FLAGS_CAMERAIMAGE, see: IMG_FLAGS) which indicates whether the image is captured by digital camera (phone) or not. This flag is set when loading the image. If this flag is set deskew, binarization and resolution enhancement is done differently:
  • binarization: pre-process makes shading correction before binarization,
  • deskew: if the current deskewing mode is DSK_AUTO3D the function performs 3D deskew,
  • resolution enhancement: if the average height of the characters is large, the ratio of resolution enhancement will be 0.5.
After calling this function you can get information about the applied operations by the kRecGetPreprocessInfo function.
The specification of this function in C# is:
 RECERR kRecPreprocessImg(int sid, IntPtr hPage); 
RECERR RECAPIKRN kRecPutImgArea ( int  sid,
LPCIMG_INFO  lpImg,
const BYTE *  lpBitmap,
HPAGE  hPage,
int  xDst,
int  yDst,
LPCSIZE  pDstSize 
)

Updating image area.

The kRecPutImgArea function is used for updating a rectangular area of the current image of the page with a bitmap from the application. During downloading, the function compresses or stretches the original bitmap, if requested. The function assumes that the coordinates are given in the coordinate system of the current image (II_CURRENT).

Parameters:
[in]sidSettings Collection ID.
[in]lpImgPointer to an IMG_INFO structure which describes the source bitmap you want to download into the Engine.
[in]lpBitmapPointer to the source bitmap.
[in]hPageHandle of the page of the destination image to be modified.
[in]xDstX position of the destination area in pixels (upper left corner).
[in]yDstY position of the destination area in pixels (upper left corner).
[in]pDstSizeSize of the destination area. If this is not the same as the source area, the function compresses or stretches the area into the destination. NULL means that the size of the destination area will be the same as the size of the original bitmap.
Return values:
RECERR
Note:
If there is II_BW image in the page before using this function a secondary image conversion runs again after updating the current image.
If there is II_THUMBNAIL image in the page before using this function it is recreated after updating the current image.
A typical use of this function is in conjunction with the kRecGetImgArea function. Since an image is not directly accessible to the application, the kRecGetImgArea can be used to get a copy of the image in the application's authority. After having modified this copied image, the application can call the kRecPutImgArea function to pass back the modified image to the engine.
This function can also be used for passing the application's image to the engine. In this case before downloading the image, a new and empty image should be created with the kRecCreateImg function. The attributes of this empty image (size, resolution, Bits per pixel value) should be the same as for the application's bitmap. The xDst and yDst parameters must be set to zero (0) and the pDstSize should be NULL.
The kRecLoadImgM function or the kRecPutImgArea function should be used when it is easy to place an entire image into the engine's memory. However, you may instead prefer the kRecStartWriteImg, kRecWriteImg and kRecStopWriteImg set of functions, which transfer an image in successive lines.
This function takes into account the Engine settings Line order (IMG_LINEORDER) and - for color images - the RGBorder (IMG_RGBORDER), but ignores the Padding mode setting. These settings should be consistent with the appropriate attributes of the source bitmap. A preceding call to the kRecSetImgFormat API function can be used to change these settings.
The function always operates with the image stretching mode STRETCH_DELETE.
The specification of this function in C# is:
    RECERR kRecPutImgArea(int sid, IMG_INFO pImg, byte[] pBitmap, IntPtr hPage, int xDst, int yDst, SIZE pDstSize);
    // or when pDstSize is NULL in C/C++
    RECERR kRecPutImgArea(int sid, IMG_INFO pImg, byte[] pBitmap, IntPtr hPage, int xDst, int yDst);
    // or
    RECERR kRecPutImgArea(int sid, Bitmap pBitmap, IntPtr hPage, int xDst, int yDst, SIZE pDstSize);
    // or when pDstSize is NULL in C/C++
    RECERR kRecPutImgArea(int sid, Bitmap pBitmap, IntPtr hPage, int xDst, int yDst);
RECERR RECAPIKRN kRecReadImg ( int  sid,
LPBYTE  pBuff 
)

Reading an image line-by-line.

The kRecReadImg function exports one line from the specified image.

Parameters:
[in]sidSettings Collection ID.
[out]pBuffPointer of a buffer to store the next line.
Return values:
RECERR
Note:
This function is the second part in the three-part series for line-by-line reading an image. Before calling this function, the application should call the kRecStartReadImg function. Repeated calls of this function get a sequence of the lines of the image and generate a return code REC_OK each time. As soon as the function finds no further line to get, it returns with IMG_NOMORE_WARN, signaling the need for calling the kRecStopReadImg function.
This function is insecure for managed code. In C# use the more advanced kRecGetImgArea function.
RECERR RECAPIKRN kRecRemoveBorders ( int  sid,
HPAGE  hPage,
UINT  maxWidth 
)

Removing marginal shadows.

This function cleans marginal shadows that may result from scanning. The borders are filled in with the color white.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page to be processed.
[in]maxWidthMaximum width of the borders (in pixels).
Return values:
RECERR
Note:
The specification of this function in C# is:
 RECERR kRecRemoveBorders(int sid, IntPtr hPage, uint maxWidth); 
RECERR RECAPIKRN kRecRemoveLines ( int  sid,
HPAGE  hPage,
IMAGEINDEX  iiImg,
const RECT *  pRect 
)

Removing lines.

The kRecRemoveLines function removes horizontal and vertical rule lines from the II_CURRENT or II_BW image of the page inside the given rectangle. The detected rule lines are stored in the line list of HPAGE, and can be obtained by kRecGetLineCount and kRecGetLineInfo functions.

Parameters:
[in]sidSettings Collection ID.
[in]hPageHandle of the page.
[in]iiImgIndex of the image in the page to be processed. If the specified image is not black-and-white the function returns IMG_BITSPERPIXEL_ERR.
[in]pRectThe rectangular area inside which lines are removed from the image. The function assumes that the coordinates are given in the coordinate system of the iiImg image. NULL means the whole image.
Return values:
RECERR
Note:
Not all line occurrences are handled in the same way. See RLINE for more information.
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]sidSettings Collection ID.
[in]hPageHandle of the page to be processed.
[in]ROIsArray of rectangles inside which the punch holes should be detected. If it is NULL then the whole image is processed.
[in]nROIsThe number of rectangles in the ROIs array.
[in,out]HolesPointer 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]nHolesPointer to a variable for storing the number of the holes. It can be NULL if Holes is NULL.
[in]flagsThe 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]minDiameterReserved for future versions. Must be 0.
[in]maxDiameterReserved 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]sidSettings 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]sidSettings Collection ID.
[in]hPageHandle of the page containing the image to be rotated.
[in]RotationImage 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]sidSettings Collection ID.
[in]hPageHandle of the page which contains the source image.
[in]iiImgIndex to the image in the page.
[in]pSrcRectDimensions of the source area. NULL means: the whole image will be copied.
[in]RotationImage rotation mode to be applied as the area is copied. All the values of the IMG_ROTATE can be used except ROT_AUTO.
[out]lpImgAddress of a structure to get information about the output image area.
[out]lplpBitmapAddress 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]sidSettings Collection ID.
[in]wredWeight of the red component.
[in]wgreenWeight of the green component.
[in]wblueWeight 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:
  1. Set drop-out color weights to default (77,150,29).
  2. Detect skew (kRecDetectImgSkew)
  3. Set drop-out color weights
  4. Set slope and rotation (kRecSetImgDeskew, kRecSetImgSlope, kRecSetImgRotation)
  5. 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]sidSettings Collection ID.
[in]corrIf 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]sidSettings Collection ID.
[in]BWConversionSecondary 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]sidSettings Collection ID.
[in]BrightnessBrightness 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]sidSettings Collection ID.
[in]ConversionPrimary 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]sidSettings Collection ID.
[in]_ImgDeskewSelect deskewing mode.
Return values:
RECERR
Note:
See also Notes on Deskew and Orientation.
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]sidSettings Collection ID.
[in]bModeImage 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]sidSettings Collection ID.
[in]downsampleIf 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]hPageHandle of the page.
[in]FlagThe flag to set. See: IMG_FLAGS.
[in]bValueThe 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]sidSettings Collection ID.
[in]lineordLine 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]paddingPadding 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]ordOrder 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:
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]sidSettings Collection ID.
[in]ImgInvertImage 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]hPageHandle of the page containing the image.
[in]pPalArray 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]sidSettings Collection ID.
[in]resThe 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]hPageHandle of the page containing the image.
[in]DPIThe 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]sidSettings Collection ID.
[in]imgRotateImage rotation mode to be set. Possible values are: ROT_AUTO, ROT_NO, ROT_RIGHT, ROT_DOWN, ROT_LEFT.
Return values:
RECERR
Note:
See also Notes on Deskew and Orientation.
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]sidSettings Collection ID.
[in]SlopeSlope 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]sidSettings Collection ID.
[in]ImgStretchModeImage 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]sidSettings Collection ID.
[in]ThresholdThe 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]sidSettings Collection ID.
[in]preserveIf 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]sidSettings Collection ID.
[in]RetainColorThe 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]sidSettings Collection ID.
[in]pThumbnailThis 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]colorThis 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]sidSettings Collection ID.
[in]hPageHandle of the page which contains the image to be processed.
[in]iiImgIndex to the image in the page.
[in]pRectPointer to the structure defining the requested area of the image or NULL for the entire image.
[in]ImgRotationOrientation of the lines during reading. Possible values are all the values of the type IMG_ROTATE except ROT_AUTO.
[out]pBytesPointer 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]sidSettings Collection ID.
[in]pImgPointer 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]sidSettings 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]sidSettings Collection ID.
[out]phPageAddress 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]hPageHandle of the page.
[in]iiDstIndex of the destination image.
[in]iiSrcIndex of the source image.
[in]nPNumber of points in the buffer.
[in,out]pPointBuffer 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]sidSettings Collection ID.
[in]hPageHandle of the input page.
[in]iiImgIndex of the input image whose area should be transformed.
[in]pSrcRectRectangular area of the image to be transformed. NULL means: the whole image is transformed.
[in]pDstSizeSize 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]BitsPerPixelType 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]phPageOutPointer 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]sidSettings Collection ID.
[in]hPageHandle of the page containing the image(s) to be transformed.
[in]newsizeThe new size of the current image. The size is not changed if it is NULL.
[in]matrixThe 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]sidSettings Collection ID.
[in]hPageHandle of page containing the image(s) to be transformed.
[in]newsizeThe new size of the current image. The size is not changed if it is NULL.
[in]pOriginalArray of original points.
[in]pTransformedArray of transformed points.
[in]nPointsThe 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]sidSettings Collection ID.
[in]hPageHandle of the source page.
[in]iiImgIndex of the image in the source page to be transformed.
[in]pSrcRectRectangular area of the selected image to be transformed. NULL means the whole image is transformed.
[in]pDstSizeSize 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]phPageOutPointer 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]sidSettings Collection ID.
[in]pBuffPointer 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.