FindImagePos>needle_bitmap,haystack,tolerance,return_offset,X_Array,Y_Array,NumFound[,MatchAlgorithm]
Not supported in Macro Scheduler Lite.
Scans a haystack image looking for occurrences of needle_bitmap. needle_bitmap is usually a small image such as an image of a button or other GUI component captured at design time, and haystack would be a screen image.
It is recommended that the Image Recognition Wizard is used to capture needle images and generate FindImagePos code.
needle_bitmap should be a fully qualified path to a bitmap or png file (see MatchAlgorithm type below for supported image types).
haystack can be set to one of the following values:
1. A bitmap/png file (e.g. %SCRIPT_DIR%\haystack.bmp) (see MatchAlgorithm type below for supported image types).
2. SCREEN - this causes the entire screen to be scanned
3. WINDOW:title where title is a window title (e.g. WINDOW:Untitled - Notepad)
4. WINDOW:Active Window - to work against the active window
MatchAlgorithm was added in v14 and although it is at the end of the parameter list it should be discussed here as it affects the use and outcome of the remaining parameters. Prior to v14 image recognition was exact and performed a precise comparison of pixels.
To use exact matching set MatchAlgorithm to EXACT.
Version 14 introduces the use of a Correlation Coefficient algorithm. To use this set MatchAlgorithm to CCOEFF. This algorithm uses a template matching system attempting to find similarities in images rather than comparing pixels precisely. It is therefore able to find images even if they are not exactly the same and will therefore cope with differences in bit depth, different versions of images across different versions of Windows and different fonts, etc, making image recognition scripts more portable and less likely to fail should the environment change.
The use of the tolerance parameter varies depending on the MatchAlgorithm used.
CCOEFF:Tolerence should be given a value between 0 and 1 where 1 is a precise match and 0 is the least precise. A value of 0.7 is recommended and should allow for subtle variations in the images and works best for portability. The lower the value the more likely false positives will be observed. With CCOEFF matching only one match (if any) is returned - the most likely candidate. CCOEFF will work with bitmap or png files.
EXACT: For exact matching tolerance specifies the color tolerance. If tolerance is zero the pixel colors must match exactly. Tolerance can be set to a value between 0 and 255. If larger than zero the red, green and blue values of the pixels in bitmap_to_scan are checked to see if they are within the tolerance specified (color value + or - tolerance). Smaller values match less and larger values match more. EXACT matching may return more than 1 match if there are more than 1 exact matches in the target area. EXACT can only work with bitmap files.
Each method has benefits and drawbacks. CCOEFF is more intelligent and more tolerant but is slower and will return only one match. EXACT is faster and can return multiple matches but is precise and therefore less portable and will not cope with changes.
To ensure backward compatibility EXACT matching will be used if MatchAlgorithm is omitted. This ensures old scripts will work as they used to.
return_offset is used to determine which coordinates should be returned and can be one of the following:
|
0 |
Top left position of located image within bitmap_to_scan. In other words X, Y is the top left corner of needle_bitmap within haystack |
|
1 |
Center: X,Y will be set to the center of the located image within the main haystack image. |
|
2 |
Top right |
|
3 |
Bottom left |
|
4 |
Bottom right |
|
5 |
Middle top |
|
6 |
Middle bottom |
|
7 |
Middle left |
|
8 |
Middle right |
X_Array is the name of an array to store the X coordinates of each match. If using CCOEFF matching (the default) only the most likely result is returned and so there will be only one result in X_Array_0 if a match is found. If using EXACT matching multiple results may be returned. The first match is stored in X_Array_0, the second in X_Array_1, etc.
Y_Array is the name of an array to store the Y coordinates of each match. If using CCOEFF matching (the default) only the most likely result is returned and so there will be only one result in X_Array_0 if a match is found. If using EXACT matching multiple results may be returned. The first match is stored in Y_Array_0, the second in Y_Array_1, etc.
NumFound returns the number of matches found. If an error is encountered NumFound will be set to -1. E.g. if the needle image is larger than the haystack image, NumFound will be set to -1.
Note that if haystack is SCREEN or a WINDOW the x and y positions returned are absolute screen positions and can be used directly with MouseMove to move the mouse to the found position.
Advanced (If using EXACT matching): By default FindImagePos now scans ALL pixels in each matching rectangle on needle_bitmap. If you wish to scan only a small set of random pixels (and thereby speed up searching) set FIP_SCANPIXELS to that number, e.g. FIP_SCANPIXELS=100. To set back to all set FIP_SCANPIXELS=ALL.
Abbreviation: FIP
See also: GetScreenRes, CompareBitmaps, ScreenCapture, WaitScreenImage
Example
FindImagePos>d:\today_button.bmp,SCREEN,0.7,1,X,Y,NumFound,CCOEFF
If>NumFound>0
MouseMove>X_0,Y_0
Endif