Working with Images
The basic scenarios of image processing work with images within the FRDocument object, which represents the document being processed.
To load images into the document, do one of the following:
- When creating the FRDocument object, use the CreateFRDocumentFromImage method of the Engine object.
- Add images to the created 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. Create this object by calling the IEngine::CreatePrepareImageMode function, then change its properties as necessary, and then pass it to a function that requires it.
Pages of the document provide access to the images via the IFRPage::ImageDocument property. Each open image in ABBYY FineReader Engine, each image in the so-called "internal format," is represented by the ImageDocument object, which includes 4 image planes. One image plane corresponds to one Image object:
- Black-and-white plane. It is the black-and-white copy of the source image. The copy is deskewed or non-deskewed, depending on the internal file preparation mode (see the description of the IPrepareImageMode::CorrectSkewMode property).
- Gray plane. This is the gray copy of the source image. The copy is deskewed or non-deskewed, depending on the internal file preparation mode (see the description of the IPrepareImageMode::CorrectSkewMode object). 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. The copy is deskewed or non-deskewed, depending on the internal file preparation mode (see the description of the IPrepareImageMode::CorrectSkewMode object). 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. It may be or may not be available in the file in the internal format. The availability of this preview image depends on the internal file preparation mode (see the description of the IPrepareImageMode::CreatePreview property).
Each image plane of the above-mentioned set is characterized by its own size and resolution. The size and resolution of black-and-white, gray, and color images are the same. Since image documents may consist of deskewed images, the ImageDocument object has a set of coordinate conversion functions. Use the ICoordinatesConverter::ConvertCoordinates function to 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. Remember that the recognition functions use the page received after image preparation (therefore, the page may be deskewed).
You can add an already created ImageDocument object to a document using the AddImageDocument method of the FRDocument object.
There are several ways to modify the image after opening: via the methods of the ImageDocument object, using the ImageModification object, and via the methods of the FRPage and FRDocument objects.
These objects provide 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 that are suitable for your scenario):
- To improve recognition quality:
- Crop image (use the CropImage method of the ImageDocument object)
- Enhance local contrast (use the EnhanceLocalContrast method of the ImageDocument object)
- Correct orientation (use the Transform method of the ImageDocument object with necessary parameters)
- Invert or mirror image (use the Transform method of the ImageDocument object with necessary parameters)
- Correct geometrical distortions (use the CorrectGeometricalDistortions method of the FRPage object)
- Correct skew (use the CorrectSkew method of the ImageDocument object)
- Split double page spread (use the SplitPages method of the FRDocument object)
- Remove garbage (use the RemoveGarbage method of the ImageDocument object)
- Remove noise (use the RemoveNoise method of the ImageDocument object)
- Remove motion blur (use the RemoveMotionBlur method of the ImageDocument object)
- Remove color objects (use the RemoveColorObjects method of the ImageDocument object; if you need to specify the color hues and/or save the removed objects as a separate image, use the RemoveColorObjectsEx method instead)
- Equalize brightness and make the background white (use the EqualizeBrightness method of the ImageDocument object)
- Smooth the image texture (use the SmoothTexture method of the ImageDocument object)
- Dither image (use the DitherImage method of the ImageDocument object)
Note that all these preprocessing methods are applied to an open image. You can make some modifications to the image earlier on the stage when it is being opened. Please, see the description of the PrepareImageMode object to know more about image preprocessing during the opening.
FineReader Engine provides functionality for additional image editing (inversion, stretch, etc.) via the ImageModification object. To perform modification, do the following:
- Create an ImageModification object with the help of the CreateImageModification method of the Engine object.
- Specify the necessary parameters.
- Call the IImageDocument::Modify method that takes the ImageModification object as an input parameter. The actual change takes place only when you call this method.
- Save the changes using the IImageDocument::SaveModified method.
Important! Modifications to the image are not saved until the IImageDocument::SaveModified method is called. If the ImageDocument object is released before a call to this method, the modifications are not saved.
You can save the current image plane into an image file in a specified format using the WriteToFile method of the Image object.
Note that though 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.
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.