Table of Contents
Find Image on Screen Action
The Find Image on Screen action finds a specified image on the screen in a specified area and stores the image location and fuzziness (left,top,width,height,fuzz) in a Keyboard Maestro Variable.
You can specify the image to search based on:
- An image pasted in to the action.
- An image from the System Clipboard, Trigger Clipboard or a Named Clipboard (v9.0+).
- An image loaded from a file (v9.0+).
- An image from elsewhere on the screen (v9.0+).
You can also specify the fuzz allowed in the match, as well as whether to display the possible matches (generally used for debugging), and whether the image must be unique, or if not, which of the acceptable images to choose (the best, the topmost (v9.0+), leftmost (v9.0+), bottommost (v9.0+), or rightmost (v9.0+)).
You can search the entire desktop, or you can restrict your search to a specific screen or window, or to a specific area on the screen.
There is an option in the action (gear) ⚙ menu to have the action wait until the image appears (v11.0+).
Suppose that the image location is stored in the Variable ImageLocation (chosen by you in the action). Then parts of the image data (properties) may be referenced in other actions like Move and Click Mouse using the following notation:
- ImageLocation.x — Horizontal position of upper left corner.
- ImageLocation.y — Vertical position of upper left corner.
- ImageLocation.width — the Width of the match (same as the source image).
- ImageLocation.height — the Height of the match (same as the source image).
- ImageLocation.fuzz — the Fuzz of the match.
- ImageLocation.MidX — Horizontal position of center.
- ImageLocation.MidY — Vertical position of center.
If this action fails to find the image, the variable will be set to the empty string.
After an action like this is executed, and an image was found, then the %FoundImage% token (v8+) will return the data of the last found image.
Please note that “ImageLocation” is just an example Variable (which you the user can set), whereas %FoundImage% is a token provided by the Keyboard Maestro Engine.
How To Use
Specifying Fields in Found Image Actions
- Specify the image to match
- Paste an image into the image well
(Use ⌘⌃⇧4 to Take a screenshot of part of your screen). - To view the image in the image well, click on it and press SPACE.
- You can copy the image from the Image Well.
- Alternatively (v9.0+), you can get the image to search from the System Clipboard, Trigger Clipboard, a Named Clipboard, a file, or from an image elsewhere on the screen.
- Specify the amount of fuzziness allowed
- Because of transparency and anti-aliasing almost all screen matches are fuzzy to some degree.
- But usually about 20% is a good place to start.
- Unique Menu
- By default, the image must be unique on the screen so that Keyboard Maestro knows where to click, otherwise the action will fail.
- Alternatively, you can have Keyboard Maestro click based on the best match, or (v9.0+) click on the topmost, leftmost, bottommost, or rightmost match.
- Display Checkbox – If checked, it will highlight on the screen all found matches
- This can be helpful in debugging, like determining the right amount of fuzz to use.
- It will also show when an image is being found in more than one location.
- Choose Where to Search for Image
- You can search in all screens, or on a specific screen.
- Alternatively, you can search within a specific window.
- However, the window must be in the frontmost, active, application, in order for it to be seen by this Action.
- Or you can search within a specific area on the screen.
- For instructions on how to get data for area, see Determine Location of Area to Search for Found Image
Search in Specified Area
Remember when specifying the area, as with all numeric fields, the numbers can be calculations including functions, and the fields expand to allow for longer expressions as soon as you type something other than a number, so this allows very precise control of where you can match.
Note that in the above screen shot, the WINDOW(0,Left) function is referring to the frontmost window in the frontmost app. To refer to other windows in the frontmost app, you need to change the index parameter of the WINDOW function.
