So I'm trying to better understand some things about the subtleties of doing image searches with Keyboard Maestro.
IF
The image you want to find is always visible on your screen (but may dynamically be in different locations on your screen),
AND IF
You just simply need to determine the coordinates of said image, to subsequently use those coordinates for further processing within a macro,
Is there any effective difference between using the "Find Image" action versus instead using a combination of the "Pause Until Image Found" and "Set Variable" actions? Both scenarios will ultimately give you a variable, from which you can extract .MidX and .MidY coordinates from, to use elsewhere as desired.
If we were talking about an image which may not initially be visible on the screen, I would see why using "Pause Until Image Found" was advantageous, but in my scenario this should be an image that is always visible somewhere on the screen. So do I really need to worry about using "Pause Until Image Found" combined with "Set Variable", or is "Find Image" just as effective in this scenario? Maybe there's some other advantage to using one option or the other that I'm not thinking about? Do I need to be worrying about any pausing at all?
If it's always visible onscreen, you should just use Find Image, as you surmised. The Pause Until Image is Found action is used for images that aren't always there, and will come into existence after some event (possibly an event caused by earlier steps in the macro).
So, when using "Find Image", is there ever a reason I would need to use a pause action of any kind ("Pause" or "Pause Until") after it?
I ask because I'm accustomed to using a "Pause" after things like move/click of the mouse, where KM doesn't have control or knowledge of how long it takes for the OS to complete the move/click, hence the need for a pause immediately following the move/click action.
But, correct me if I'm wrong here, "Find Image" is an action completely contained within KM, correct? In other words, KM controls and has knowledge of when the "Find Image" action is complete, and therefore no "Pause" after "Find Image" is necessary because KM is able to know when "Find Image" is complete, and thus will not move on to the next action until "Find Image" is complete, correct?
By the way, in the gear widget settings menu for the "Find Image" action, I see that it has "Wait for Image" and "Failure Aborts Macro" both set to OFF, by default. I haven't seen where "Wait for Image" is discussed anywhere, but that seems like it would function the same as "Pause Until Image Is Found", though I'm wondering what the purpose is for "Wait for Image"? It seems duplicative of "Pause Until Image Is Found". Actually, it almost makes the existence of "Pause Until Image Is Found" seem unnecessary, as you could do the same thing with the "Wait for Image" setting in "Find Image", but then you wouldn't have to also bother with adding the additional "Set Variable" action to %FoundImage%, because "Find Image" already sets the variable internally within its own action.
In my scenario, I think I'd still leave "Wait for Image" set to OFF, because I either want it to find the image or not, and not continue to keep looking, thus hanging up the macro. Plus, the image should be there all the time anyway.
I know that's new in v11, though I have no idea how it differs from the Pause Until version. I suspect they're quite similar, but I'd have to rely on others or @peternlewis to explain the differences.
Oh. I didn't realize "Wait For Image" was new. I only recently starting playing around with "Find Image". I had previously been doing the whole "If Image Is Found" action, followed by a move/click mouse at image action, which worked, but involved two identical image searches, and slowed the macro down. Once I became aware of what you could do with "Find Image" I quite using the IF action for these purposes, unless it was specifically because it was all needed as part of a larger If/then action scenario.
I still have a little difficulty at times knowing which actions are deterministic (completely controlled by KM, and where KM also is aware of the action's completion) and which actions are not deterministic. The move or move/click a mouse thing is obviously not deterministic, so I've known that I needed pauses after those actions, but I hadn't been quite as sure about things like "Find Image", though I sort of suspected that a pause wasn't needed after "Find Image". I wish there was a KM Wiki somewhere that spelled out which actions were deterministic and which were not, that way it would be more clear about where you need to use pauses. The explanations I've seen on this subject have always felt a little vague. There isn't a Wiki like this somewhere, is there?
It would be nice, but it's probably not really possible as it depends on two many factors.
For example, I'd typically say that simulated typing is deterministic, since typing goes in to a queue, and then is read back in sequence, but on the other hand, the key might stay in the queue for an unknown time, and also some poorly behaved applications still manage to mess up the order of the characters (eg web pages, and apparently WhatsApp will process the Command-V out of order with the other typing).
Also, things that are entirely deterministic and rapidly become not-so when the target application decides it will take note of something and defer it for its own reasons.
As much as possible, Keyboard Maestro actions try to wait until their actions complete, but that is not always possible, and sometimes they are guesses, and to try to document each of these would be a nightmare, especially as they change with versions of macOS and with target applications.
To clarify the difference between Find Image, and Pause Until Image Found:
The Find Image on Screen action will fail and potentially abort the macro if the image is not found. Unless the new Wait For Image option is enabled.
The Find Image on Screen action with the Wait For Image option will return directly the image location into a variable.
The Pause Until action with the Found Image condition will wait for the image to be found, and you can use the FoundImage token to determine the location and set a variable with the Set Variable to Text action.
So yes, there is overlap. But:
The Wait For Image option was only added in version 11, thus there was no overlap before that.
The Find Image action should be used without the Wait For Image option if you expect the image to already be on the screen, thus aborting and erroring if the image is not there.
If you just want to find the image and expect it to potentially take some time to show up, then the Find Image action with the Wait For Image option is a good solution. Set the timeout as appropriate.
You might still want to use the Pause Until Action with the Found Image condition if you want other conditions, for example you might want:
to pause until either of two images appears
to pause until the image appears or the idle time exceeds 30 seconds
to pause until the image appears or the mouse move to the top of the screen
The Pause Until Image Found is more “Keyboard Maestro-like” generally, as it breaks the parts of the action in to more components, which gives you more flexibility. But waiting for the image to appear turned out to be extremely common which is why it was added to the various image searching actions.