Chinese Simplified (简体中文)

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:
    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 geometrical distortions (use the CorrectGeometricalDistortions method of the FRPage object)
    6. Correct skew
    7. Split double page spread (use the SplitPages method of the FRDocument object)
    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 object to know more about image preprocessing during opening.

The ImageDocument object is a so-called "connectable object." This means that it supports the IConnectionPointContainer interface. To receive notification events during processing, you should create an object derived from the IImageDocumentEvents interface, then advise it to the ImageDocument object by the call to the AdviseFREngineObject global function.

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.
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, LoadImageDoc, OpenBitmap, OpenDib, OpenBitmapBits, OpenImageFileFromMemory of the Engine object.

Input parameter

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

Samples

The object is used in the code samples: CommandLineInterface, BCR.

See also

IImageDocumentEvents

Working with Images

Working with Connectable Objects

Working with Properties

7/3/2024 8:50:25 AM

Usage of Cookies. In order to optimize the website functionality and improve your online experience ABBYY uses cookies. You agree to the usage of cookies when you continue using this site. Further details can be found in our Privacy Notice.