Image - Image recognition

Declaration

<AMIMAGE ACTIVITY="image_recognize" MATCHCASE="YES/NO" SUBFOLDERS="YES/NO" EXCLUDE="text" RE="YES/NO" ISNEWERTHAN="%DateSerial+TimeSerial%" ISOLDERTHAN="%DateSerial+TimeSerial%" ATTRFILTER="+r+a+s+h+c+e" HAYSTACKIMAGE="text" POSITION="text (options)" TOLERANCE="number" DATASET="text" NEEDLEIMAGE="text" />

Related Topics

Description

Scans one or more haystack (larger) images for occurrence of a matching needle (smaller) image and populates a dataset with results. To specify more than one file, use wildcard characters (for example, * or ?). To specify multiple file names or wildcard masks, separate them with a pipe symbol (for example, c:\*.txt|c:\*.bak).

Practical Usage

This activity can be used to quickly search for duplicate images within folders and sub-folders that may contain a considerable amount of image files. It can also be used as a tool to specify coordinates as a way to precisely identify the location of an image.

Parameters

General

Property Type Required Default Markup Description
Haystack image Text Yes (Empty)
  • HAYSTACKIMAGE="c:\folder\fileName.png"
  • HAYSTACKIMAGE="c:\folder\*.bmp"
  • HAYSTACKIMAGE="c:\fdr1\*.jpg|c:\fdr2\*.gif"
 The image files to scan. 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). Wildcard characters (for example, * or ?) may be used to specify all files matching a certain mask. Multiple files and/or file masks can be specified by separating each entry with a pipe character (|) (for example, c:\temp\*.txt|c:\backup\*.bak). See File Masks & Wildcards for more details.
Needle image Text (options) No (Empty) NEEDLEIMAGE="C:\folderName\image.jpg" The path and file name of the needle (smaller) image.
Tolerance Number (options) No 0 TOLERANCE="10" The level of tolerance (accuracy) to apply when searching for matching images. Use the slider to select a tolerance value from 0 to 100 or enter the value manually in the provided text box. The default value is 0 tolerance which means pixel colors must match exactly.
Create and populate dataset Text Yes (Empty) DATASET="theDatasetName" The name of the dataset to create and populate with haystack and needle image attributes. For more details, see Datasets below.
Pixel position Text (options) No Center
  • POSITION="center"
  • POSITION="top_left"
 Determines the area of the matching needle image to reference when determining pixel coordinates. The available options are:
  • Center (default) - X and Y pixel coordinates will reference the center of the matching needle image within the main haystack image.
  • Top left - X and Y pixel coordinates will reference the top left corner of the matching needle image.

File Options

Property Type Required Default Markup Description
Exclude mask Text No (Empty)
  • EXCLUDE="*.txt"
  • EXCLUDE="*.txt|*.bak
  • EXCLUDE="c:\foldename"
 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.
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.
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)
  • ATTRFILTER="+R+A-H" (read-only & archive files will be affected but not hidden files)
  • ATTRFILTER="-S+H+E" (hidden and encrypted files will be affected but not system files)
 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:
  • R—Read-only - Specifying On or "+R" causes files with this attribute turned on to be included. Specifying Off or "-R" causes files with this attribute turned off to be included. Specifying Doesn't matter or excluding the letter (default) causes this attribute to be ignored.

  • A—Archive - Specifying On or "+A" causes files with this attribute turned on to be included. Specifying Off or "-A" causes files with this attribute turned off to be included. Specifying Doesn't matter or excluding the letter (default) causes this attribute to be ignored.

  • S—System - Specifying On or "+S" causes files with this attribute turned on to be included. Specifying Off or "-S" causes files with this attribute turned off to be included. Specifying Doesn't matter or excluding the letter (default) causes this attribute to be ignored.

  • H—Hidden - Specifying On or "+H" causes files with this attribute turned on to be included. Specifying Off or "-H" causes files with this attribute turned off to be included. Specifying Doesn't matter or excluding the letter (default) causes this attribute to be ignored.

  • C—Compression - Specifying On or "+C" causes files with this attribute turned on to be included. Specifying Off or "-C" causes files with this attribute turned off to be included. Specifying Doesn't matter or excluding the letter (default) causes this attribute to be ignored.

  • E-Encrypted - Specifying On or "+E" causes files with this attribute turned on to be included. Specifying Off or "-E" causes files with this attribute turned off to be included. Specifying Doesn't matter or excluding the letter (default) causes this attribute to be ignored.

Description

Error Causes

On Error

Additional Notes

Datasets

A dataset is a multi-column, multi-row object that contains a collection of information gathered during execution of a particular activity and stored in memory. This activity creates and populates a dataset with the following fields (rows):

Name Type Return Value
theDataset.Haystack Text The path and file name of the haystack image.
theDataset.HaystackHeight Number The height of the haystack image measured in pixels.
theDataset.HaystackWidth Number The width of the haystack image measured in pixels.
theDataset.IsFound True/False Returns TRUE if the haystack image was found. Otherwise, returns FALSE.
theDataset.Needle Text The path and file name of the needle image.
theDataset.NeedleHeight Number The height of the needle image measured in pixels.
theDataset.NeedleWidth Number The width of the needle image measured in pixels.
theDataset.X Number The X coordinates of a matching image.
theDataset.Y Number The Y coordinates of a matching image.

Example

NOTE:
  • The sample AML code below can be copied and pasted directly into the Steps Panel of the Task Builder.
  • Parameters containing user credentials, files, file paths, and/or other information specific to the task must be customized before the sample code can run successfully.

Description

This sample task finds the center coordinates of a Needle image in a Haystack image and then creates and populates a dataset with the results.

Copy 
<AMIMAGE ACTIVITY="image_recognize" MATCHCASE="YES" SUBFOLDERS="YES" HAYSTACKIMAGE="c:\temp\HashImage.png" DATASET="imageAttrib" NEEDLEIMAGE="c:\temp\Needlemage.png" />