ImageSearchDLL v2025.5.25.1 with Source

[Trong]

Overview of Functionality

The primary exported function is ImageSearch. This versatile function scans a designated area of the screen (or the entire screen) to locate one or more specified images. It's designed to be robust, offering options for approximate matching and handling variations in image appearance.

Key Features:

• Multiple Image Search: Allows searching for several images in a single call by providing a | (pipe) separated list of file paths.
• Region-Specific Search: Users can define a specific rectangular area on the screen (iLeft, iTop, iRight, iBottom) to narrow down the search, improving performance. If iRight or iBottom are not set, the full screen dimensions are used.
• Color Tolerance: Supports inexact matching through a iTolerance parameter (0 for an exact match, up to 255 for maximum tolerance). This helps find images even if their colors are slightly different.
• Multi-Result: Can find and return multiple occurrences of the image(s) if iMultiResults is set to a value greater than 0.
• Coordinate Customization: Can return either the top-left coordinates or the center coordinates of the found image(s) via the iCenterPOS flag.
• Debugging Information: Optional debug information can be appended to the result string for troubleshooting.

---

🌟 Advanced Search Capabilities

Two particularly powerful features of the ImageSearch function are its ability to find scaled images and to handle transparency:

Scaled Image Search

The function can search for images even if they appear on the screen at a different size than the source image file. This is controlled by three parameters:

• fMinScale: The minimum scaling factor to test (e.g., 0.5 for 50% of original size).
• fMaxScale: The maximum scaling factor (e.g., 1.5 for 150% of original size).
• fScaleStep: The increment used to iterate through scales between fMinScale and fMaxScale.

The DLL will systematically resize the search image according to these parameters and attempt to find a match. If a scaled version is found, the fScaleSuccess value in the debug information will indicate the scale at which the match occurred.

Transparent Background Search

The iTransparent parameter allows specifying a color (in COLORREF format) that should be treated as transparent during the search. Any pixels in the source image that match this transparent color will be ignored when comparing against the screen. This is invaluable for finding irregularly shaped images or icons that are displayed over varying backgrounds. The default value CLR_NONE (0xFFFFFFFF) indicates no transparency.

---

Input Arguments for ImageSearchDll

The ImageSearch function accepts the following parameters:

• sImageFile (char*) A string containing one or more image file paths, separated by |.
• iLeft (int, optional): The left coordinate of the search area. Defaults to 0.
• iTop (int, optional): The top coordinate of the search area. Defaults to 0.
• iRight (int, optional): The right coordinate of the search area. Defaults to the screen width if 0 or less than iLeft.
• iBottom (int, optional): The bottom coordinate of the search area. Defaults to the screen height if 0 or less than iTop.
• iTolerance (int, optional): Color variation tolerance from 0 (exact) to 255. Defaults to 0.
• iTransparent (int, optional): The color to be treated as transparent. Defaults to CLR_NONE = -1.
• iMultiResults (int, optional): Set to 0 to find only the first match, or a higher number to find up to that many matches. Defaults to 0.
• iCenterPOS (int, optional): If 1, results are center coordinates; otherwise, top-left. Defaults to 1.
• iReturnDebug (int, optional): If non-zero, appends debug information to the result string. Defaults to 0.
• fMinScale (float, optional): Minimum scaling factor for the image (0.1 to 1.0). Defaults to 1.0f.
• fMaxScale (float, optional): Maximum scaling factor (1.0 to 3.0). Defaults to 1.0f.
• fScaleStep (float, optional): Step to increment scale between min and max. Defaults to 0.1f.

---

Return Format

The function returns a char* (C-string) with the results formatted as follows:

• Match Found: "{<match_count>}[<match_result(s)>]"
  • Example for one match: "{1}[x|y|w|h]"
  • Example for multiple matches: "{2}[x1|y1|w1|h1,x2|y2|w2|h2]" (results are comma-separated)
  • x, y are the coordinates of the found image (top-left or center based on iCenterPOS).
  • w, h are the width and height of the image as found on screen (which might be scaled).
• No Match Found: "0[]"
• Error Occurred: "{<negative_error_code>}[<error_message>]"
  • Example: "{E<-2>}[Failed to load image]" (Error codes are defined in GetErrorMessage)

If iReturnDebug is enabled, additional debug information is appended in parentheses, detailing the parameters used for the search and the success scale factor, e.g., (...debug_info...). For errors, fScaleSuccess is reported as 0.00 in the debug info.

 

ImageSearchUDF supports Windows XP!

Download Autoit ImageSearchUDF here:  

 

Edited Friday at 07:03 AM by Trong
Finalize UDF