ClipFieldToNewImage

Clips the field on the Image file to a separate Image file containing only the image from field's coordinates.

Syntax

bool ClipFieldToNewImage ()

Parameters

NewImagePageType: String. The Page Type that is to be assigned to the Image file containing the clipped field and its value. This should be a page type that is meaningful within the application.

NewImageStatus: String. The Page Status to be assigned to the new DCO page object that is created.

Smart parameters are supported.

Returns

False if either parameter is invalid or if the new page cannot be created, otherwise True.

Level

Field level only.

Details

This action creates a new DCO page object. The image associated with the new page object is determined by the zone coordinates of the current field object, clipping the source page image to contain only the section defined by the current field's zone coordinates. The new DCO page object is added to the end of the current parent document object for the page that contains the field that is clipped.

This action does not make any changes to the current field; It simply uses the field zone coordinates to define the boundaries for the new page.

The new page object that is created from the image segment, is assigned the initial page type and status that are provided as parameters to this action.

The name of the new image file is based on the name of the source image file by adding a two character suffix to the file name. "_01" is the suffix of the first new page. For example, if the source page image name is TM000001.tif, the name of the first new page will be "TM000001_01.tif". The suffix is then incremented using an alpha-numeric pattern of 0-9 and a-z as additional fields from that same page are clipped. The suffix is incremented "_02", "_03", etc., until "_09" is reached. From that point, alphabetic characters are added such as "_0a", "_0b", with the final suffix of "_zz". If more fields are clipped from the current page than that supported by the naming pattern, the subsequent pages are not be created and the action returns false.

The new page object has the following DCO property variables created:
  • SourcePage: The ID of the source page.
  • SourceImage: The path to the parent image that was clipped for this page's image segment.
  • SourceField: The ID of the field that was used to determine the boundaries of the image.
  • SourceValue: The text value, if any, of the source field.

If the current field does not have valid zone coordinates, then a new page is not created. The field's zone values must be loaded with an action like ReadZonesFPX or ReadZones prior to using this action.

The source page type can be TIFF, PNG, BMP or JPEG. If recognition is performed on the image, it is recommended to avoid using a compression, such as JPEG, which can reduce the quality of text recognition. The new image that is associated with the new page, is of the same type and of same compression as of the source page. Actions such as "SaveImageAs" can change type of an image and the compression used within an image. The following example creates a new page that is a child of the parent document object. The type of the new page is "Trailing_Page" and has an initial status of "0", which means "OK" or "No Error".
ClipFieldToNewImage("Trailing_Page", "0")
The following example uses smart parameters to get the type and status for the new page. In this case, the new page will have the same type and status of the parent page for the current field.
ClipFieldToNewImage("@P.TYPE", @P.STATUS)