Differences

This shows you the differences between two versions of the page.

--- Found_Image [2016/03/06 07:34] – better wiki syntax for internal links AlainLifchitz
+++ Found_Image [2024/10/12 09:23] (current) – [Specifying Fields in Found Image Actions] peternlewis
@@ Line 1: / Line 1: @@
-{{:condition:image-icon.png?nolink|}}
 ====== Found Image ======
-Although it is generally better to use high level actions like Press Button or Resize Window, 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).
+Although it is generally better to use high level actions like [[action:Press_a_Button|Press Button]] or [[action:Resize_a_Window|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 ([[action:Move or Click Mouse|Move or Click Mouse]], [[action:Find Image on Screen|Find Image on Screen]], [[condition:Found Image|conditions]] and [[collection:Found Images|collections]] that search the screen for a matching image.
+===== Example Click on Found Image =====
+This is how the Action appears when first inserted into your macro.
+{{ action:clickatfoundimagedescription.png?nolink&611x290 | Click at Found Image Description }}
 ===== How To Use =====
+==== Specifying Fields in Found Image Actions ====
 - **Specify the image to match**
@@ Line 12: / Line 20: @@
       * To view the image in the image well, click on it and press <key>SPACE</key>.
       * You can copy the image from the Image Well.
+      * Alternatively, you can get the image to search from the System Clipboard, Trigger Clipboard, a Named Clipboard, an Icon, 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.
-- **Optionally highlight Found Matches**
+- **//Unique// Menu**
-        * This can be helpful in determining the right amount of fuzz to use.
+        * By default, the image must be unique on the screen so that Keyboard Maestro knows where to click, otherwise the action will fail.
-        * It can also show when an image is being found in more than one location.
+        * 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**
-      * All screens.
+  * You can search in all screens, or on a specific screen.
-      * Main screen.
+  * Alternatively, you can search within a specific window.
-      * Specified screen (counting from the left).
+    * However, the window must be in the frontmost, active, application, in order for it to be seen by this Action.
-      * Front window.
+  * Or you can search within a specific area on the screen.
-      * Window with a specified title.
+    * For instructions on how to get data for area, see [Determine Location of Area to Search for Found Image](https://forum.keyboardmaestro.com/t/using-mouse-display-window-to-get-window-specific-locations/7112/9)
-      * Window with a title containing a given string.
-      * Window with a title matching a given regular expression.
+==== Search in Specified Area ====
-      * Specified window (counting from the frontmost window).
-      * Specified area on the screen.
 Remember when specifying the area, as with all [numeric fields](:Text_Fields), the numbers can be calculations including [functions](: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.
+{{ action:click-found-image-action-example.png?nolink&503x407 | Click at Found Image Example }}
+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 [[function:WINDOW|WINDOW function]].
+===== Search Speed and Accuracy =====
+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.
+===== Testing =====
+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.