About This File
ImageSearch UDF v3.5 - AutoIt Wrapper for ImageSearchDLL
Advanced image search library for AutoIt with cache system and SIMD optimization.
Overview
ImageSearchDLL UDF is a high-performance image search library for AutoIt that enables you to find images on screen or within other images. Built with C++14 and optimized with SIMD instructions (AVX512/AVX2/SSE2), it provides fast and accurate image matching capabilities.
Features
- High Performance: SIMD optimization (AVX512/AVX2/SSE2) for fast searching
- Multi-Monitor Support: Full support for multi-monitor setups with negative coordinates
- DPI Awareness: Thread-local DPI awareness without affecting AutoIt GUI
- Cache System: Persistent cache for 30-50% speed boost on repeated searches
- Image Scaling: Search for images at different scales (0.1x to 5.0x)
- Screen Capture: Direct screen capture with DPI-aware coordinates
- Mouse Automation: Precise mouse movement and clicking with multi-monitor support
Requirements
- AutoIt: Version 3.3.16.1 or higher
- Windows: XP SP3 to Windows 11
- Architecture: x86 or x64 (automatic detection)
- DLL: ImageSearchDLL v3.5 (included)
Installation
-
Download the UDF package
-
Place
ImageSearchDLL_UDF.au3in your script directory -
Ensure the appropriate DLL is in the same directory:
-
ImageSearchDLL_x64.dllfor 64-bit AutoIt -
ImageSearchDLL_x86.dllfor 32-bit AutoIt - Not required in embedded version! (But need to install Visual C++ Redistributable 2015-2022)
-
-
Include the UDF in your script:
#include "ImageSearchDLL_UDF.au3"
Quick Start
Basic Image Search
#include "ImageSearchDLL_UDF.au3" ; Search for a button on screen Local $aResult = _ImageSearch("button.png") If $aResult[0] > 0 Then ConsoleWrite("Found at: " & $aResult[1][0] & ", " & $aResult[1][1] & @CRLF) MouseClick("left", $aResult[1][0], $aResult[1][1]) Else ConsoleWrite("Image not found" & @CRLF) EndIf
Wait for Image and Click
; Wait up to 5 seconds for button to appear, then click it If _ImageSearch_WaitClick(5000, "button.png") Then MsgBox(0, "Success", "Button clicked!") Else MsgBox(0, "Failed", "Button not found within 5 seconds") EndIf
Screen Capture
; Capture a region and save as PNG _ImageSearch_ScreenCapture_SaveImage(@ScriptDir & "\screenshot.png", 100, 100, 600, 400) ; Capture full screen _ImageSearch_ScreenCapture_SaveImage(@ScriptDir & "\fullscreen.png")
API Reference
Startup & Configuration
_ImageSearch_Startup()
Initializes the ImageSearch library by loading the appropriate DLL.
Returns:
- Success: 1 (DLL loaded successfully)
- Failure: 0 and sets @error
Remarks:
- Must be called before using any search functions
- Automatically called on script start
- DLL v3.5+ uses thread-local DPI awareness and won't affect AutoIt GUI
_ImageSearch_Shutdown()
Closes the DLL and cleans up resources.
_ImageSearch_SetDllPath($sPath)
Sets a custom DLL path (must be called before _ImageSearch_Startup).
Parameters:
-
$sPath- Full path to the DLL file
Returns:
- Success: 1
- Failure: 0 (file not found)
Core Search Functions
_ImageSearch($sImagePath [, $iLeft, $iTop, $iRight, $iBottom [, $iScreen [, $iTolerance [, $iResults [, $iCenterPOS [, $fMinScale [, $fMaxScale [, $fScaleStep [, $iReturnDebug [, $iUseCache]]]]]]]])
Searches for an image within a specified screen area.
Parameters:
-
$sImagePath- Image file path(s), multiple separated by "|" -
$iLeft, $iTop, $iRight, $iBottom- Search region (0 = entire screen) -
$iScreen- Monitor index (-1 = virtual screen, 0 = primary, 1+ = specific monitor) -
$iTolerance- Color tolerance 0-255 (default: 10) -
$iResults- Max results 1-1024 (default: 1) -
$iCenterPOS- Return center (1) or top-left (0) coordinates (default: 1) -
$fMinScale, $fMaxScale- Scale range 0.1-5.0 (default: 1.0) -
$fScaleStep- Scale step (default: 0.1) -
$iReturnDebug- Debug mode (default: 0) -
$iUseCache- Enable cache (default: 1)
Returns:
-
Success: Array of found positions
[count][X, Y, Width, Height] - Failure: Empty array with @error set
Example:
; Search for multiple images with scaling Local $aResult = _ImageSearch("icon1.png|icon2.png", 0, 0, 800, 600, -1, 10, 5, 1, 0.8, 1.2, 0.1) If $aResult[0] > 0 Then For $i = 1 To $aResult[0] ConsoleWrite("Match " & $i & " at: " & $aResult[$i][0] & ", " & $aResult[$i][1] & @CRLF) Next EndIf
_ImageSearch_InImage($sSourceImage, $sTargetImage [, $iTolerance [, $iResults [, $iCenterPOS [, $fMinScale [, $fMaxScale [, $fScaleStep [, $iReturnDebug [, $iUseCache]]]]]]]])
Searches for a target image within a source image (file-to-file search).
Parameters:
-
$sSourceImage- Path to source image file -
$sTargetImage- Path to target image file(s), multiple separated by "|" -
Other parameters same as
_ImageSearch
Returns: Same as _ImageSearch
Remarks: Useful for pre-processing images or testing without screen capture
Example:
$aResult = _ImageSearch_InImage("screenshot.png", "button.png", 20)
_ImageSearch_hBitmap($hBitmapSource, $hBitmapTarget [, $iTolerance [, $iLeft [, $iTop [, $iRight [, $iBottom [, $iResults [, $iCenterPOS [, $fMinScale [, $fMaxScale [, $fScaleStep [, $iReturnDebug [, $iUseCache]]]]]]]]]]]])
Searches for a target bitmap within a source bitmap (memory-to-memory search).
Parameters:
-
$hBitmapSource- Handle to source bitmap (HBITMAP) -
$hBitmapTarget- Handle to target bitmap (HBITMAP) -
Other parameters same as
_ImageSearch
Returns: Same as _ImageSearch
Remarks:
- Fastest method for repeated searches (no disk I/O)
- Bitmaps must be created with GDI/GDI+ functions
Screen Capture Functions
_ImageSearch_CaptureScreen([$iLeft, $iTop, $iRight, $iBottom [, $iScreen]])
Capture screen region and return as HBITMAP handle.
Parameters:
-
$iLeft, $iTop, $iRight, $iBottom- Capture region (default: 0 = full screen) -
$iScreen- Monitor index (default: -1 = virtual screen)
Returns:
- Success: HBITMAP handle (must DeleteObject when done)
- Failure: 0 and sets @error
Example:
$hBitmap = _ImageSearch_CaptureScreen(0, 0, 800, 600) ; ... use $hBitmap ... _WinAPI_DeleteObject($hBitmap)
_ImageSearch_ScreenCapture_SaveImage($sImageFile [, $iLeft [, $iTop [, $iRight [, $iBottom [, $iScreen]]]]])
Captures a screen region and saves it directly to an image file in one call.
Parameters:
-
$sImageFile- Output file path (extension determines format: .bmp, .png, .jpg/.jpeg) -
$iLeft, $iTop, $iRight, $iBottom- Capture region (default: 0 = full screen) -
$iScreen- Monitor index (default: 0 = primary screen)
Returns:
- Success: True (1)
- Failure: False (0) and sets @error
Remarks:
- Automatically detects format from file extension
- ~2x faster than separate capture + save operations
- JPEG quality is fixed at 100% (highest quality)
- Uses DPI-aware capture (accurate on all DPI scales)
Example:
; Capture full primary screen to PNG _ImageSearch_ScreenCapture_SaveImage(@ScriptDir & "\screenshot.png") ; Capture region on monitor 2 to JPEG _ImageSearch_ScreenCapture_SaveImage(@ScriptDir & "\region.jpg", 100, 100, 600, 400, 2)
_ImageSearch_hBitmapLoad($sImageFile [, $iAlpha [, $iRed [, $iGreen [, $iBlue]]]])
Load image file and convert to HBITMAP handle.
Parameters:
-
$sImageFile- Path to image file -
$iAlpha, $iRed, $iGreen, $iBlue- Background color components 0-255 (default: 0 = transparent)
Returns:
- Success: HBITMAP handle (must DeleteObject when done)
- Failure: 0 and sets @error
Example:
$hBitmap = _ImageSearch_hBitmapLoad("image.png", 255, 255, 255, 255) ; White background ; ... use $hBitmap ... _WinAPI_DeleteObject($hBitmap)
Mouse Functions
_ImageSearch_MouseMove($iX, $iY [, $iSpeed [, $iScreen]])
Moves mouse cursor to coordinates (supports negative coordinates on multi-monitor).
Parameters:
-
$iX, $iY- Target coordinates (-1 = keep current position) -
$iSpeed- Speed 0-100 (0=instant, default: 0) -
$iScreen- Monitor index (default: -1 = virtual screen)
Returns: 1 on success, 0 on failure
_ImageSearch_MouseClick([$sButton [, $iX [, $iY [, $iClicks [, $iSpeed [, $iScreen]]]]]])
Clicks mouse at coordinates (screen or current position).
Parameters:
-
$sButton- Button: "left", "right", "middle" (default: "left") -
$iX, $iY- Coordinates (-1 = current position) -
$iClicks- Number of clicks (default: 1) -
$iSpeed- Speed 0-100 (0=instant, default: 0) -
$iScreen- Monitor index (default: -1 = virtual screen)
Returns: 1 on success, 0 on failure
_ImageSearch_MouseClickWin($sTitle, $sText, $iX, $iY [, $sButton [, $iClicks [, $iSpeed]]])
Clicks mouse in a window.
Parameters:
-
$sTitle- Window title/class/handle -
$sText- Window text -
$iX, $iY- Relative coordinates in window -
$sButton- Button (default: "left") -
$iClicks- Number of clicks (default: 1) -
$iSpeed- Speed 0-100 (default: 0)
Returns: 1 on success, 0 on failure
Wait & Click Functions
_ImageSearch_Wait($iTimeout, $sImagePath [, $iLeft [, $iTop [, $iRight [, $iBottom [, $iScreen [, $iTolerance [, $iResults [, $iCenterPOS [, $fMinScale [, $fMaxScale [, $fScaleStep [, $iReturnDebug [, $iUseCache [, $iMaxAttempts]]]]]]]]]]]]])
Waits for an image to appear on screen with timeout and optional max attempts limit.
Parameters:
-
$iTimeout- Timeout in milliseconds (0 = wait forever) -
$sImagePath- Image file path(s), multiple separated by "|" -
$iMaxAttempts- Max number of search attempts (0 = unlimited, default: 0) -
Other parameters same as
_ImageSearch
Returns:
-
Success: 2D Array (same as
_ImageSearch) -
Timeout: Empty array with
[0][0] = 0
Example:
; Wait 5 seconds for button (unlimited attempts) $aResult = _ImageSearch_Wait(5000, "button.png") If $aResult[0] > 0 Then MouseClick("left", $aResult[1][0], $aResult[1][1]) Else MsgBox(0, "Timeout", "Button not found") EndIf
_ImageSearch_WaitClick($iTimeout, $sImagePath [, $sButton [, $iClicks [, $iLeft [, $iTop [, $iRight [, $iBottom [, $iScreen [, $iTolerance [, $iResults [, $iCenterPOS [, $fMinScale [, $fMaxScale [, $fScaleStep [, $iReturnDebug [, $iUseCache]]]]]]]]]]]]])
Waits for an image and clicks it when found.
Parameters:
-
$iTimeout- Timeout in milliseconds (0 = wait forever) -
$sImagePath- Image file path(s) -
$sButton- Mouse button: "left", "right", "middle" (default: "left") -
$iClicks- Number of clicks (default: 1) -
Other parameters same as
_ImageSearch
Returns:
- Success: 1 (image found and clicked)
- Timeout: 0 (image not found)
Monitor Functions
_ImageSearch_Monitor_GetList()
Gets a list of all connected display monitors and their properties.
Returns:
- Success: The number of monitors found. @extended contains a detailed log.
- Failure: 0 and sets @error
Remarks:
-
Populates the global
$g_aMonitorList -
Called automatically by
_ImageSearch_Startup
_ImageSearch_Monitor_ToVirtual($iMonitor, $iX, $iY)
Converts local monitor coordinates to virtual screen coordinates.
Parameters:
-
$iMonitor- The 1-based index of the monitor -
$iX, $iY- Coordinates relative to the monitor's top-left corner
Returns:
-
Success: A 2-element array
[$vX, $vY]containing virtual screen coordinates - Failure: 0 and sets @error
_ImageSearch_Monitor_FromVirtual($iMonitor, $iX, $iY)
Converts virtual screen coordinates to local monitor coordinates.
Parameters:
-
$iMonitor- The 1-based index of the monitor -
$iX, $iY- Virtual screen coordinates
Returns:
-
Success: A 2-element array
[$lX, $lY]containing local monitor coordinates - Failure: 0 and sets @error
_ImageSearch_Monitor_Current()
Detects which monitor contains the current mouse cursor position.
Returns:
- Success: Monitor index (1-based) where the cursor is located
- Failure: 0 and sets @error
_ImageSearch_Monitor_GetAtPosition([$iX [, $iY]])
Returns detailed information string about the monitor at specified position.
Parameters:
-
$iX, $iY- Coordinates (default: -1 = use mouse cursor position)
Returns:
- Success: String describing the monitor (e.g., "Monitor 2: 1920x1080 (Primary)")
- Failure: Error message string
Window Coordinate Functions
_ImageSearch_Window_ToScreen($hWnd, $iX, $iY [, $bClientArea])
Converts window-relative coordinates to screen (virtual desktop) coordinates.
Parameters:
-
$hWnd- Window handle or title -
$iX, $iY- Coordinates relative to window -
$bClientArea- True = relative to client area, False = relative to window (default: True)
Returns:
-
Success: A 2-element array
[$screenX, $screenY]containing screen coordinates - Failure: 0 and sets @error
_ImageSearch_Window_FromScreen($hWnd, $iScreenX, $iScreenY [, $bClientArea])
Converts screen (virtual desktop) coordinates to window-relative coordinates.
Parameters:
-
$hWnd- Window handle or title -
$iScreenX, $iScreenY- Screen coordinates -
$bClientArea- True = relative to client area, False = relative to window (default: True)
Returns:
-
Success: A 2-element array
[$winX, $winY]containing window-relative coordinates - Failure: 0 and sets @error
Cache & Info Functions
_ImageSearch_WarmUpCache($sImagePaths [, $bEnableCache])
Pre-loads images into cache for faster subsequent searches.
Parameters:
-
$sImagePaths- Pipe-separated list of images to preload -
$bEnableCache- Enable persistent cache (default: True)
Returns:
- Success: Number of images cached
- Failure: 0
Example:
_ImageSearch_WarmUpCache("btn1.png|btn2.png|icon.png")
_ImageSearch_ClearCache()
Clears the internal bitmap and location cache.
Remarks:
- Useful for freeing memory or forcing re-scan after image updates
- Clears both in-memory cache and persistent disk cache
_ImageSearch_GetDllInfo([$bForceRefresh])
Gets comprehensive DLL information in INI format.
Parameters:
-
$bForceRefresh- Force refresh of cached info (default: True)
Returns: Multi-line string in INI format with sections:
-
[DLL]- DLL name, version, architecture, author -
[OS]- OS name, version, build, platform -
[CPU]- Threads, SSE2, AVX2, AVX512 support -
[SCREEN]- Virtual screen, scale, monitors with individual resolutions -
[CACHE]- Location cache, bitmap cache, pool size
_ImageSearch_GetInfo()
Gets formatted DLL and system information for display.
Returns: Formatted string with DLL info, cache status, and screen information
_ImageSearch_GetDllValue($sSection, $sKey)
Quick accessor to read any value from cached DLL Info.
Parameters:
-
$sSection- Section name (DLL, OS, CPU, SCREEN, CACHE) -
$sKey- Key name
Returns: Value string or "" if not found
Example:
$sVersion = _ImageSearch_GetDllValue("DLL", "Version") $sOSName = _ImageSearch_GetDllValue("OS", "Name") $iThreads = _ImageSearch_GetDllValue("CPU", "Threads")
_ImageSearch_GetLastResult()
Gets the raw DLL return string from the last search.
Returns: Raw result string (e.g., "{2}[100|200|32|32,150|250|32|32]")
Remarks: Useful for debugging or custom parsing
_ImageSearch_GetScale([$iScreen])
Gets the DPI scale factor for a specific monitor as a decimal number.
Parameters:
-
$iScreen- Monitor index (0 = Primary, 1+ = specific monitor number)
Returns: Scale factor as number (e.g., 1.0, 1.25, 1.5) or 0 if not found
Example:
$fScale = _ImageSearch_GetScale(0) ; Get primary monitor scale (e.g., 1.25) $fScale = _ImageSearch_GetScale(2) ; Get monitor 2 scale
Examples
Advanced Search with Multiple Images and Scaling
#include "ImageSearchDLL_UDF.au3" ; Search for multiple UI elements with different scales Local $sImages = "button_ok.png|button_cancel.png|icon_settings.png" Local $aResult = _ImageSearch($sImages, 0, 0, 1920, 1080, -1, 15, 10, 1, 0.8, 1.3, 0.1, 0, 1) If $aResult[0] > 0 Then ConsoleWrite("Found " & $aResult[0] & " matches:" & @CRLF) For $i = 1 To $aResult[0] ConsoleWrite(" Match " & $i & ": X=" & $aResult[$i][0] & ", Y=" & $aResult[$i][1] & ", W=" & $aResult[$i][2] & ", H=" & $aResult[$i][3] & @CRLF) Next Else ConsoleWrite("No matches found" & @CRLF) EndIf
Multi-Monitor Screen Capture
#include "ImageSearchDLL_UDF.au3" ; Get monitor information _ImageSearch_Monitor_GetList() ConsoleWrite("Detected " & $g_aMonitorList[0][0] & " monitors" & @CRLF) ; Capture each monitor separately For $i = 1 To $g_aMonitorList[0][0] Local $sFile = @ScriptDir & "\monitor_" & $i & ".png" _ImageSearch_ScreenCapture_SaveImage($sFile, 0, 0, 0, 0, $i) ConsoleWrite("Captured monitor " & $i & " to: " & $sFile & @CRLF) Next ; Capture entire virtual desktop _ImageSearch_ScreenCapture_SaveImage(@ScriptDir & "\virtual_desktop.png", 0, 0, 0, 0, -1)
Automated UI Testing
#include "ImageSearchDLL_UDF.au3" ; Pre-load images for better performance _ImageSearch_WarmUpCache("login_button.png|username_field.png|password_field.png") ; Wait for login screen and interact If _ImageSearch_WaitClick(10000, "login_button.png") Then ConsoleWrite("Login button clicked" & @CRLF) ; Find username field and click Local $aUsername = _ImageSearch_Wait(5000, "username_field.png") If $aUsername[0] > 0 Then MouseClick("left", $aUsername[1][0], $aUsername[1][1]) Send("myusername") ; Find password field and click Local $aPassword = _ImageSearch_Wait(5000, "password_field.png") If $aPassword[0] > 0 Then MouseClick("left", $aPassword[1][0], $aPassword[1][1]) Send("mypassword") Send("{ENTER}") EndIf EndIf Else MsgBox(0, "Error", "Login screen not found within 10 seconds") EndIf
Error Codes
| Code | Constant | Description |
|---|---|---|
| -1 |
$IMGSE_INVALID_PATH
|
Invalid file path |
| -2 |
$IMGSE_FAILED_TO_LOAD_IMAGE
|
Failed to load image |
| -3 |
$IMGSE_FAILED_TO_GET_SCREEN_DC
|
Failed to get screen device context |
| -4 |
$IMGSE_INVALID_SEARCH_REGION
|
Invalid search region |
| -5 |
$IMGSE_INVALID_PARAMETERS
|
Invalid parameters |
| -6 |
$IMGSE_INVALID_SOURCE_BITMAP
|
Invalid source bitmap |
| -7 |
$IMGSE_INVALID_TARGET_BITMAP
|
Invalid target bitmap |
| -9 |
$IMGSE_RESULT_TOO_LARGE
|
Result too large |
| -10 |
$IMGSE_INVALID_MONITOR
|
Invalid monitor |
Performance Tips
- Use Cache: Enable cache for repeated searches to get 30-50% speed boost
-
Pre-load Images: Use
_ImageSearch_WarmUpCache()during initialization - Limit Search Area: Specify search regions instead of full screen when possible
- Optimize Tolerance: Use appropriate tolerance values (5-15 for most cases)
- Use Appropriate Scale Range: Limit scale range to what you actually need
- Monitor Selection: Use specific monitor index for faster searches on multi-monitor setups
- Image Format: BMP files load faster than PNG/JPG but are larger
-
Memory Management: Always call
_WinAPI_DeleteObject()for HBITMAP handles
Changelog
Version 3.5
- Added thread-local DPI awareness (no GUI resize issues)
- Enhanced multi-monitor support with individual monitor scales
- Improved cache system with persistent disk cache
-
Added
_ImageSearch_ScreenCapture_SaveImage()for direct file saving - Performance optimizations with SIMD instructions
- Better error handling and debugging information
License
This project is licensed under the MIT License - see the LICENSE file for details.
Author
Dao Van Trong - TRONG.PRO
Thank you for using ImageSearch UDF! 🚀
☕ Support My Work
Enjoy my work? Buy me a 🍻 or tip via ❤️ PayPal
Happy Automating! 🚀
___________________________
Edited by Trong
Update document!
What's New in Version v3.5
Released
Fix dll errors. DLL Only applying internal scaling will not affect AutoIT GUI!
