Leaderboard

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