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." 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.
|
| 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.
|
| 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.
|
| 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.
|
| 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.
|
| 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
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:
- AddImageDocument method of the FRDocument object
- SetImageData method of the TrainingImage object
Samples
The object is used in the code samples: CommandLineInterface, BCR.
See also
03.07.2024 8:50:25