Working with Images
ABBYY FineReader Engine works with images by loading them into an FRDocument object, which represents the document being processed.
Image opening
To load images into the document, do one of the following:
- Use the CreateFRDocumentFromImage method of the Engine object to create an FRDocument object.
- Add images to an existing FRDocument object from a file. Use the AddImageFile, AddImageFileFromMemory, AddImageFileFromStream, AddImageFileWithPassword, or AddImageFileWithPasswordCallback method.
All these methods receive as a parameter the PrepareImageMode object, which allows you to specify different parameters of image preprocessing. Call the IEngine::CreatePrepareImageMode method to create this object, change its properties as necessary, and then pass it to one of the methods mentioned above.
You can also add an existing ImageDocument object (for example, one loaded from a file in internal format) using the AddImageDocument method of the FRDocument object.
ImageDocument structure
Once loaded into the document, the image of each page can be accessed via the IFRPage::ImageDocument property. Each open image in ABBYY FineReader Engine is represented by an ImageDocument object. The ImageDocument stores the image in the so-called "internal format," which includes 4 image planes, represented by Image objects:
- Black-and-white plane. It is the black-and-white copy of the source image.
- Gray plane. This is the gray copy of the source image. If the source image was black-and-white, this page is the same as the black-and-white plane.
- Color plane. This is the color copy of the source image. If the source image was black-and-white, this page is the same as the black-and-white plane; if it was gray, this page is the same as the gray plane.
- Preview. A small color image used for displaying a preview image in the user interface. The preview is created at the call to the GetPreviewImage or GetPreviewImageSpecificSize method. Any modification of the image, automatic or manual, may reset the created preview, and it will have to be created again.
The size and resolution of black-and-white, gray, and color images are the same. The preview image is usually smaller.
The images may be deskewed during image opening. To correlate the coordinates on the original image with the coordinates after opening or after additional modifications, use the CoordinatesConverter object. It stores the state of coordinates at the moment when it was obtained. You can use this object to convert the pixel coordinates between any two stages in the image processing. For example:
- Get this object using the IImageDocument::CoordinatesConverter property directly after image opening, during which image skew was corrected.
- After other modifications, obtain another instance of this object from the ImageDocument.
- Now you can convert pixel coordinates between the initially deskewed image plane and the modified image plane by applying the ConvertCoordinates method twice:
- Convert from the deskewed image plane to the original using the first instance of the CoordinatesConverter.
- Convert the result from the original image plane to the modified image plane using the second instance of the CoordinatesConverter.
The same method lets you convert pixel coordinates from one of the full-size image planes to the preview image plane and back. The coordinates of pixels on the black-and-white, gray, and color image planes are the same.
Important! An image modification, automatic or manual, may reset the preview image plane created earlier, and you will not be able to convert coordinates to or from that preview. Before converting coordinates, call the GetPreviewImage method again if the image was modified.
Image modification
Important! The automatic preprocessing mechanisms are best to prepare the image for OCR. The program determines image origin and document type, detects incorrect orientation, resolution, or image skew, and takes all this data into account to improve the image. We recommend that you only perform additional image modifications if after automatic preprocessing you are not satisfied with the result.
Modifications during image opening are managed by the PrepareImageMode object.
After opening, the image can be modified using:
- Methods of the ImageDocument object
- The ImageModification object, passed to the IImageDocument::Modify method
- Methods of the FRPage and FRDocument objects
Image saving
You can save the current image plane into an image file in a specified format using the WriteToFile method of the Image object.
ABBYY FineReader Engine also provides functionality for saving several images into a single image file. To save a multi-page image file, use the MultipageImageWriter object:
- Create a MultipageImageWriter object using the CreateMultipageImageWriter method of the Engine object.
- Add images to the end of the multi-page image file using the AddPage method of the MultipageImageWriter object. Each image is added as a single page.
- Before the newly created image file can be used, all the references to the MultipageImageWriter object must be released.
Note that although the ImageDocument object provides a set of saving methods (SaveTo, SaveToFile, SaveToMemory), these methods cannot be used for saving an image in an external format. These methods save the contents of the ImageDocument object in the ABBYY FineReader Engine internal format, which cannot be viewed in any external program.
See also
11/7/2025 12:48:30 PM