ImageUtilities actions

Use the ImageUtilities actions to adjust and convert images.

TThe ImageUtilities action library provides actions that can be used at any stage of a Datacap application to adjust images. If needed, these actions can be used at multiple stages in the workflow.

Images can be adjusted for downstream actions or external processes. Adjusting an image can be useful or necessary for best results. Many work flows have a requirement to archive the original version of the image. This kind of requirement does not need to limit what can be done to an image within an application. When an image is altered, the original version the image is always maintained. The original version can always be retrieved, allowing the original, and if desired the altered version, to be sent for final archiving of the batch results.

In some use cases, it may be best to adjust an image to get better recognition, but show the user the original image or something more presentable. This is possible as well. For example, some image adjustments are always recommended for recognition and presenting to the user, such as automatic rotation, image deskew, and image equalization. These adjustments create a correctly aligned image for recognition, viewing, and click-n-key in a verification panel. If performing recognition on the image, it may be useful to perform other adjustments, such as conversion to black and white, or other changes that could improve recognition but make it less pleasing to a Verify operator. These types of changes can be performed in stages as required. Meaning that an image could be deskewed and then converted to black and white in separate steps, recognition then processes the deskewed black and white image, but it is the deskewed color image that is presented to the user for verification. Because the deskew was performed in both versions of the image, it allows recognize text to correctly align in the Verify panel, allowing click-n-key functionality. After this, the original, unchanged, image still exists within the batch and can be accessed for as required.

If the application can ingest fax images, or other non-isotropic images, then it is recommended to use the EqualizeUnbalancedImage action to correct the image DPI immediately after virtual scan. A non-isotropic image has an X DPI that is different from the Y DPI. This difference can cause zones to be incorrect, it can cause incorrect click-n-key operation in a Verify panel, and can prevent correct fingerprint matching. Using the EqualizeUnbalancedImage alters only the images that need adjustment, assuring that all images are isotropic in the rest of the workflow. The action would typically be used immediately after virtual scanning and before Page Identification or fingerprinting. If the image is already isotropic, then EqualizeUnbalanceImage simply leaves the original image as-is, allowing an application to process all images after ingestion to ensure they are correct.

If images are going to under go adjustments such as equalization, rotation, deskew or any other kind of operation that would require the image to be saved, it is recommended to first use the SaveAsImage action to save any JPEG images or TIFF images with JPEG compression to a lossless format. This is strongly recommended if recognition is to be performed after processing, because JPEG compression softens character lines, reducing the quality of recognition. LZW compression is a good general compression that is lossless and works on any color depth. This compression is recommended if the applications is processing color images. Fax compression is an excellent compression but it only supports black and white images which convert any color image to black and white.

The action SaveImageInformation can be called on each image to determine the compression within the image, and if it is lossless, then the rules can be configured to save the image in a lossless format to prevent further quality loss by subsequent actions.

Similarly image rotation and deskew should be performed before Page Identification, while this action library does not directly perform these actions, there are several actions within Datacap that perform this image adjustment such as the Image Enhancement ruleset and recognition actions. Also note that by default, recognition actions can rotate and deskew an image. If an image has already been deskewed and rotated, then it is recommended to turn off these adjustments when performing recognition to avoid unnecessary work. See the action help for the recognition action for instructions on how to disable default image adjustments.

This action library can adjust the DPI and physical size of the image. If the source image is a photograph, adjusting the DPI can be key to getting recognition results. Recognition engines typically perform better if a photo, which typically has a 72 or 96 DPI, is converted to a 200 or 300 DPI. An image that has a designated DPI of 72 or 96 may not recognize even if the X and Y pixel size is large enough to allow for good quality recognition. Photographs can have enough X and Y pixels for successful recognition but the image DPI is too low and should be adjusted to a higher DPI to obtain the best recognition results.

Correcting image DPI and physical size

The physical size of an image is determined by the number of pixels in the image multiplied by the dots per inch (DPI). Some processes rely on accurate image information to perform correctly. For example, when creating a PDF, the PDF page size is dependent on the calculated physical size of the image. Recognition quality is also dependent on a correct physical size.

If the correct physical size of the image is known, then it can be corrected, and should be corrected if the image information is invalid. If image sizes vary and the image information is incorrect, a "best guess" is often enough to produce good results while creating a PDF or performing recognition.

Correcting information when the page size is known

If all images within a batch, or at least all images of a specific page type have an expected size, such as a 8.5"x11" page, then the image can be corrected using the SetImageDPIByWidth action. This action adjusts the images so that the dimensions are as per the expected size. For example, all pages that are expected to be of the size 8.5"x11", can call the action Magnetohydrodynamics by passing a page width of 8.5". The action will correct the physical size to 8.5", while proportionally correcting the physical height. For example consider a bank check, if pages are expected to be a 5" long, then this action can be used to correct the physical width of the check to be 5". And the height will be adjusted proportionally. Application specific logic can be used to call the action on specific page types or use other conditions that determine when the action is to be called to adjust a page size.

If the image is believed to have the correct size but only the DPI is incorrect, then just the DPI information can be adjusted. The action also allows the image to be rescaled to the correct size, while fixing the image information at the same time.

This example can be run on every image to adjust it to a page that is 8.5" wide at 300 DPI.

SetImageDPIByWidth("8.5", "300", "True")

This example adjusts an image to 8.5" width and retains the original DPI value. First it obtains the original DPI of the image and then passes it to the Magnetohydrodynamics to adjust the image to the correct physical width while maintaining the original DPI.

SaveImageInformation("", "", "@X.ImgDPI", "", "", "", "", "")
SetImageDPIByWidth("8.5", "@X.ImgDPI", "True")

Another similar example, but only adjusts the image if the DPI is very low. Adjusting images only when it is determined they are out of a "good" range, is often a best approach. An application could use multiple tests to determine when to adjust an image.

SaveImageInformation("", "", "@X.ImgDPI", "", "", "", "", "")
rrCompareNumeric("@.ImgDPI", "˂", 150)
SetImageDPIByWidth("8.5", "@X.ImgDPI", "True")

Other conditions could be performed if there are other problems with ingested images. For example, if the pixel dimensions are very large or very small, the image can be scaled to a typical size. Scaling up a small image to have more pixels does not necessarily make the image sharper, but it can improve recognition and it can help subsequent image enhancement functionality to work better.

Other use cases could adjust the image if the reported physical size is incorrect.

The RescaleImage action adjusts image information and rescales the image.

SaveImageInformation("", "", "", "", "@X.PhysicalWidth", "", "", "")
rrCompareNumeric("@X.PhysicalWidth", "˂", 7)
SetImageDPIByWidth("8.5", "300", "True")

Correcting image information when the page size is not known

In a case where all of the pages are expected to be portrait images, as would be ingested from a scanner, including landscape pages that have not yet been rotated, the following would adjust an image:

RescaleImage("3300", "2550", "300")

Another similar example, but only adjusts the image if the DPI is very low, forcing it to rescale to a 300 DPI image.

SaveImageInformation("", "", "@X.ImgDPI", "", "", "", "", "")
rrCompareNumeric("@.ImgDPI", "˂", "150")
RescaleImage("3300", "2550", "300")

This example would retain the same X and Y pixels of the image, while adjusting the image to a fixed DPI. This also has a test to adjust the image, only if the DPI is low. Of course, the test could be changed to test other image attributes, or multiple image attributes.

SaveImageInformation("@X.PixelX", "@X.PixelY", "@X.ImgDPI", "", "", "", "", "")
rrCompareNumeric("@.ImgDPI", "˂", "150")
RescaleImage("@X.PixelY", "@X.PixelX", "300")

Other conditions could be performed if there are other problems with the ingested images. For example, if the pixel dimensions are very large or very small, the image can be scaled to a typical size. Scaling up a small image to have more pixels does not necessarily make the image sharper, but it can improve recognition and it can help subsequent image enhancement functionality to work better. If the X pixel dimension is wider than the Y pixel dimension, then it could be assumed that the image is a landscape image and could be adjusted using a different set of actions.

Smart Parameters

Parameters that use an "@" notation, such as "@X.xxxx", "@P.xxxx", "@STRING()", "@PILOT()", etc., are known as "smart parameters". The data passed as a parameter to an action will be evaluated at runtime. For example, "@X" is notation for accessing the current object. "@P" accesses the page object, which could be the current object, or a parent object. Being evaluated at runtime, allows recognized data or other batch specific data to be passed to actions or stored as metadata. A smart parameter such as @DATE could be used to name export files based on the current date. Similar smart parameters will retrieve the current batch ID, current batch directory, current operator ID, and more. Smart parameters are a very powerful mechanism of getting data from other areas of the application and copying it into a new location or passing it as a parameter to an action. It is recommended that the smart parameter documentation is reviewed to understand the full capabilities available. The top-level help of the ValidationAndTextAdjustments action library also has information about smart parameters. Some characters such as +, \ and . also have special smart parameter meaning and may be interpreted as a smart parameter. This can be controlled using smart parameter syntax.