ImageDocument Object (IImageDocument Interface)

ImageDocument object (IImageDocument interface) in the ABBYY FineReader Engine API — Represents an open image; root of the four image planes (black-and-white, gray, color, preview) and exposes a full suite of image-preprocessing methods to improve recognition quality or visual representation.

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:
  1. Crop image
  2. Enhance local contrast
  3. Correct orientation (use the Transform method with necessary parameters)
  4. Invert or mirror image (use the Transform method with necessary parameters)
  5. Correct skew
  6. Split double page spread (use the SplitPages method of the FRDocument object)
  7. Remove geometrical distortions
  8. Remove garbage
  9. Remove noise
  10. Remove motion blur
  11. Suppress color objects
  12. Remove color objects
• To improve image appearance:
  1. Equalize brightness and make the background white
  2. Smooth image texture
  3. 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 and PagePreprocessingParams objects to know more about image preprocessing during opening.

The ImageDocument object is a so-called “connectable object.” For Visual Basic in FRE for Windows, it may be declared WithEvents. For C++ (all supported operating systems), this means that it supports the IConnectionPointContainer interface. To receive notification events during processing, C++ users should create an object derived from the IImageDocumentEvents interface and do the following:

• In Linux and macOS: advise the object to the ImageDocument object by calling the AdviseFREngineObject global function.
• In Windows: set up the connection between the object and the events source implemented in the ImageDocument object by standard COM means.

In Windows: 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.
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. 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. 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
HasUnsavedData	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.
ImageRotation	RotationTypeEnum, read-only	Specifies rotation that was performed upon the image since opening.
ImageWasInverted	VARIANT_BOOL, read-only	This property set to TRUE specifies that the image colors were inverted since opening.
ImageWasMirrored	VARIANT_BOOL, read-only	This property set to TRUE specifies that the image was mirrored around the vertical axis since opening.
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. 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.
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.
CorrectShadowsAndHighlights	Corrects excessive shadows and highlighting on the image.
CorrectSkew	Corrects the image skew.
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.
GetPreviewImage	Provides access to the 94 \* 60 preview image plane of the current ImageDocument object. If the preview of this size has not been created yet, it will be created during this call, which will take some time.
GetPreviewImageSpecificSize	Provides access to the preview image plane of the current ImageDocument object and lets you specify the size. If the preview of this size has not been created yet, it will be created during this call, which may take some time.
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.
RemoveGeometricalDistortions	Removes the geometrical distortions of the image (such as curving lines near the edge of a page).
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 Note: Windows only.	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.

Related objects

Object Diagram

Output parameter

This object is the output parameter of the following methods LoadImageDocFromFile, LoadImageDocFromMemory (Windows only), LoadImageDoc, OpenBitmap, OpenDib, OpenBitmapBits, OpenImageFileFromMemory of the Engine object.

Input parameter

This object is passed as an input parameter to the following methods:

• AddImageDocument method of the FRDocument object
• SetImageData method of the TrainingImage object

Samples

The object is used in the code samples:

Linux: CommandLineInterface and BCR

macOS: Business Card Recognition

Windows: CommandLineInterface; and demo tools: Engine Predefined Processing Profiles

See also

IImageDocumentEvents

Working with Images

Working with Connectable Objects

Working with Properties