Image - Overlay
Declaration
<AMIMAGE ACTIVITY="overlay" MATCHCASE="YES/NO" SUBFOLDERS="YES/NO" KEEPFOLDERSTRUCT="YES/NO" ARCHIVETURNOFF="YES/NO" OVERWRITE="YES/NO" ISNEWER="YES/NO" ONLYIFEXIST="YES/NO" OVERWRITEREADONLY="YES/NO" OVERWRITEHIDDEN="YES/NO" EXCLUDE="text" RE="YES/NO" ISNEWERTHAN="%DateSerial+TimeSerial%" ISOLDERTHAN="%DateSerial+TimeSerial%" ATTRFILTER="+r+a+s+h+c+e" SOURCEIMAGE="text" INSERTTYPE="text (options)" OVERLAYSTRING="text" OVERLAYIMAGE="text" FONT="text (options)" COLOR="text (options)" SIZE="number" FONTSTYLE="text (options)" OVERLAYPOSITION="text (options)" TOP="number" LEFT="number" DATASET="text" DESTINATIONIMAGE="text" />
Description
Superimposes one or more graphic or text elements over an image. The resulting copy contains both the overlay elements and the original image.
Practical usage
Commonly be used to overlay an image for different situations, such as to display captions, convey information, or to blend two images to produce visual attractiveness or appeal.
Parameters
General
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
Source | Text | Yes | (Empty) | SOURCEIMAGE="c:\temp\sourceImage.jpg" | The path and file name of the source image to overlay. Supported image formats are JPG, JPEG, PNG, BMP, TIF, TIFF, and GIF. This can be a fully qualified path and file name (preferred) or a single file (requires use of the File System - Change folder activity). You can use wildcard characters (for example, * or ?) to specify all files matching a certain mask. You can specify multiple files and file masks by separating each entry with a pipe character (|) (for example, c:\temp\*.txt|c:\backup\*.bak). See File Masks & Wildcards for more details. |
Destination | Text | Yes | Empty | DESTINATIONIMAGE="c:\temp\DestImage.jpg" | The path and file
name of the destination image. This allows you to save your file
under a new path, name and/or type to avoid overwriting the source
(original) file. To overwrite the source file, enter its
original path and file name. NOTE:
If performing an overwrite, make sure to set the Overwrite
if exists parameter to YES
(enabled) in the File Options
properties. This will allow matching files found in the destination
folder to be overwritten. |
Type | Text (options) | Yes | Image |
|
The
type of overlay to apply. The available options are:
|
Alignment | Text (options) | No | Bottom right |
|
The
position of the target image to apply the overlay. The available
options are:
|
Overlay image | Text | Yes, if the Type parameter is set to Image | (Empty) | OVERLAYIMAGE="c:\temp\OverlayImageFile.jpg" | The path and file name of the overlay image. Supported image formats are JPG, JPEG, PNG, BMP, TIF, TIFF, and GIF. This parameter is active only if the Type parameter is set to Image. |
Position (pixel) | Number | Yes, if the Alignment parameter is set to Custom | 0,0 |
|
The custom pixel position of the target image or text string to apply the overlay. This parameter becomes active and is required if the Alignment parameter is set to Custom. |
Overlay text | Text | Yes, if the Type parameter is set to Text | (Empty) | OVERLAYTEXT="textOverlay" | The text string to overlay. This parameter is active only if the Type parameter is set to Text. |
Font | Text (options) | Yes, if the Type parameter is set to Text | Segoe UI | FONT="Times New Roman" | The font typeface to overlay. The available list box allows selection from a predefined list of fonts. The default value is Segoe UI. This parameter is active only if the Type parameter is set to Text. |
Size | Number | Yes, if the Type parameter is set to Text | 11 | SIZE="10" | The size of the font to overlay. The default value is 11. This parameter is active only if the Type parameter is set to Text. |
Color type | Text (options) | Yes, if the Type parameter is set to Text | Black | COLOR="Blue" | The color of the text to overlay. The default value is Black. The available list box allows selection from a predefined list of colors. This parameter is active only if the Type parameter is set to Text. |
Font style | Text (options) | Yes, if the Type parameter set to Text | Regular |
|
The
font style or effect to apply. The available options are:
|
Advanced
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
Create and populate dataset | Text | No | (Empty) | DATASET="datasetName" | The name of a dataset to create and populate with information about this activity's results. For more details, see Datasets below. |
File Options
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
Exclude mask | Text | No | (Empty) |
|
Causes this action to omit files matching the masks specified. File names or wildcard masks may be used. Multiple entries may be specified by separating them with a pipe (|) symbol (for example, *.txt|*.bak). |
Regular expression | Yes/No | No | No | RE="YES" | Specifies whether the Exclude mask parameter is a regular expression. If disabled (default), the Exclude mask parameter contains literal text. |
Only if newer than | Date | No | (Empty) | ISNEWERTHAN="%DateSerial(2001,10,12) + TimeSerial(00,00,00)%" | If enabled, causes this action to only act on files that are newer than the date/time specified. If this parameter is left blank or disabled (default), file 'newer than' dates are ignored. Click the Custom button to select from a list of pre-defined date parameters. Enable the Expression option to allow entry of a date/time expression. |
Only if older than | Date | No | (Empty) | ISOLDERTHAN="%DateSerial(2001,10,12) + TimeSerial(00,00,00)%" | If enabled, causes this action to only act on files that are older than the date/time specified. If this parameter is left blank or disabled (default), file 'older than' dates are ignored. Click the Custom button to select from a list of pre-defined date parameters. Enable the Expression option to allow entry of a date/time expression. |
Overwrite if exists | Yes/No | No | No | OVERWRITE="YES" | If selected, indicates that, if files with matching names already exists in the destination, they will be overwritten. If disabled (default), files with matching names will not be overwritten, however, an error will occur during runtime stating a file with the same name already exists. |
Only if newer | Yes/No | No | No | ISNEWER="YES" | If selected, indicates that, if files with matching names already exists in the destination, only source files that are newer will overwrite existing files. If disabled (default), all matching files found in the destination folder will be overwritten regardless of their date properties. This parameter is active only if the Overwrite if Exists parameter is selected. |
Only if exists in destination | Yes/No | No | No | ONLYIFEXIST="YES" | If selected, only files that already exist in the destination will be copied from the source. All other files, regardless of whether they match the mask or other parameter settings will be bypassed. This parameter is disabled by default and becomes active only if the Overwrite if Exist parameter is selected. |
Overwrite read-only files | Yes/No | No | No | OVERWRITEREADONLY="YES" | If selected, matching files found in the destination folder will be overwritten even if they are marked with the read-only attribute. If disabled (default), read-only files are not overwritten. This parameter is active only if the Overwrite if Exist parameter is selected. |
Overwrite hidden files | Yes/No | No | No | OVERWRITEHIDDEN="YES" | If selected, matching files found in the destination folder will be overwritten even if they are marked with the hidden attribute. If disabled (default), hidden files are not overwritten. This parameter is active only if the Overwrite if Exist parameter is selected. |
Include subfolders | Yes/No | No | No | SUBFOLDERS="YES" | If selected, denotes that, if present, subfolders should be searched for files matching the mask specified in the Source parameter. If disabled (default), subfolders are ignored. Only files that exist in the root of the source folder will be searched. |
Preserve folder structure | Yes/No | No | No | KEEPFOLDERSTRUCT="NO" | If selected, subfolders found in the source folder will be created in the destination folder and source files will be copied into their respective folders. If disabled (default), subfolders will not be created in the destination. Instead, source files that exist in these subfolders will be copied into the root of the destination folder. This parameter is active only if the Include subfolders parameter is selected. |
Turn archive attribute off | Yes/No | No | No | ARCHIVETURNOFF="YES" | If selected, specifies that the archive attribute of the source files should be switched OFF. The Windows archive attribute is generally used to track whether a file has been backed-up. Turning the source file's archive attribute off indicates to many backup programs that the file has already been backed-up. This parameter is disabled by default. |
Match case | Yes/No | No | No | MATCHCASE="YES" | If selected (default), the activity becomes case sensitive. If disabled, the activity becomes case insensitive, whereas, it does not distinguish between uppercase and lowercase characters. |
File Attributes
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
Attributes | Text (Options) | No | (Empty) |
|
Instructs
the activity to filter which files it should act on based on whether
the file's original attribute settings match the attribute settings
specified in this parameter. For example, if the Read-only
attribute is set to Off
(in visual mode) or "-R"
(in AML mode) , only source files with the Read-only attribute
turned off will be affected. Source files with Read-only turned
on will be ignored. In visual mode, a group of controls are provided
to assist in the selection of attribute settings. In AML mode,
a single text item must be entered that contains the original
attribute mask of the files you wish to affect. Available Options
are:
|
Additional notes
Datasets
A dataset is a multiple column, multiple row container object. This activity creates and populates a dataset with the following fields (rows):
Name | Type | Return Value |
---|---|---|
theDataset.Destination | Text | The path and file name of the output file. |
theDataset.Message | Number | If theDataset.Result returns 1, this field returns a description of the error that occurred. If theDataset.Result returns 0, this field is left blank. |
theDataset.Result | Number | The runtime result of this activity. If 0 is returned, this activity ran successfully. If 1 is returned, this activity failed with an error. |
theDataset.Source | Text | The path and file name of the source (original) file. |
Example
- Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
- To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.
Description
This sample task overlays an image on another image and then saves the file.
<AMIMAGE ACTIVITY="overlay" MATCHCASE="YES" OVERWRITE="YES" ISNEWER="YES" SOURCEIMAGE="C:\temp2\am_128.bmp" OVERLAYIMAGE="C:\temp2\am_127.bmp" DATASET="theDataset" DESTINATIONIMAGE="C:\temp2\am_128.bmp" />