About This File
High-Performance ImageSearch UDF & DLL for AutoIt
This project provides a highly optimized UDF (User Defined Function) and two versions of a DLL (Dynamic-Link Library) for fast and flexible image searching on the screen using AutoIt.
It serves as a powerful replacement for standard image search functions, delivering superior speed, especially on modern CPUs, by leveraging advanced SIMD instructions.
✨ Key Features
- Superior Speed: The modern version utilizes the AVX2 instruction set to accelerate the search speed by several factors compared to traditional methods.
- Two DLL Versions: Provides both a modern version (optimized for speed) and a legacy version (for Windows XP support).
- Multi-Image Search: Search for multiple image files in a single function call by separating paths with a pipe (|).
- Multi-Scale Searching: Automatically search for an image across a range of sizes (e.g., from 80% to 120% of its original size).
- Color Tolerance: Find images even with slight color variations by setting a tolerance value (0-255).
- Transparent Color Support: Specify a color in the source image to be ignored during the search.
-
Flexible Result Handling:
- Find and return the first match.
- Find and return all matches on the screen.
- Limit the maximum number of results.
- Smart (Hybrid) DLL Loading: The UDF prioritizes an external DLL for maximum performance and automatically falls back to an embedded DLL to ensure the script always runs.
- Unicode Support: Works flawlessly with file paths containing Unicode characters.
- Thread-Safe: The DLL is designed to operate stably in multi-threaded scenarios.
- Debug Information: Provides an option to return a detailed debug string for easy troubleshooting.
🚀 The Two DLL Versions
The project offers two DLL versions to meet different needs:
1. ImageSearch_x86.dll ImageSearch_x64.dll (Modern Version)
(Attached in the same UDF folder - Because the DLL file with AVX2 support is large in size) This is the recommended version for most users.
-
Strengths:
- AVX2 Support: Leverages Advanced Vector Extensions 2 on modern CPUs to process multiple pixels in parallel, resulting in extremely fast search speeds.
- Built with modern C++, ensuring stability and efficiency.
-
Limitations:
- Not compatible with Windows XP.
- When to use: When you need maximum performance on Windows 7, 8, 10, 11, and newer.
2. ImageSearch_XP.dll (Legacy Version)
(Embedded in UDF code) This version is created for backward compatibility.
-
Strengths:
- Windows XP Compatibility: Works well on the Windows XP (SP3) operating system.
-
Limitations:
- No AVX2 Support: Search speed will be significantly slower than the modern version on AVX2-supported CPUs.
- When to use: When your script must run in a Windows XP environment.
⚙️ How the UDF Works
The ImageSearch_UDF.au3 file uses a very smart "hybrid" DLL loading mechanism:
- Prioritize External DLL: When the _ImageSearch function is called, the UDF first looks for ImageSearch_x86.dll and ImageSearch_x64.dll in the same directory as the script (@ScriptDir). If found, it uses this file to achieve the best performance (with AVX2 if available).
- Fallback to Embedded DLL: If the external DLL is not found, the UDF will automatically extract and use a legacy (non-AVX2) compatible DLL version that is embedded within it as a hex string.
➡️ This ensures that your script can always run, even if you forget to copy the DLL file. However, for the highest speed, always place the modern ImageSearch_x86.dll and ImageSearch_x64.dll next to your script.
📦 Setup
- Place the DLL file: Copy ImageSearch_x86.dll and ImageSearch_x64.dll (the modern version) into the same directory as your AutoIt script file.
- Include the UDF in your script: Use the line #include <ImageSearch_UDF.au3> in your script.
📖 API Reference
The main function for performing an image search.
_ImageSearch($sImageFile, [$iLeft = 0], [$iTop = 0], [$iRight = 0], [$iBottom = 0], [$iTolerance = 10], [$iTransparent = 0xFFFFFFFF], [$iMultiResults = 0], [$iCenterPOS = 1], [$iReturnDebug = 0], [$fMinScale = 1.0], [$fMaxScale = 1.0], [$fScaleStep = 0.1], [$iFindAllOccurrences = 0])
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| $sImageFile | String | - | Path to the image file. To search for multiple images, separate paths with a pipe (` |
| $iLeft | Int | 0 | The left coordinate of the search area. 0 defaults to the entire screen. |
| $iTop | Int | 0 | The top coordinate of the search area. 0 defaults to the entire screen. |
| $iRight | Int | 0 | The right coordinate of the search area. 0 defaults to the entire screen. |
| $iBottom | Int | 0 | The bottom coordinate of the search area. 0 defaults to the entire screen. |
| $iTolerance | Int | 10 | Color tolerance (0-255). A higher value allows for greater color variation. |
| $iTransparent | Int | 0xFFFFFFFF | The color (in 0xRRGGBB format) to be ignored in the source image. 0xFFFFFFFF means no transparency. |
| $iMultiResults | Int | 0 | The maximum number of results to return. 0 means no limit. |
| $iCenterPOS | Bool | 1 (True) | If True, the returned X/Y coordinates will be the center of the found image. If False, they will be the top-left corner. |
| $iReturnDebug | Bool | 0 (False) | If True, the function returns a debug string instead of the results array. |
| $fMinScale | Float | 1.0 | The minimum scaling factor for the search (e.g., 0.8 for 80%). Must be >= 0.1. |
| $fMaxScale | Float | 1.0 | The maximum scaling factor for the search (e.g., 1.2 for 120%). |
| $fScaleStep | Float | 0.1 | The increment to use when searching between min and max scales. Must be >= 0.01. |
| $iFindAllOccurrences | Bool | 0 (False) | If False, the search stops after the first match. If True, it finds all possible matches. |
Return Value
-
On Success: Returns a 2D array containing the coordinates of the found images.
- $aResult[0][0] = The number of matches found.
- $aResult[1] to $aResult[$aResult[0][0]] = An array for each match.
- $aResult[$i][0] = X coordinate
- $aResult[$i][1] = Y coordinate
- $aResult[$i][2] = Width of the found image
- $aResult[$i][3] = Height of the found image
- On Failure / No Match: Sets @error to 1 and returns 0.
- In Debug Mode: If $iReturnDebug is True, returns a string containing detailed information about the last search operation.
💻 Examples
Example 1: Basic Search
Find the first occurrence of button.png on the screen.
#include <ImageSearch_UDF.au3> Local $aResult = _ImageSearch("C:\images\button.png") If @error Then MsgBox(48, "Error", "Image not found on screen.") Else Local $iCount = $aResult[0][0] Local $iX = $aResult[1][0] Local $iY = $aResult[1][1] MsgBox(64, "Success", "Found " & $iCount & " image(s). First match is at: " & $iX & ", " & $iY) MouseMove($iX, $iY, 20) ; Move mouse to the center of the found image EndIf
Example 2: Advanced Search (Multiple Images, Tolerance, Scaling)
Search for icon1.png or icon2.png within a specific region, with a tolerance of 20 and scaling from 90% to 110%. Find all occurrences.
#include <ImageSearch_UDF.au3> Local $sImages = "icon1.png|icon2.png" Local $iTolerance = 20 Local $fMinScale = 0.9 Local $fMaxScale = 1.1 Local $fStep = 0.05 Local $aResult = _ImageSearch($sImages, 500, 300, 1200, 800, $iTolerance, 0xFFFFFFFF, 0, True, False, $fMinScale, $fMaxScale, $fStep, True) If @error Then MsgBox(48, "Error", "No matching images found in the specified region.") Else Local $iCount = $aResult[0][0] ConsoleWrite("Found " & $iCount & " total matches." & @CRLF) For $i = 1 To $iCount ConsoleWrite("Match #" & $i & ": X=" & $aResult[$i][0] & ", Y=" & $aResult[$i][1] & ", W=" & $aResult[$i][2] & ", H=" & $aResult[$i][3] & @CRLF) Next EndIf
Example 3: Using Debug Mode
To diagnose issues, use the $iReturnDebug parameter.
#include <ImageSearch_UDF.au3> Local $2dDLLResult = _ImageSearch("image_not_exist.png", 0, 0, 0, 0, 10, 0xFFFFFFFF, 0, True, True) ConsoleWrite(">> DLL Return: " & $g_sLastDllReturn & @CRLF) ; Example output: {0}[No Match Found] | DEBUG: File=image_not_exist.png, Rect=(0,0,1920,1080), Tol=10, Trans=0xffffffff, Multi=0, Center=1, FindAll=0, AVX2=true, Scale=(1.00,1.00,0.10)
SPECIAL NOTE: The function always returns a 2D array for both results and errors.
Credits
- Author: Dao Van Trong - TRONG.PRO
- Source Dll on GitHub: daovantrong/ImageSearchDLL: A DLL for finding an image on the screen
Edited by Trong
New restructured version!
What's New in Version 2025.5.25.5
Released
New DLL Attached in the same UDF folder - Because the DLL file with AVX2 support is large in size!
AVX2 Support: Leverages Advanced Vector Extensions 2 on modern CPUs to process multiple pixels in parallel, resulting in extremely fast search speeds.
Built with modern C++, ensuring stability and efficiency.
AND
ImageSearch_XP.dll (Legacy Version) Embedded in UDF code!
Recommended Comments