Although it is generally better to use high level actions like Press Button or Resize Window action, it is sometimes necessary to resort to looking at the screen for a specific image and responding appropriately (behaving differently if it exists, clicking on it, moving things to it, etc).

There are various actions (Move or Click Mouse, Find Image on Screen, conditions and collections that search the screen for a matching image.

This is how the Action appears when first inserted into your macro.

• 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

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.

Keyboard Maestro uses a relatively fast search to make the action perform in a reasonable amount of time, but it can result in not finding some images.

• Images Difficult to Match
  • The most difficult images to match are small grey images (like grey icons or text).
  • Since the screen tends to be filled with small grey areas, it is hard for Keyboard Maestro to find the best locations to look.
• Increasing Search Accuracy
  • Set Search Area to less than a quarter of the whole desktop.
  • This will improve ability to find smaller images that have low contrast.

When testing found image macros:

• Hide the action or the Keyboard Maestro editor as the image within the action may be found.
• Turn on the “Display” checkmark, so you get visual confirmation an image has been found.
• If the image is not found, play with the fuzz slider.