SaveImageAs

Saves a new copy of the image, allowing adjustment of image type, color, depth, and compression.

Syntax

bool SaveImageAs ()

Parameters

NewFileType: String. The file type of the new image. Supported types: TIF, JPG, BMP, PNG.

NewColorDepth: String. The new color depth for the image. Values: 0, 1, 8, 24.

0: Preserve the same color depth as the source image. If blank, 0 is used as the default value. If the source image is a 32 bit color image, then the maximum bit depth of the saved image is 24 bits per pixel.
1, 8, 24: The new bits per pixel of the saved image.

Palette: String. The color palette to use for the saved image. The following values are accepted:

Optimized: A palette with the colors optimized for the image. If not specified, this is the default value.
Fixed: A fixed color palette.
Gray: A grayscale palette.

Dither: String. The dot pattern used when reducing the color depth of an image. The following values are accepted: Binarize1, Binarize2, FS, None, Optimized, and Ordered.

Binarize1: An optimized conversion to remove background information, leaving foreground information, such as dark text. This is usually the best setting to convert an image or photo to black and white to be used for text recognition. No dithering is performed. This results in a black and white image. If dither is not provided, then this is the default method for saving 1 bit images.
Binarize2: Similar to Binarize1, but may be slightly faster. No dithering is performed. This results in a black and white image.
FS: Uses the Floyd-Steinberg algorithm to dither a color image into black and white. Do not use this setting if the image will be subsequently recognized. Dither should only be used to keep a "shaded" look to the image and when the image will not be subsequently used in a recognition step.
None: No dithering is performed. This is similar to the Binarize methods, but may not yield results as good as Binarize1 for performing text recognition. Unlike Binarize, this setting is not limited to black and white images.
Optimized: The image engine determines how to dither the image. A dithered image produces a black and white image that simulates a grayscale picture, similar to a newspaper. This method is recommended to convert a photo to black and white with the intention to retain the photographic image while converting it to a black and white image. This is the default value if the target color depth is greater than 1. If performing recognition on the image, instead use Binarize1 to convert the image to black and white or use "None" when down converting to 24 bit or 8 bits per pixel.
Ordered: An alternative method of converting a color image to a black and white dithered photo. Again, it is not recommended to use this setting if the image will be subsequently recognized.

BackupSuffix: String. When the current image is saved, the original image is also retained. If the new saved image has the same name as the original source image, the source image is saved by adding a suffix to the name. By default, the suffix ".original" is added to the file name. For example, if the source image name is "TM000001.tif" then the original image is saved as "TM000001.original.tif" and the new image is saved as "TM000001.tif". If desired, this suffix can be changed using this parameter. For example, passing the value ".backup" saves the original image as "TM000001.backup.tif". If the source image is of a different type, such as "TM000001.jpg" and the new image is of a different type, such as "TM000001.TIF", then the source image name does not conflict with the new saved image name and the source image name is not changed. If it is desired to change the name of the source image in this case, then the FileIO actions can be used to rename the original file as desired.

DeleteOriginal: String. "True" or "False". If this parameter is set to "True", then the original image is not saved in the batch. If this parameter is set to "False", then the original image is retained, keeping it available for later use within the batch, such as for archiving. If this parameter is not provided, then it defaults to "False" and the original image is saved.

Smart parameters are supported for all parameters.

Returns

True, if the operation is successful, else False if any error occurred.

Level

Page level only, and the page must refer to a valid single page image file.

Details

This action updates the current image associated with the page object, changing any one or all of these image attributes:

Image Format
Compression type
Color depth / Bits per pixel

Input formats: BMP, DIB, EMF, GIF, JPEG, JPEG2000, PNG, TIF, WMF.

Output formats: BMP, PNG, JPEG, TIF.

The current image can be saved as the same file type, changing just the compression or color depth of the image. For example, a TIF with JPEG compression can be re-saved as a TIF with LZW compression. The current image can also be changed to a new file type such as converting a JPEG image to a TIFF image.

The source image can have a color depth up to 32 bits per pixel. The image can be saved in a color depth up to 24 bits per pixel. Some Datacap actions have specific color depth requirements, this action can be used to adjust the current image to different color depths as required by subsequent actions and rulesets.

If the final image file type is the same as the source image file type, the action first backs up the original image, giving it a unique name by adding the suffix ".original" to the file name. For example, if the source file name is "TM000001.tif" and the image is being saved as a TIF, then the original file is saved as "TM000001.orignal.tif" and the file "TM000001.tif" is the name of the new updated file.

The image file associated with the current page object can be converted to one of these file types: BMP, PNG, TIF, and JPEG. Bitmap (BMP) images are always saved without compression, which can make them large. Portable Network Graphics (PNG) use a loss less compression that works on a 1 bit, 8 bit or 24 bit image.

The actions SaveImageSettingsTIFF and SaveImageSettingsJPEG can be called prior to this action to adjust the file format used to save the image when saving as a TIF or JPG image. For example, the default file compression for TIF images is LZW. By first calling SaveImageSettingsTIFF, the default compression can be changed for when the SaveImageAs action saves a file as a TIFF. For example, if converting to a black and white image, Group 3 or Group 4 can be configured as the compression type as it is an efficient and lossless method for black and white images.

If an application is ingesting JPEG images or TIF images with JPEG compression, and these images are to be used for recognition, it is highly recommended to convert the image to a lossless format, such as a TIF with LZW compression, immediately after the images are ingested into a batch. Subsequent actions can then operate on the new TIF image using lossless compression. The original version of the image is always available, if necessary, for viewing in a Verification panel or for exporting at the end of the batch. JPEG compression is intended for photographs, not for images that contain text to be recognized. JPEG compression makes crisp lines on letters, fuzzy, reducing the quality of the recognition. As the image is further manipulated, such as with image enhancement, rotation, etc., and saved again with JPEG compression, additional quality is lost with each save, even if compression is set to a high quality.

It may be useful to use the action SaveImageInformation along with this action. SaveImageInformation reads image attributes and stores the values in the DCO. Application rules can be configured to act on this information. For example, if an image has a color depth greater than 24 bits per pixel, then the rules could call SaveImageAs to reduce the color depth of the image.

The SaveImageInformation action can also be used to obtain the compression used within the image. For example, rules can be arranged to check the current image compression type and if the compression type is "JPEG", then the rules can call SaveImageAs only on those images to save them with a lossless compression and if the image already has a lossless compression, then the image can be left as-is.

Example 1:

SaveImageInformation("","","","","","","","@X.ImgCompression")
rrCompareCase("Jpeg", "@X.ImgCompression", "False")
SaveImageAsSettingsTIFF("LZW")
SaveImageAs("TIF","0","","","","")

This example checks to see if the current TIFF image is using JPEG compression. If it does have JPEG compression, the actions configure the compression for saved TIF images to LZW using the action SaveImageAsSettingsTIFF. The example is shown in the same rule as the rule for SaveImageAs. If the settings are intended to be the same for all pages, then it would be more efficient to place SaveImageAsSettingsTIFF in a rule attached to the batch open event. That would allow the action to be called only once instead of over and over for each page.

The SaveImageAs action converts the current page image to a TIF using LZW compression. It does not matter if the source image is a TIF or a different image type, such as JPEG or PNG. The parameter of 0 retains the same color depth as the original image. If the image was black and white, it stays a 1 bit black and white image. If the source image was 24 bit color, it is saved as 24 bit color. This example is a good way to convert images that may be saved using a lossy compression, such as JPEG, to a lossless compression to limit further degradation of quality caused by a lossless compression.

Example 2:

SaveImageAsSettingsJPEG("100","False","True")
SaveImageAs("JPEG","0","Optimized","Optimized",".Old","False")

This example converts the current image to a JPEG image. Although the color depth parameter is set to "0", which means to retain the original color depth, JPEG images can only be saved as 8 bit grayscale or 24 bit color. If the source image is 1 bit, then it is upconverted. While it still looks black and white, it is converted to a 24 bit color depth. This example also uses a custom extension, ".Old", to back up the original file name, should the new file name and the old file name evaluate to the same name.

Again, while this example shows the SaveImageAsSettingsJPEG being called in the same rule function just prior to SaveImageAs, if all pages are going to have the same settings, then this action can be called at the document or batch level and the setting will stay in effect for the remainder of the current task profile. Calling this action at a higher level avoids unnecessarily calling this action over and over for each page object. If each page object may need different parameters when saved, then calling the action with each page would be necessary.

It is recommended to save as a JPEG or a TIF with JPEG compression if processing photos are not to be used for text recognition. If performing text recognition on an image, or image enhancements, it is recommended to first convert to a lossless compression and do not use the JPEG image format.

Example 3:

rrSet("Group4", "@X.Compression")
rrSet("TIF", "@X.NewFileType")
rrSet("True", "@X.DeleteOriginal")
SaveImageAsSettingsTIFF(@X.Compression)
SaveImageAs("@X,NewFileType","1","","","","@X.DeleteOriginal")

This is another example that converts the current page image to a TIF, regardless of the original format. It also converts the image to a black and white image with Group 4 fax compression, which is an efficient and lossless black and white compression.

This example demonstrates using smart parameters to pass values to the actions. The example illustrates how a variable, New Filetype, is passes as a smart parameter to the action at runtime. The value of the variable "NewFileType" will be obtained and used as the input parameter. In a realistic example, it would be likely that some earlier rule or action would have set the value to the DCO variable "NewFileType" prior to calling the action. For example, a value could have been previously set in a field or be data that was recognized into a field and then the reference to a field passed as the parameter, using the field's current runtime value as input to the action. Another approach could have the values configured in the setup DCO, which can be set within Datacap Studio, so they pre-exist for the object and then the actions pull the value at runtime from a pre-configured variable.

Example 4:

SaveImageInformation("","","","","","","@P.BitDepth","")
rrCompare("@P.BitDepth", "32")
SaveImageAsSettingsTIFF("LZW")
SaveImageAs("tif", "24", "", "", ".prebitdepth", "False)

This example runs on a page object and if the image is a 32 bit color image, it reduces the color depth of the image associated with the page. It is required that the associated page file is an image. The series of steps is useful because some actions do not support 32 bit color images. If the current image is 32 bit color, the image is saved as a TIF image with a color depth of 24 bits and backup the original image is saved by appending ".prebitdepth" to the file name. The LZW compression is used because it is a lossless compression and it supports any color depth. If the current image is 24 bits or less, then the rrCompare will return false causing the action flow to stop in this current function and jump to the next function, if one exists. Images of 24 bits or lower are left unchanged by this series of actions.