^ What's the point?
^ Requirements
^ Compare (search) modes
^ Pre-process the images
^ Loading a picture from HBitmap
^ Loading a picture from memory
^ Note on OpenCL info strings
^ Using the search and load queue
^ Free Image Library

Download :: Topics on this subject on the Forum :: Top
Image Recognition Library

Image Recognition Library is a component for use in Win32 and Win64 (2K/XP/Vista/7/8/10) software with a purpose to provide image recognition functionality, that is compare two pictures if they are the same or similar or find a smaller picture in a bigger picture with difference tolerance.

Features:
  • Exact, relative ARGB and AHSL, rotated search modes with alpha channel support
  • Pre-process images with 6 different resamplers
  • Multi-threaded processing
  • Multiple match support
  • OpenCL accelerated search
  • A fully multi-threaded loading queue functionality for batch loading of pictures
  • A fully multi-threaded search queue functionality for batch processing with support of parallel CPU-OpenCL processing a the same time
  • Full unicode support
  • Platforms: Win32 and Win64
  • Delphi and C++ API included
You should also see the included example programs's source-codes for example of how to use Image Recognition Library in your own programs.


Requirements
  • Delphi 2009 or a developer environment that supports the stdcall calling convention.

Image Recognition Library in shareware and commercial software?

The component can be evaluated for free. If like it and use it for freeware, shareware and commercial software one of the licenses is needed.


Compare (search) modes
  • IR_COMPARE_TYPE_EXACT: Perform an exact search with an allowed pixel difference count. This requires that the search for bitmap is pixel identical with the search in bitmap, although you can set a "DifferenceTolerance" value to allow a concrete pixel count to differ. Exact mode is the fastest of the available modes.

  • IR_COMPARE_TYPE_RELATIVE_ARGB: Perform a search with an allowed pixel difference in Alpha-Red-Green-Blue color space. This mode is usefull when searching a similar picture in another picture. Setting a "DifferenceTolerance" value will allow a concrete pixel count to differ completly. This mode is slower than exact mode but faster than AHSL mode.

  • IR_COMPARE_TYPE_RELATIVE_AHSL: Perform a search with an allowed pixel difference in Alpha-Hue-Saturation-Lightness color space. AHSL component values range from 0 to 1. This mode is usefull when searching a similar picture in another picture but AHSL mode is required. Setting a "DifferenceTolerance" value will allow a concrete pixel count to differ completly.

  • IR_COMPARE_TYPE_RELATIVE_ARGB_ALPHA: Same as ARGB but the search for bitmap's pixels transparency value (alpha chanel) is considered when searching. Usefull when searching for a non-rectangular image, for example to find a logo put on a picture with transparency. Recommended that the search for bitmap is a PNG image with transparency. Slower then ARGB mode.

  • IR_COMPARE_TYPE_RELATIVE_AHSL_ALPHA: Same as AHSL but the search for bitmap's pixels transparency value (alpha chanel) is considered when searching. Usefull when searching for a non-rectangular image, for example to find a logo put on a picture with transparency but AHSL mode is required. Recommended that the search for bitmap is a PNG image with transparency. This is the slowest of the available modes.
OpenCL accelerated search right now is supported with IR_COMPARE_TYPE_EXACT and IR_COMPARE_TYPE_RELATIVE_ARGB_ALPHA.

Rotate search is supported with only IR_COMPARE_TYPE_RELATIVE_ARGB_ALPHA.


Pre-process the images

It can be usefull to resize the images when loading for faster processing and also usefull if you want to compare two images that differ in dimensions. When acquireing the picture object specify the "ProcessType" parameter of the "TIRCreateObjectParameters" structure to "IR_PROCESS_TYPE_RESAMPLE". And specify a resampler ("Resampler" variable).
Resampling the images is performed by FreeImage.dll.


Loading a picture from HBitmap

Use the "ImageRecognition_CreateObjectFromBitmapHandle()" to load a HBitmap.

For example:

var
    Bitmap: TBitmap;
begin
    FreeImageLoadImage('C:\MyPicture.png', Bitmap, Handle);
    ImageRecognition_CreateObjectFromHandle(Bitmap.Handle, IRObjectSearchIn, IRCreateObjectParameters);
end;

Loading a picture from memory

Use the "ImageRecognition_CreateObjectFromMemory()" to load a picture from memory. FreeImage.dll is used internally to load the picture.

For example:

var
    MemoryStream: TMemoryStream;
begin
    MemoryStream := TMemoryStream.Create;
    try
        MemoryStream.LoadFromFile('C:\MyPicture.png');
        ImageRecognition_CreateObjectFromMemory(MemoryStream.Memory, MemoryStream.Size, IRObjectSearchIn, IRCreateObjectParameters);
    finally
        FreeAndNil(MemoryStream);
    end;
end;

Note on OpenCL info strings

The pointers to wide chars returned by 'ImageRecognition_OpenCLGetPlatform' and 'ImageRecognition_OpenCLGetPlatformDevice' are only valid until the according function is called again. So make a copy of the strings if they are needed afterwards.


Using the search and load queue

The search queue can be used to automatically process objects multi-threaded, use multiple OpenCL devices in parallel at the same time, and also to use mixed-mode CPU/OpenCL processing for additional speed.
It can be configured to use just multiple OpenCL devices in parallel or just multiple CPU cores in parallel too as needed.

When adding work to the queue the jobs will be automatically assigned either to the CPU or OpenCL processing depending which list contains less remaining work to do. Or can be manually assigned with 'TIRSearchQueueWork.SearchMode = IR_SEARCH_MODE_CPU' or 'IR_SEARCH_MODE_OPENCL'. To let it have automatically distributed use 'IR_SEARCH_MODE_ANY'.

When creating a search queue, 1 thread per OpenCL device (if OpenCL processing is requested) and the set number of CPU threads ('TIRSearchQueueParameters.CPUThreads') is created for CPU processing, if set to 0 then all available CPU cores count threads will be created.

If the processing parameter for a work 'TIRProcessParameters.MultiThreadedProcessing' is set to 'True' that will spawn additional threads, normally it should be set to 'False' when using the search queue, as additional threads will just slow things down. One reason to use multi-threading per work is when processing eg. real-time and a result is quickly needed but the queue is not over used. But for real-time processing probably the search queue is not needed at all it's meant for batch processing. Also per work multi threading is only quicker when the search pictures are larger, with small pictures multi-threading off maight be faster - balance between thread creation overhead and the actual processing time.

When adding work to the queue use the 'WorkID' variable to store a custom class for example that identifies the work. This 'WorkID' object should be freed in the callback or when a result message arrives.

The results will arrive in the callback or as messages if the HWND 'TIRSearchQueueParameters.SearchQueueMatchMessageHandle' is set. If setting the HWND also set the message ID ('TIRSearchQueueParameters.SearchQueueMatchMessageID') that will be sent as the message ID. The callback is always called in a thread context (no UI access permited in the callback), the message mode can be used to receive the results in the main thread (UI access ok). When a result message arrives the 'wParam' contains a pointer to a 'TIRSearchQueueResult' (so it is a 'PIRSearchQueueResult'). This 'PIRSearchQueueResult' needs to be freed with 'ImageRecognition_FreeQueueResult()' when done with it. The callback on the other side, must not free any object (they are automatically freed after the callback returns).

No completion notification is implemented, use a variable and increment it on every 'ImageRecognition_AddWork()' and decrement it on every result callback/message arrival. Also use a flag to know if work is still in progress, as the completion can drop to 0 mid-processing.

Calling ImageRecognition_AbortSearchQueue() clears the queue but does not abort currently running searches. After calling this function the results callback and message may arrive that should be discarded if not needed.

Please see the tutorial 'Tutorial OpenCL Relative Alpha Queue' for a demo on how to use the search queue.

Hint: If the processing is hogging the system set the number of threads to CPU count - 1, so leave 1 CPU core for other apps, and/or set the threads' priority to a lower value.

The load queue works the same way as the search queue just the parameters are different.


Free Image Library

Free Image Library is a free solution for loading and saving of many different image formats. FreeImage.dll is used for many picture formats support automatically and the pre-processing (resampling) option.

http://freeimage.sourceforge.net/

FreeImage.dll is always needed on the search path.


Bug reports, Suggestions, Comments, Enquiries, etc...

If you have any of the aforementioned please email: 3delite@3delite.hu


[Top]