Jump to content

ImageSearchUDF beta 1.0.0

   (1 review)
Trong
 Share

1 Screenshot

About This File

ImageSearchDLL & UDF - The Complete Guide

Author: Dao Van Trong - TRONG.PRO

Last Updated: 2025-08-04

1. Introduction

ImageSearchDLL is a high-performance image recognition solution for Windows, designed to be both powerful for modern systems and compatible with legacy environments. The project consists of three distinct C++ DLL versions and a smart AutoIt User-Defined Function (UDF) that automatically selects the best DLL for the job.

This architecture ensures that your scripts get the best possible performance on modern systems (like Windows 10/11) while maintaining full functionality on older systems like Windows 7 and even Windows XP.

New is the Special Feature is the function of searching for pictures in pictures!

2. How it Works: The Smart UDF Loader

The core of this project is the AutoIt UDF (ImageSearch_UDF.au3). You don’t need to worry about which DLL to use; the _ImageSearch_Startup() function handles it all automatically.

Here is the loading logic:

  1. On Modern OS (Windows 8, 10, 11+):
    • It first looks for the Modern DLL (ImageSearch_x64.dll or ImageSearch_x86.dll).
    • If not found, it falls back to the Windows 7 DLL.
    • If neither is found, it deploys the Embedded XP DLL.
  2. On Windows 7:
    • It prioritizes the Windows 7 DLL (ImageSearch_Win7_x64.dll or ImageSearch_Win7_x86.dll).
    • If not found, it deploys the Embedded XP DLL.
  3. On Windows XP:
    • It exclusively uses the Embedded XP DLL, which is extracted from a HEX string inside the UDF.

This ensures maximum performance where possible and maximum compatibility where needed.

3. The DLL Versions Explained

There are three distinct DLLs, each compiled for a specific purpose.

Feature Modern (Win10+) Windows 7 Legacy (XP)
Target OS Windows 8, 10, 11+ Windows 7 SP1+ Windows XP SP3+
Filename ImageSearch_x64.dll
ImageSearch_x86.dll 		ImageSearch_Win7_x64.dll
ImageSearch_Win7_x86.dll 		Embedded in UDF
Compiler VS 2022 (C++23) VS 2017+ (C++14) VS 2010 (C++03)
Performance Excellent Very Good Good
AVX2 Support Yes (auto-detected) Yes (auto-detected) No
Thread-Safety Yes (thread_local) Yes (thread_local) No (static buffer)
Best Use Case High-performance automation on modern PCs. Scripts that need to run reliably on both modern systems and Windows 7 machines. Maximum compatibility for legacy systems or when no external DLLs are provided.

4. Getting Started (For AutoIt Users)

Using the library is simple. Just make sure your files are organized correctly.

File Structure

For the best experience, place the DLL files in the same directory as your script and the UDF.

/YourScriptFolder/
|
|-- MyScript.au3
|-- ImageSearch_UDF.au3
|-- ImageSearch_x64.dll (Modern DLL for 64-bit)
|-- ImageSearch_x86.dll (Modern DLL for 32-bit)
|-- ImageSearch_Win7_x64.dll (Win7 DLL for 64-bit)
|-- ImageSearch_Win7_x86.dll (Win7 DLL for 32-bit)
|
/-- images/
|-- button.png

Quick Start Example

Here is a basic AutoIt script to get you started. 

#include "ImageSearch_UDF.au3"

; 1. Initialize the library. The UDF will automatically load the best DLL.  
_ImageSearch_Startup()  
If @error Then  
    MsgBox(16, "Error", "ImageSearch DLL could not be initialized. Exiting.")  
    Exit  
EndIf

; You can check which version was loaded  
ConsoleWrite(">> Loaded DLL Version: " & _ImageSearch_GetVersion() & @CRLF)  
ConsoleWrite(">> System Info: " & _ImageSearch_GetSysInfo() & @CRLF)

; 2. Perform a search for an image on the entire screen.  
Local $sImagePath = @ScriptDir & "\images\button.png"  
Local $aResult = _ImageSearch($sImagePath)

; 3. Process the results. The result is ALWAYS a 2D array.  
If $aResult[0][0] > 0 Then  
    ConsoleWrite("Found " & $aResult[0][0] & " match(es)!" & @CRLF)  
    ; Loop through each match  
    For $i = 1 To $aResult[0][0]  
        Local $iX = $aResult[$i][1] ; X coordinate  
        Local $iY = $aResult[$i][2] ; Y coordinate  
        ConsoleWrite("Match #" & $i & " found at: " & $iX & ", " & $iY & @CRLF)  
        MouseMove($iX, $iY, 20)  
        Sleep(1000)  
    Next  
Else  
    ConsoleWrite("Image not found." & @CRLF)  
EndIf

; 4. Shutdown is handled automatically when the script exits. No need to call _ImageSearch_Shutdown().

 

5. Full API Reference

Main Functions

  • _ImageSearch_Area(…): The main function with all available options.
  • _ImageSearch(…): A simplified wrapper for searching the entire screen.
  • _ImageInImageSearch_Area(…): Searches for an image within another image file.

Common Parameters

Parameter Description Default
$sImageFile Path to the image(s). Use | to search for multiple images.  
$iLeft, $iTop, $iRight, $iBottom The coordinates of the search area. Entire Screen
$iTolerance Color tolerance (0-255). Higher values allow for more variation. 10
$iTransparent A color in 0xRRGGBB format to be ignored during the search. -1 (disabled)
$iMultiResults The maximum number of results to return. 1
$iCenterPos 1 returns the center coordinates; 0 returns the top-left. 1
$fMinScale, $fMaxScale Minimum and maximum scaling factor (e.g., 0.8 for 80%). 1.0
$fScaleStep The increment between scales (e.g., 0.1 for 10% steps). 0.1
$iFindAllOccurrences 1 finds all matches; 0 stops after the first. 0
$iUseCache 1 enables the file-based location cache; 0 disables it. 1
$iDisableAVX2 1 disables AVX2 optimization (for debugging). 0

Return Value

All search functions return a 2D array.

  • $aResult[0][0]: Contains the number of matches found.
  • For each match $i (from 1 to $aResult[0][0]):
    • aResult[aResult[i][1]: X coordinate
    • aResult[aResult[i][2]: Y coordinate
    • aResult[aResult[i][3]: Width of the found image
    • aResult[aResult[i][4]: Height of the found image

Utility Functions

  • _ImageSearch_GetVersion(): Returns the version string of the currently loaded DLL.
  • _ImageSearch_GetSysInfo(): Returns system info from the DLL (AVX2 support, screen resolution).
  • _ImageSearch_ClearCache(): Deletes all cache files from the temp directory.
 Share
Previous File ImageSearchUDF

User Feedback

You may only provide a review once you have downloaded the file.

Steven2025

Steven2025 0

  

Thank you for sharing the updated version. I noticed the reference to wrapper functions like _ImageSearch_Wait and _ImageInImageSearch in your post. Could you please clarify:

  1. Are these functions meant to be implemented in AutoIt (AU3) or are they part of a C++ extension?

  2. If they're AutoIt functions, would you be able to share:

    • The required function prototypes

    • Key parameters they should accept

  3. If they're C++ based:

    • Is there a header file or DLL interface we should reference?

Response from the author:

All the functionality is done by c++ dll, AuttoIt is just the user and handler of the results.

If you have seen UDF, you will understand immediately without looking at Dll code.

Here is the header code for you to visualize: 

// =================================================================================================
//
//  Project .........: ImageSearchDLL - High-Performance Image Search Library
//  File ............: ImageSearchDLL.h
//  Description .....: Public C-style header for using the ImageSearchDLL.
//                    This file provides the function declarations necessary to link against
//                    and use the ImageSearchDLL from C/C++ applications or other languages
//                    that can interoperate with standard C DLLs.
//
//  Integration .....: To use this DLL in your project:
//                    1. #include "ImageSearchDLL.h" in your source code.
//                    2. Link against the ImageSearchDLL.lib file in your project's settings.
//                    3. Ensure the ImageSearchDLL.dll is in the same directory as your
//                       executable or in a directory listed in the system's PATH.
//
//  Author(s) .......: Dao Van Trong - TRONG.PRO
//  Last Updated ....: 2025-08-04
//
// =================================================================================================

#ifndef IMAGE_SEARCH_DLL_H
#define IMAGE_SEARCH_DLL_H

// Use standard Windows calling convention
#include <windows.h>

// The __declspec(dllimport) is used by the consumer of the DLL.
// When building the DLL itself, you would define IMAGE_SEARCH_DLL_EXPORTS
// so that the symbols are exported.
#ifdef IMAGE_SEARCH_DLL_EXPORTS
#define IMAGE_SEARCH_API __declspec(dllexport)
#else
#define IMAGE_SEARCH_API __declspec(dllimport)
#endif

// Ensure C-style linkage to prevent name mangling, allowing the DLL
// to be used by a wide variety of compilers and languages.
#ifdef __cplusplus
extern "C" {
#endif

// =================================================================================================
// #BLOCK# CORE SEARCH FUNCTIONS
//
// These are the primary functions for finding images on the screen or within other images.
// They offer a rich set of parameters to control the search behavior, including tolerance,
// scaling, multi-image support, and caching.
// =================================================================================================

/**
 * @brief Searches for one or more images on the screen within a specified region.
 * @details This is the main function for screen-based image searches. It can search for multiple
 * images, apply scaling, tolerate color variations, and use caching to speed up
 * repeated searches. The function returns its results in a formatted wide string.
 *
 * @param sImageFile          Path to the image file(s) to find. Multiple paths can be joined with a '|' delimiter.
 * @param iLeft               (Default: 0) The left boundary of the screen search area.
 * @param iTop                (Default: 0) The top boundary of the screen search area.
 * @param iRight              (Default: 0) The right boundary. If 0, extends to the full screen width.
 * @param iBottom             (Default: 0) The bottom boundary. If 0, extends to the full screen height.
 * @param iTolerance          (Default: 10) Color tolerance from 0 (exact match) to 255.
 * @param iTransparent        (Default: 0xFFFFFFFF) A color in 0xRRGGBB format to be ignored during the search. 0xFFFFFFFF disables this feature.
 * @param iMultiResults       (Default: 0) The maximum number of results to return. If 0, returns all found matches.
 * @param iCenterPOS          (Default: 1) If 1, returns the center coordinates; otherwise, returns the top-left coordinates.
 * @param iReturnDebug        (Default: 0) If 1, appends a detailed debug string to the result.
 * @param fMinScale           (Default: 1.0f) The minimum scaling factor for the search (e.g., 0.8 for 80%).
 * @param fMaxScale           (Default: 1.0f) The maximum scaling factor for the search (e.g., 1.2 for 120%).
 * @param fScaleStep          (Default: 0.1f) The increment between scaling factors (e.g., 0.1 for 10% steps).
 * @param iFindAllOccurrences (Default: 0) If 0, stops after the first match. If 1, finds all occurrences of all specified images.
 * @param iUseCache           (Default: 1) If 1, enables the file-based location cache; 0 disables it.
 * @param iDisableAVX2        (Default: 0) If 1, forces the use of the slower, more compatible scalar search algorithm.
 * @return A constant wide string pointer.
 * - On Success: "{count}[x1|y1|w1|h1,x2|y2|w2|h2,...]"
 * - On Failure: "{errorCode}[error message]"
 * The returned buffer is thread-local and valid until the next call on the same thread.
 */
IMAGE_SEARCH_API const wchar_t* WINAPI ImageSearch(
    const wchar_t* sImageFile,
    int iLeft, int iTop, int iRight, int iBottom,
    int iTolerance,
    int iTransparent,
    int iMultiResults,
    int iCenterPOS,
    int iReturnDebug,
    float fMinScale, float fMaxScale, float fScaleStep,
    int iFindAllOccurrences,
    int iUseCache,
    int iDisableAVX2
);

/**
 * @brief Searches for one or more "target" images within a larger "source" image file.
 * @details This function finds all occurrences of a small image (needle) inside a larger
 * image (haystack), both loaded from files. It supports the same advanced features
 * as the screen search, such as tolerance, scaling, and caching.
 *
 * @param sSourceImageFile    Path to the source image file (the image to be searched).
 * @param sTargetImageFile    Path to the target image file(s) to find. Multiple paths can be joined with '|'.
 * @param iTolerance          (Default: 10) Color tolerance from 0 (exact match) to 255.
 * @param iTransparent        (Default: 0xFFFFFFFF) A color in 0xRRGGBB format to be ignored. 0xFFFFFFFF disables this feature.
 * @param iMultiResults       (Default: 0) The maximum number of results to return. If 0, returns all.
 * @param iCenterPOS          (Default: 1) If 1, returns center coordinates; otherwise, top-left.
 * @param iReturnDebug        (Default: 0) If 1, appends a debug string to the result.
 * @param fMinScale           (Default: 1.0f) The minimum scaling factor for the target image.
 * @param fMaxScale           (Default: 1.0f) The maximum scaling factor for the target image.
 * @param fScaleStep          (Default: 0.1f) The increment between scaling factors.
 * @param iFindAllOccurrences (Default: 0) If 0, stops after the first match. If 1, finds all occurrences.
 * @param iUseCache           (Default: 1) If 1, enables caching; 0 disables it.
 * @param iDisableAVX2        (Default: 0) If 1, forces the scalar search algorithm.
 * @return A constant wide string pointer with the same format as ImageSearch.
 * The returned buffer is thread-local and valid until the next call on the same thread.
 */
IMAGE_SEARCH_API const wchar_t* WINAPI ImageInImageSearch(
    const wchar_t* sSourceImageFile,
    const wchar_t* sTargetImageFile,
    int iTolerance,
    int iTransparent,
    int iMultiResults,
    int iCenterPOS,
    int iReturnDebug,
    float fMinScale,
    float fMaxScale,
    float fScaleStep,
    int iFindAllOccurrences,
    int iUseCache,
    int iDisableAVX2
);

// =================================================================================================
// #BLOCK# SIMPLIFIED WRAPPER FUNCTIONS
//
// These functions provide a simpler interface to the core search capabilities by using
// common default parameters. They are ideal for quick and simple search tasks.
// =================================================================================================

/**
 * @brief A simplified wrapper for ImageSearch with common default parameters.
 * @details Searches the entire screen for a single instance of an image using default settings
 * (10 tolerance, caching enabled, center position returned, no scaling).
 *
 * @param sImageFile   Path to the image file to find.
 * @param iTolerance   (Default: 10) Color tolerance value.
 * @param iDisableAVX2 (Default: 0) Set to 1 to disable AVX2 optimization.
 * @return A constant wide string pointer with the search result.
 */
IMAGE_SEARCH_API const wchar_t* WINAPI SimpleImageSearch(
    const wchar_t* sImageFile,
    int iTolerance,
    int iDisableAVX2
);

/**
 * @brief A simplified wrapper for ImageInImageSearch with common default parameters.
 * @details Searches a source image for a single instance of a target image using default settings.
 *
 * @param sSourceImageFile Path to the source (haystack) image.
 * @param sTargetImageFile Path to the target (needle) image.
 * @param iTolerance       (Default: 10) Color tolerance value.
 * @param iDisableAVX2     (Default: 0) Set to 1 to disable AVX2 optimization.
 * @return A constant wide string pointer with the search result.
 */
IMAGE_SEARCH_API const wchar_t* WINAPI SimpleImageInImageSearch(
    const wchar_t* sSourceImageFile,
    const wchar_t* sTargetImageFile,
    int iTolerance,
    int iDisableAVX2
);

// =================================================================================================
// #BLOCK# UTILITY FUNCTIONS
//
// Supplementary functions for managing the DLL's cache and retrieving version or system info.
// =================================================================================================

/**
 * @brief Clears the in-memory and persistent file-based image location cache.
 * @details Call this function to force the DLL to perform fresh searches instead of using
 * cached results. It deletes all "~CACHE_IMGSEARCHDLL_*.dat" files from the
 * system's temporary directory.
 */
IMAGE_SEARCH_API void WINAPI ClearImageCache();

/**
 * @brief Returns the version string of the DLL.
 * @return A constant wide string pointer containing the DLL version (e.g., "ImageSearchDLL v2025.8.4.1 AVX2").
 */
IMAGE_SEARCH_API const wchar_t* WINAPI GetDLLVersion();

/**
 * @brief Returns system information relevant to the DLL's operation.
 * @return A thread-local wide string buffer with info about AVX2 support, screen resolution, and cache directory.
 * Example: "AVX2 Support: Yes, Screen: 1920x1080, Cache Dir: C:\Users\...\Temp"
 */
IMAGE_SEARCH_API const wchar_t* WINAPI GetSysInfo();

#ifdef __cplusplus
}
#endif

#endif // IMAGE_SEARCH_DLL_H

!

 

×
×
  • Create New...