ImageDocument Object (IImageDocument Interface)

This object corresponds to an open image, or "image document". Its attributes reflect the attributes of an image. ImageDocument object is a root for a collection of Image objects, or "image planes". Each image document includes 4 "image planes": black-and-white, gray, color and preview. They are accessible via corresponding properties.

The object contains a number of image preprocessing methods. Some of these methods are suitable only for photos, others may be used for all types of documents. Some of the methods increase recognition quality, others improve only visual representation of images, but may decrease recognition quality. The latest should be used only after recognition. Please, read carefully the description of each method to find out whether the method could be used in your scenario. Below you can find the order, in which we recommend using image preprocessing methods (use only those methods from the list which are suitable for your scenario):

To improve recognition quality:

Crop image
Enhance local contrast
Correct orientation (use the Transform method with necessary parameters)
Invert or mirror image (use the Transform method with necessary parameters)
Correct geometrical distortions (use the CorrectGeometricalDistortions method of the FRPage object)
Correct skew
Split double page spread (use the SplitPages method of the FRDocument object)
Remove garbage
Remove noise
Remove motion blur
Suppress color objects
Remove color objects

To improve image appearance:

Equalize brightness and make the background white
Smooth image texture
Dither image

Note that all these preprocessing methods have to be applied to an open image. Some modifications of the image can be applied earlier, in the process of opening it. Please see the description of the PrepareImageMode object to know more about image preprocessing during opening.

The ImageDocument object is a so-called "connectable object." It may be declared WithEvents in Visual Basic. For a C++ user, this means that it supports the IConnectionPointContainer interface. To receive notification events during processing, a C++ user should create an object derived from the IImageDocumentEvents interface, then set up the connection between it and the events source implemented in the ImageDocument object by standard COM means.

The methods of the ImageDocument object report information about page processing progress through special outgoing interfaces. These interfaces are IImageDocumentEvents (for C++) and the dispinterface DIImageDocumentEvents (for Visual Basic). It should be noted that Visual Basic users should not care for details of implementing event interfaces, as this development platform provides easy means for handling them.

Properties

Name	Type	Description
Application	Engine, read-only	Returns the Engine object.
Main attributes
BlackWhiteImage	Image, read-only	Provides access to the black-and-white image plane of the current ImageDocument object.
ColorImage	Image, read-only	Provides access to the color image plane of the current ImageDocument object.
GrayImage	Image, read-only	Provides access to the gray image plane of the current ImageDocument object.
PreviewImage	Image, read-only	Provides access to the preview image plane of the current ImageDocument object. An open image contains this image plane, only if IPrepareImageMode::CreatePreview property was set to TRUE during image preparation. Otherwise, the object accessed through this property is NULL.
Id	int, read-only	Stores the ID of the image document.
ImageColorType	ImageColorTypeEnum, read-only	Each color plane of the image document is characterized by its own color type. This property specifies the color type for the whole image document as the maximum of the corresponding values for its color planes (black-and-white, gray, color).
IsInMemory	VARIANT_BOOL, read-only	Specifies if the image document is stored in memory only or it is also represented as a folder on disk. Note: After the call to the SaveTo method the value of this property is not changed. You need to re-load the image document by the call to the LoadImageDoc method.
Path	BSTR, read-only	Stores the path to the folder with object's internal representation on disk. The property contains an empty string, if the value of the IsInMemory property is TRUE. Note: After the call to the SaveTo method the value of this property is not changed. You need to re-load the image document by the call to the LoadImageDoc method.
CoordinatesConverter	CoordinatesConverter, read-only	Returns the CoordinatesConverter object that contains information about pixel coordinates in the current modification state. This property is useful whenever you need to convert coordinates between two states during image processing.
Image modification
ImageRotation	RotationTypeEnum, read-only	Specifies rotation that was performed upon the current ImageDocument object from the opening or from the last call to the SaveModified method.
ImageWasInverted	VARIANT_BOOL, read-only	This property set to TRUE specifies that the image colors were inverted after opening or after the last call to SaveModified method.
ImageWasMirrored	VARIANT_BOOL, read-only	This property set to TRUE specifies that the image was mirrored around the vertical axis after opening or after the last call to SaveModified method.
IsModified	VARIANT_BOOL, read-only	Specifies if any modifications were made upon the ImageDocument object since it was loaded in memory or from the last call of the SaveModified method. Information about modifications is available through the ImageWasInverted, ImageWasMirrored and ImageRotation properties. Note: This property will not reflect any modifications made during image opening, since ImageDocument is only created after those modifications are completed.
IsSkewCorrected	VARIANT_BOOL, read-only	This property provides information about whether the image skew was fully corrected during opening, preprocessing or the CorrectSkew method call. The tangent of skew angle which was corrected is stored in the SkewAngle property.
SkewAngle	double, read-only	Stores the tangent of skew angle that was detected for the image and corrected during opening, preprocessing or the CorrectSkew method call. If the skew angle is negative the image is rotated clockwise; if the angle is positive the image is rotated counter-clockwise. The image can be rotated around any point. The size of the deskewed image is always larger than the size of the original image. Note: When you perform further modifications of the image, this property value is reset to 0. Save the value of corrected skew angle, if you need it, before calling any other methods to edit the image.
Source file information
HasTextualContent	VARIANT_BOOL, read-only	Tells you if the ImageDocument object was created from a file which contains text. For example, PDF files can have text layer.
IsPhoto	VARIANT_BOOL, read-only	Tells you if the ImageDocument object was created from a file which is a photo. This property depends on the value of PhotoProcessingMode property of the PrepareImageMode object used during the image opening: if that property was set to PPM_TreatAsNonPhoto, this property will return FALSE. If that property was set to PPM_TreatAsPhoto, this property will return TRUE. Note: This property is set automatically to TRUE only if the image contains some EXIF information. Otherwise it must be set manually.
SourceImageFileFormat	ImageFileFormatEnum, read-only	Provides information about format of the source image file of the current ImageDocument object. If this information is not available or image was received from scanner, the value of this property is IFF_UnknownFormat.
SourceImageScannerInfo	BSTR, read-only	Provides information about scanner used to acquire the image. If information about source image parameters is not available or image was received from file, the value of this property is empty string.
SourceImageScanThreshold	int, read-only	Provides information about scanning intensity threshold for the current ImageDocument object. If information about source image parameters is not available or image was obtained from file, the value of this property is -1.
SourceImageXResolution	int, read-only	Provides information about horizontal resolution of the source image of the current ImageDocument object. If information about source image parameters is not available, the value of this property is 0.
SourceImageYResolution	int, read-only	Provides information about vertical resolution of the source image of the current ImageDocument object. If information about source image parameters is not available, the value of this property is 0.

Methods

Name	Description
ApplySigmaFilter	This method applies a noise reducing filter to the image. It is mostly useful for photographs.
ChangeResolution	Changes resolution of the image.
CorrectSkew	Corrects a skew of the image.
CropImage	Finds the edges of a document on the image and then crops the image.
DitherImage	Dithers the image using either Floyd–Steinberg, or Bayer (ordered) dithering algorithm.
EnhanceLocalContrast	Increases the local contrast of the image.
EqualizeBrightness	Equalizes the image brightness. This method can be used for gray and color images only.
FindBlackSquares	Finds black squares on the image.
GetTextBackgroundColor	Detects colors of text and background in the specified rectangle on image.
Modify	Allows you to modify the image. This method provides advanced modifications as compared with the Transform method.
RemoveColorObjects	Removes specified color objects from the whole image or its parts. This method can be used for color images only.
RemoveColorObjectsEx	Removes all color objects of the specified hues from the image and replaces them with the specified color. The removed objects can be saved into a separate image.
RemoveGarbage	Removes garbage (excess dots that are smaller than a certain size) from the image.
RemoveMotionBlur	Removes motion blur from the image.
RemoveNoise	Reduces the noise on the image.
SaveImageRegionTo	Saves the parts of the image into a folder on disk. The saved image is in ABBYY FineReader Engine internal format.
SaveModified	Saves all modifications that were performed upon the current ImageDocument object into the folder on disk.
SaveTo	Saves the contents of the ImageDocument object into a folder on disk. The image is saved in ABBYY FineReader Engine internal format.
SaveToFile	Saves the contents of the ImageDocument object into a file.
SaveToMemory	Saves the contents of the ImageDocument object into the global memory.
SmoothImage	Allows you to smooth the image. This method can be used for gray and color images only.
SmoothTexture	Smoothes the image using a nonlinear filter. Useful for images with texture. This method can be used only for gray and color images which measure no less than 3 pixels in each dimension.
Transform	Applies a limited set of transformations to the image.