About This File

ImageSearch UDF - AutoIt Wrapper for ImageSearchDLL

Overview

ImageSearchDLL_UDF.au3 is a high-level AutoIt wrapper for ImageSearchDLL, providing easy-to-use functions for image searching, mouse automation, and multi-monitor support. It handles all the complexity of DLL calls and provides a clean, reliable API with built-in error handling and fallback mechanisms.

Author: Dao Van Trong - TRONG.PRO
UDF Version: v3.3
Compatible with: ImageSearchDLL v3.3+
AutoIt Version: 3.3.16.1+
License: MIT License

☕ Support My Work

Enjoy my work? Buy me a 🍻 or tip via ❤️ PayPal

Your support helps me continue developing and maintaining this library for the community! 🙏

Key Features

Search Functions

Screen Search: Find images on screen with multi-monitor support
Image-in-Image Search: Find images within other images
HBITMAP Search: Direct bitmap handle searching
Wait & Click: Wait for image and auto-click when found
Cache Control: Enable/disable persistent caching per search

Mouse Automation (v3.3 Enhanced)

Multi-Monitor Support: 100% reliable on all monitor configurations
Negative Coordinates: Full support via WinAPI SetCursorPos
Click Simulation: WinAPI mouse_event for all button types
Smooth Movement: Optional speed parameter for cursor animation
Window Clicks: Click relative to window positions

Monitor Management

Auto-Detection: Enumerate all connected monitors
Virtual Desktop: Coordinate conversion between monitor and virtual space
Specific Monitor Search: 2-3x faster when searching single monitor
Monitor Info: Get position, size, and primary status

Installation

Include the UDF in your AutoIt script:

#include "ImageSearchDLL_UDF.au3"

Place DLL in same directory as script:
- ImageSearchDLL_x64.dll for x64 AutoIt
- ImageSearchDLL_x86.dll for x86 AutoIt
- Not required, as the DLL is already embedded in the UDF!
Initialize (automatic on first use):

_ImageSearch_Startup()  ; Optional - auto-called if needed

Quick Start Examples

Example 1: Simple Image Search

#include "ImageSearchDLL_UDF.au3"

; Search for image on screen
Local $aResult = _ImageSearch("button.png")

If $aResult[0][0] > 0 Then
    ConsoleWrite("Found at: X=" & $aResult[1][0] & ", Y=" & $aResult[1][1] & @CRLF)
    ; Click the found image
    _ImageSearch_MouseClick("left", $aResult[1][0], $aResult[1][1])
Else
    ConsoleWrite("Image not found" & @CRLF)
EndIf

Example 2: Multi-Monitor Search

#include "ImageSearchDLL_UDF.au3"

; Search on all monitors (virtual desktop)
Local $aResult = _ImageSearch("icon.png", 0, 0, 0, 0, -1)

; OR search on specific monitor (faster!)
Local $aResult = _ImageSearch("icon.png", 0, 0, 0, 0, 2) ; Monitor 2

If $aResult[0][0] > 0 Then
    ConsoleWrite("Found " & $aResult[0][0] & " match(es)" & @CRLF)
    For $i = 1 To $aResult[0][0]
        ConsoleWrite("Match " & $i & ": X=" & $aResult[$i][0] & ", Y=" & $aResult[$i][1] & @CRLF)
    Next
EndIf

Example 3: Wait and Click

#include "ImageSearchDLL_UDF.au3"

; Wait up to 5 seconds for image, then click it
Local $iResult = _ImageSearch_WaitClick(5000, "submit.png", "left", 1)

If $iResult Then
    ConsoleWrite("Image found and clicked!" & @CRLF)
Else
    ConsoleWrite("Timeout - image not found" & @CRLF)
EndIf

Example 4: Find All Occurrences

#include "ImageSearchDLL_UDF.au3"

; Find all matches (up to 10)
Local $aResult = _ImageSearch("item.png", 0, 0, 0, 0, -1, 10, 10)

If $aResult[0][0] > 0 Then
    For $i = 1 To $aResult[0][0]
        ConsoleWrite("Match " & $i & ": ")
        ConsoleWrite("X=" & $aResult[$i][0] & ", Y=" & $aResult[$i][1])
        ConsoleWrite(", W=" & $aResult[$i][2] & ", H=" & $aResult[$i][3] & @CRLF)
    Next
EndIf

Example 5: Image-in-Image Search

#include "ImageSearchDLL_UDF.au3"

; Search for button.png within screenshot.png
Local $aResult = _ImageSearch_InImage("screenshot.png", "button.png", 15, 5)

If $aResult[0][0] > 0 Then
    ConsoleWrite("Found " & $aResult[0][0] & " match(es) in image" & @CRLF)
EndIf

Example 6: Region Search with Tolerance

#include "ImageSearchDLL_UDF.au3"

; Search in specific region with high tolerance
Local $aResult = _ImageSearch("target.png", 100, 100, 800, 600, -1, 20)

If $aResult[0][0] > 0 Then
    ConsoleWrite("Found at: " & $aResult[1][0] & ", " & $aResult[1][1] & @CRLF)
EndIf

Example 7: Cache-Enabled Search

#include "ImageSearchDLL_UDF.au3"

; Enable cache for 30-50% performance boost on repeated searches
Local $aResult = _ImageSearch("icon.png", 0, 0, 0, 0, -1, 10, 1, 1, 1.0, 1.0, 0.1, 0, 1)
;                                                                                       ↑
;                                                                               iUseCache=1

If $aResult[0][0] > 0 Then
    ConsoleWrite("Found (cached search): " & $aResult[1][0] & ", " & $aResult[1][1] & @CRLF)
EndIf

Example 8: Monitor Management

#include "ImageSearchDLL_UDF.au3"

; Get monitor information
_ImageSearch_Monitor_GetList()

ConsoleWrite("Total monitors: " & $g_aMonitorList[0][0] & @CRLF)

For $i = 1 To $g_aMonitorList[0][0]
    ConsoleWrite("Monitor " & $i & ": " & _
        $g_aMonitorList[$i][5] & "x" & $g_aMonitorList[$i][6] & _
        ($g_aMonitorList[$i][7] ? " (Primary)" : "") & @CRLF)
Next

; Convert coordinates between monitor and virtual desktop
Local $aVirtual = _ImageSearch_Monitor_ToVirtual(2, 100, 200)
ConsoleWrite("Monitor 2 (100,200) = Virtual (" & $aVirtual[0] & "," & $aVirtual[1] & ")" & @CRLF)

Core Functions Reference

Search Functions

_ImageSearch()

_ImageSearch($sImagePath, [$iLeft=0], [$iTop=0], [$iRight=0], [$iBottom=0], 
             [$iScreen=-1], [$iTolerance=10], [$iResults=1], [$iCenterPOS=1], 
             [$fMinScale=1.0], [$fMaxScale=1.0], [$fScaleStep=0.1], 
             [$iReturnDebug=0], [$iUseCache=0])

Parameters:

$sImagePath - Image file path (or multiple: "img1.png|img2.png")
$iLeft, $iTop, $iRight, $iBottom - Search region (0 = full screen)
$iScreen - Monitor: -1=all, 0=primary, 1=first, 2=second, etc.
$iTolerance - Color tolerance 0-255
$iResults - Max results to return (1-64)
$iCenterPOS - 1=return center, 0=return top-left
$fMinScale, $fMaxScale, $fScaleStep - Scaling parameters
$iReturnDebug - 1=enable debug output
$iUseCache - 1=enable cache, 0=disable

Returns:

Array[0][0] = match count
Array[1..n][0] = X coordinate
Array[1..n][1] = Y coordinate
Array[1..n][2] = Width
Array[1..n][3] = Height

_ImageSearch_InImage()

_ImageSearch_InImage($sSourceImage, $sTargetImage, [$iTolerance=10], 
                     [$iResults=1], [$iCenterPOS=1], [$fMinScale=1.0], 
                     [$fMaxScale=1.0], [$fScaleStep=0.1], [$iReturnDebug=0], 
                     [$iUseCache=0])

Search for target image(s) within a source image file.

_ImageSearch_Wait()

_ImageSearch_Wait($iTimeout, $sImagePath, [$iLeft=0], [$iTop=0], 
                  [$iRight=0], [$iBottom=0], [$iScreen=-1], [$iTolerance=10], 
                  [$iResults=1], [$iCenterPOS=1], [$fMinScale=1.0], 
                  [$fMaxScale=1.0], [$fScaleStep=0.1], [$iReturnDebug=0], 
                  [$iUseCache=0])

Wait for image to appear (with timeout in milliseconds).

_ImageSearch_WaitClick()

_ImageSearch_WaitClick($iTimeout, $sImagePath, [$sButton="left"], 
                       [$iClicks=1], [$iLeft=0], [$iTop=0], [$iRight=0], 
                       [$iBottom=0], [$iScreen=-1], [$iTolerance=10], 
                       [$iResults=1], [$iCenterPOS=1], [$fMinScale=1.0], 
                       [$fMaxScale=1.0], [$fScaleStep=0.1], [$iReturnDebug=0], 
                       [$iUseCache=0])

Wait for image and automatically click it when found.

Mouse Functions (v3.3 Enhanced)

_ImageSearch_MouseMove()

_ImageSearch_MouseMove($iX, $iY, [$iSpeed=0], [$iScreen=-1])

Move mouse cursor to coordinates. Supports negative coordinates for multi-monitor.

Uses WinAPI SetCursorPos for 100% reliability
$iSpeed - 0=instant, >0=smooth movement with steps

_ImageSearch_MouseClick()

_ImageSearch_MouseClick([$sButton="left"], [$iX=-1], [$iY=-1], 
                        [$iClicks=1], [$iSpeed=0], [$iScreen=-1])

Click mouse at coordinates. Supports negative coordinates for multi-monitor.

Uses WinAPI mouse_event for reliable clicking
$sButton - "left", "right", "middle"
$iX, $iY - Virtual desktop coordinates (-1 = current position)

_ImageSearch_MouseClickWin()

_ImageSearch_MouseClickWin($sTitle, $sText, $iX, $iY, 
                           [$sButton="left"], [$iClicks=1], [$iSpeed=0])

Click at window-relative coordinates.

Monitor Functions

_ImageSearch_Monitor_GetList()

_ImageSearch_Monitor_GetList()

Enumerate all monitors and populate $g_aMonitorList array.

Global Array Structure:

$g_aMonitorList[0][0] = Total monitor count
$g_aMonitorList[i][0] = Handle
$g_aMonitorList[i][1] = Left
$g_aMonitorList[i][2] = Top
$g_aMonitorList[i][3] = Right
$g_aMonitorList[i][4] = Bottom
$g_aMonitorList[i][5] = Width
$g_aMonitorList[i][6] = Height
$g_aMonitorList[i][7] = IsPrimary (1/0)
$g_aMonitorList[i][8] = Device name

_ImageSearch_Monitor_ToVirtual()

_ImageSearch_Monitor_ToVirtual($iMonitor, $iX, $iY)

Convert monitor-relative coordinates to virtual desktop coordinates.

_ImageSearch_Monitor_FromVirtual()

_ImageSearch_Monitor_FromVirtual($iMonitor, $iX, $iY)

Convert virtual desktop coordinates to monitor-relative coordinates.

Utility Functions

_ImageSearch_CaptureScreen()

_ImageSearch_CaptureScreen([$iLeft=0], [$iTop=0], [$iRight=0], 
                           [$iBottom=0], [$iScreen=-1])

Capture screen region as HBITMAP handle.

_ImageSearch_hBitmapLoad()

_ImageSearch_hBitmapLoad($sImageFile, [$iAlpha=0], [$iRed=0], 
                         [$iGreen=0], [$iBlue=0])

Load image file as HBITMAP with optional background color.

_ImageSearch_GetVersion()

_ImageSearch_GetVersion()

Get DLL version string.

_ImageSearch_GetSysInfo()

_ImageSearch_GetSysInfo()

Get system info (CPU, screen, cache stats).

_ImageSearch_ClearCache()

_ImageSearch_ClearCache()

Clear all DLL caches (location and bitmap).

Performance Tips

Cache System

Enable caching for repeated searches: $iUseCache=1
30-50% faster on subsequent searches
Persistent across script runs
Auto-validated (removes stale entries)

Multi-Monitor Optimization

Use specific monitor ($iScreen=1 or 2) for 2-3x faster search
Use virtual desktop ($iScreen=-1) only when needed
Coordinates are always in virtual desktop space (may be negative)

Search Optimization

Smaller region = faster search
Higher tolerance = faster but less accurate
Fewer results ($iResults=1) = faster
Disable debug in production ($iReturnDebug=0)

Version 3.3 Improvements

Fixed Issues

✅ Multi-Monitor Mouse Movement - Now 100% reliable using WinAPI ✅ Negative Coordinates - Full support for monitors positioned left/above primary ✅ Mouse Click Reliability - WinAPI mouse_event never fails ✅ Coordinate Conversion - Proper handling of virtual desktop space

Enhanced Features

Debug logging shows actual mouse position after move
Better error handling with meaningful error codes
All mouse functions bypass DLL for maximum reliability
Smooth cursor movement with customizable speed

Breaking Changes

Mouse functions no longer rely on DLL implementation
Always use WinAPI for mouse operations (more reliable)

Troubleshooting

"DLL not found" Error

Ensure DLL is in same directory as script
Use correct architecture (x64 vs x86)
Check with FileExists($g_sImgSearchDLL_Path)

Mouse Not Moving on Second Monitor

✅ Fixed in v3.3! Now uses WinAPI SetCursorPos
Coordinates are virtual desktop (may be negative)
Update to UDF v3.3 or later

Image Not Found

Check image file exists
Increase tolerance ($iTolerance=20)
Enable debug ($iReturnDebug=1) to see search info
Try different region/monitor settings

Slow Search Performance

Enable cache ($iUseCache=1)
Use specific monitor instead of all monitors
Reduce search region
Lower max results

Example: Complete Script

#include "ImageSearchDLL_UDF.au3"

; Initialize
_ImageSearch_Startup()

; Show system info
ConsoleWrite("UDF: " & $IMGS_UDF_VERSION & @CRLF)
ConsoleWrite("DLL: " & _ImageSearch_GetVersion() & @CRLF)
ConsoleWrite(_ImageSearch_GetSysInfo() & @CRLF)

; Search for image with cache enabled
Local $aResult = _ImageSearch("target.png", 0, 0, 0, 0, -1, 10, 5, 1, 1.0, 1.0, 0.1, 1, 1)

If $aResult[0][0] > 0 Then
    ConsoleWrite("Found " & $aResult[0][0] & " match(es):" & @CRLF)
    
    For $i = 1 To $aResult[0][0]
        ConsoleWrite("  Match " & $i & ": ")
        ConsoleWrite("X=" & $aResult[$i][0] & ", Y=" & $aResult[$i][1])
        ConsoleWrite(", W=" & $aResult[$i][2] & ", H=" & $aResult[$i][3] & @CRLF)
        
        ; Move mouse and click
        _ImageSearch_MouseMove($aResult[$i][0], $aResult[$i][1], 10)
        Sleep(500)
        _ImageSearch_MouseClick("left", $aResult[$i][0], $aResult[$i][1])
        Sleep(1000)
    Next
Else
    ConsoleWrite("No matches found" & @CRLF)
EndIf

; Cleanup
_ImageSearch_Shutdown()

License & Contact

Author: Dao Van Trong
Website: TRONG.PRO
Email: trong@email.com
License: MIT License
AutoIt Forum: Post in AutoIt General Help

What's New in Version v3.3

Released Yesterday at 01:31 AM

💢 Note: There are a lot of changes that break the script (DLL & UDF)! 👈

v3.3

ImageSearchUDF v3.3

1 Screenshot

About This File

ImageSearch UDF - AutoIt Wrapper for ImageSearchDLL

Overview

☕ Support My Work

Key Features

Search Functions

Mouse Automation (v3.3 Enhanced)

Monitor Management

Installation

Quick Start Examples

Example 1: Simple Image Search

Example 2: Multi-Monitor Search

Example 3: Wait and Click

Example 4: Find All Occurrences

Example 5: Image-in-Image Search

Example 6: Region Search with Tolerance

Example 7: Cache-Enabled Search

Example 8: Monitor Management

Core Functions Reference

Search Functions

_ImageSearch()

_ImageSearch_InImage()

_ImageSearch_Wait()

_ImageSearch_WaitClick()

Mouse Functions (v3.3 Enhanced)

_ImageSearch_MouseMove()

_ImageSearch_MouseClick()

_ImageSearch_MouseClickWin()

Monitor Functions

_ImageSearch_Monitor_GetList()

_ImageSearch_Monitor_ToVirtual()

_ImageSearch_Monitor_FromVirtual()

Utility Functions

_ImageSearch_CaptureScreen()

_ImageSearch_hBitmapLoad()

_ImageSearch_GetVersion()

_ImageSearch_GetSysInfo()

_ImageSearch_ClearCache()

Performance Tips

Cache System

Multi-Monitor Optimization

Search Optimization

Version 3.3 Improvements

Fixed Issues

Enhanced Features

Breaking Changes

Troubleshooting

"DLL not found" Error

Mouse Not Moving on Second Monitor

Image Not Found

Slow Search Performance

Example: Complete Script

License & Contact

See Also

What's New in Version v3.3

User Feedback

Similar Content