Wiki Update: Found Image Condition


Submitted for your review, comment, and/or revision, this KM Wiki article:
###Found Image Condition

####Purpose of Change:

  • Improve instructions on how to use
  • Provide connection with Actions


  • Add screenshots of example Actions that use Found Image condition
  • Add sections on “Example Actions” and “How to Use”
  • Reorganize and reformat instructions
  • Add links to Actions that use this condition


Hey JM,

Looks good.  :sunny:



There is a bit of confusion added with that.

Conditions are things you add to the Control Flow actions (If Then Else, While, Until, Pause Until).

There are other actions that also find an image, and they use a similar UI, but they do not test for the existence of an image on the screen so much as they find it on the screen and do something with it (return its location, or click there). But they are not Found Image conditions, so while they could be referenced as related, they are not actually using the Find Image condition per se.

So it would be better to use one of the Control Flow actions in the images, and only refer to the Move or Click/Find Image actions as related.

Whether you want to repeat the Configuration information (which is great!) in the other two actions, or just have them reference the condition, or even put it in a page on its own (or possibly put it in a page on its own and have it included on the two pages - I’m not entirely sure how to do that, but I remember doing that on another wiki, so its probably possible on dokuwiki).



It is confusing, even the way you state it.
I get it that technically some Actions do NOT use a “Condition”, but the do search for an image.

The list of Actions I show I got from a wiki search of “found image”.

So, from a non-technical user’s point of view, does it really matter whether some of these Actions technically have a “Condition” of found image, or just a setup that uses “found image”?

The “Move or Click Mouse” Action is a perfect example. It has Action fields for everything listed in the “Found Image Condition” section on “Configure the Action”.

Maybe the solution is to state that some Actions search for images just like the Found Image Condition, but do not call it a “condition”.

Although, having just written that, it seems like it raises as many questions as it answers.

I’ve already spent a lot of time making the changes I did. I don’t see a clear way to address your concern. So feel free to change as you see fit. Frankly, from the user’s POV, I don’t see an issue, so I don’t know how to fix it. :wink:


Hey Jim,

I get what Peter’s saying.

The title of the page is Found Image Condition.

Therefore pause until image found should probably be the lead image, since it’s a flow-control condition.

The others would then reference off of it.

I think the only thing you’d really need to do is add 1 image and perhaps a brief explanation.



OK, I added a page on the found image facility (Found Image), and then adjusted the condition and collection pages to reference it (implicitly, from the page you can’t tell that the information is being copied from another source).

One of the important ways I try to keep the complexity of Keyboard Maestro down is by segregating different topics. You could use Keyboard Maestro just fine and never know about any collections. Or conditions. You can’t use Keyboard Maestro without knowing about actions. But I try very hard to keep each of the concepts orthogonal.

In this case, the facility to find matches on the screen runs across several of these orthogonal features, in the same way that text tokens or functions runs across the other features.

The idea is that you should not have to learn everything at once, and that each thing you learn should be applicable across a range of other things.

So to me, it’s important to try to keep the terminology straight and keep the complexity down. Hence the desire to avoid conflating terms.

Anyway, take a look at how I’ve massaged the stuff you did on the condition and hopefully that makes it clear. I haven’t applied the changes to the two actual actions yet.


OK, that looks good Peter. Thanks for taking the initiative to separate out into a new article.

I just got back from a late dinner, and you probably won't believe this, but I had come to the same conclusion as you did in making the "Found Image" as a separate page. OTOH, maybe it's like they say, "great minds think . . ." :laughing:

What do you think about adding the two example screenshots I had to the new Found Image, along with the one you did for "Pause Until"? I think those 3 really communicate the utility and power of "Found Image" to users.

I'd also like list all of the Actions that use "Found Image" where as a "condition" or otherwise, as I had done. Your thoughts?

I also had just make this comparison, and had concluded that all Actions that use "Found Image" are, from a functional POV, using a "condition". It just that those that use a "KM Condition" offer multiple conditions, whereas the others offer on one fixed condition:


Yes, by all means add the images of the actions in to the Found_Image page. Remember when editing that that the contents of the How to Use section are slotted in elsewhere.

Currently the Found_Image page is not actually linked anywhere.

The same facility (Finding and Image on the Screen) is used in a variety of contexts. As one of several possible conditions to the Control Flow actions (where it essentially returns a boolean yes/no. As one of several possible collections for the For Each action (where it returns a list of matches). And as a source for a position on the screen for various actions.

Interestingly, in your image of “Identical” sections, they aren’t actually identical - the latter offers the “Must be unique” option. Which in turn is the only thing that separates it from:

  • For Each in Found Images
    • Break From Loop


Sorry, missed answering that. Sure, if it fits in. They are listed at the top of the Found_Image page, and in the Related section of the other two pages. Well, they don’t list the actual actions (the Control Flow actions and the For Each action). Feel free to add them back in any way you like.


What’s the difference between the “Must be unique” option on the “Find Image on Screen” and the “contains uniquely” option on the “Pause Until”?


I’d forgotten I implemented that :wink:

But it is more that it offers the various boolean options.

Regardless, its the same facility across the various actions, collections, and conditions. In this way, its the same as Functions or Text Tokens in that it provides a facility that can be used across a range of operations.


I think that was my point in the beginning. :wink:

IAC, I’m happy with the solution we have arrived at, RE a separate article for “Found Image”.


Good. I’ve finished editing them, so feel free to go wild on whatever you think works at this point.


###Need Wiki Update on Area Search

One thing that seems to be missing from all of the Wiki pages concerning “Found Image” is the fact that now you can specify an Area to search, which will invoke a higher resolution search. This type of search is often needed when searching for an image of text (like grey text on a grey background). The “Area” condition is mentioned, but not the high res search.

@peternlewis, I remember you mentioning somewhere the max area size that you can use to invoke this high res search. Could you please update the Wiki to document this?



Is it possible to add the code lines from the example?

An_Image Contents    == %Variable%An_Image%
An_Image.x           == %Calculate%An_Image.x%
An_Image.y           == %Calculate%An_Image.y%
An_Image.width       == %Calculate%An_Image.width%
An_Image.height      == %Calculate%An_Image.height%
An_Image.fuzz        == %Calculate%An_Image.fuzz%
An_Image.Midx        == %Calculate%An_Image.Midx% = %Calculate%An_Image[1]% + %Calculate%An_Image[3]% /2
An_Image.Midy        == %Calculate%An_Image.Midy% = %Calculate%An_Image[2]% + %Calculate%An_Image[4]% /2

An_Image Contents    == %Variable%An_Image%
An_Image Contents[1] == %Calculate%An_Image[1]%
An_Image Contents[2] == %Calculate%An_Image[2]%
An_Image Contents[3] == %Calculate%An_Image[3]%
An_Image Contents[4] == %Calculate%An_Image[4]%
An_Image Contents[5] == %Calculate%An_Image[5]%


What do you mean? As text so it can be copied?


Sorry Peter, I did’t realized that a download link exists. :confused:


Oh I’m so glad you mentioned that restricting the area of search yields a higher-resolution search! I not infrequently have to change the pictures used to search in situations like that!