Differences

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

--- Found_Image [2018/04/14 07:42] – [Specifying Fields in Found Image Actions] peternlewis
+++ 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**\\
+===== Example Click on Found Image =====
-This is how the Action appears when first inserted into your macro.{{:click-found-image-action-initial-setup-km-7.3.png?nolink|}}
+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 ====
@@ Line 19: / 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.
-- **//Must be Unique// Checkbox**
+- **//Unique// Menu**
-        * If //checked//, then the image must be the only image in the specified area, or the //Action// will fail.
+        * By default, the image must be unique on the screen so that Keyboard Maestro knows where to click, otherwise the action will fail.
-        * If //not checked//, then best one of the images (based on an internal algorithm) will be selected.  If there are multiple similarly good matches then it is unpredictable which one will be used.
+        * 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 all found matches**
+- **//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.
-  * Window with a title containing a given string.
-  * Window with a title matching a given regular expression.
-  * Specified window (counting from the frontmost window).
-  * Specified area on the screen.
     * 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)
@@ Line 46: / Line 43: @@
 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.
-**Example: Click on Image in Area Relative to Front Window**{{:click-found-image-action-km-7.3.png?nolink|}}
+{{ 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 =====
@@ Line 52: / Line 52: @@
 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 icons or text).
+      * 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
+      * Set Search Area to less than a quarter of the whole desktop.
-      * This will improve ability to find smaller images that have low contrast
+      * This will improve ability to find smaller images that have low contrast.
 ===== Testing =====
@@ Line 62: / Line 62: @@
 When testing found image macros:
-* ALWAYS hide the Keyboard Maestro editor – as the image in the found image action may be found too under some circumstances.
+* Hide the action or the Keyboard Maestro editor as the image within the action may be found.
-* ALWAYS turn ON the “Display” checkmark, so you get visual confirmation an image has been found.
+* Turn on the “Display” checkmark, so you get visual confirmation an image has been found.
-* If the image is NOT found ALWAYS play with the fuzz slider.
+* If the image is not found, play with the fuzz slider.
-* It's generally a good idea to initially test on the main monitor in the front window.