ImageModification Object (IImageModification Interface)

ImageModification object (IImageModification interface) in the ABBYY FineReader Engine API — Stores image-modification parameters for IImageDocument.Modify: clip, paint, invert, replace-black-pixels, replace-white-pixels, remove-garbage regions, plus stretching.

This object is used to store parameters of image modification. Method IImageDocument::Modify that is used to modify an image, together with some other methods, takes a reference to this object as an input parameter. The ImageModification allows a wide range of operations upon an image, such as stretching, setting clip regions, inversion regions, paint regions, replace pixels regions, remove garbage regions. The image is modified as follows:

• The color of text and the size of garbage in regions is determined.
• Image part inside the clipping regions is cut.
• “Paint” regions are filled in with the corresponding color.
• Colors inside the “invert” regions are inverted.
• Black dots inside the “replace black pixels” regions are replaced with the dots of the corresponding color.
• White dots inside the “replace white pixels” regions are replaced with the dots of the corresponding color.
• The garbage inside the “remove garbage” regions is cleaned up. This modification can be applied only to the black-and-white image plane.
• Image is stretched with the stretch ratio defined by the StretchRatio property.

All regions that are added inside this object should not exceed the bounds of the image rectangle.

The ImageModification object is a persistent object. This means that the object’s current state can be written to persistent storage. Later, the object can be re-created by reading the object’s state from the persistent storage. The following methods provide persistence of the object:

Linux: SaveToFile, and LoadFromFile

Windows: SaveToFile, LoadFromFile, SaveToMemory, and LoadFromMemory.

Properties

Name	Type	Description
Application	Engine, read-only	Returns the Engine object.
StretchRatio	double	Specifies the stretch ratio to apply to the image. By default, this property is 1.0 that corresponds to no stretch.

Methods

Name	Description
AddClipRegion	Adds new clipping region to the internal array of clipping regions.
AddInvertRegion	Adds new inversion region to the internal array of inversion regions.
AddPaintRegion	Adds new paint region to the internal array of paint regions.
AddReplaceBlackPixelsRegion	Adds new “replace black pixels” region to the internal array of “replace black pixels” regions.
AddReplaceWhitePixelsRegion	Adds new “replace white pixels” region to the internal array of “replace white pixels” regions.
ClearClipRegions	Clears the internal array of clipping regions.
ClearInvertRegions	Clears the internal array of inversion regions.
ClearPaintRegions	Clears the internal array of paint regions.
ClearReplaceBlackPixelsRegions	Clears the internal array of “replace black pixels” regions.
ClearReplaceWhitePixelsRegions	Clears the internal array of “replace white pixels” regions.
CopyFrom	Initializes properties of the current object with values of similar properties of another object.
LoadFromFile	Restores the object contents from a file on disk.
LoadFromMemory	Restores the object contents from the global memory. Windows only.
SaveToFile	Saves the object contents into a file on disk.
SaveToMemory	Saves the object contents into the global memory. Windows only.

Output parameter

This object is the output parameter of the CreateImageModification method of the Engine object.

Input parameter

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

• WriteToFile, EstimateBitmapSize (Win), GetBitmap (Win) of the Image object,
• Modify of the ImageDocument object.

Samples

C# code

int splitStartPosition;
int splitEndPosition;
bool isVerticalSplit;
FREngine.IFRDocument frDoc;
FREngine.IFRPage page;
// Split the image of a document page in two pages
// Image dimensions
int width = page.ImageDocument.ColorImage.Width;
int height = page.ImageDocument.ColorImage.Height;
// Duplicate page
frDoc.AddPage(page);
FREngine.IFRPage secondPage = frDoc.Pages[frDoc.Pages.Count - 1];
// Crop first and second pages
FREngine.IImageModification firstModification = engine.CreateImageModification();
FREngine.IRegion firstClipRegion = engine.CreateRegion();
FREngine.IImageModification secondModification = engine.CreateImageModification();
FREngine.IRegion secondClipRegion = engine.CreateRegion();
if (isVerticalSplit)
{
 firstClipRegion.AddRect(0, 0, splitStartPosition, height - 1 );
 secondClipRegion.AddRect(splitEndPosition, 0, width - 1, height - 1);
}
else
{
 firstClipRegion.AddRect(0, 0, width - 1, splitStartPosition);
 secondClipRegion.AddRect(0, splitEndPosition, width - 1, height - 1);
}
firstModification.AddClipRegion(firstClipRegion);
page.ImageDocument.Modify(firstModification);
secondModification.AddClipRegion(secondClipRegion);
secondPage.ImageDocument.Modify(secondModification);

See also

Working with Images

Working with Properties