L_CorrelationListBitmap

#include "l_bitmap.h"

L_LTIMGCOR_API L_INT L_CorrelationListBitmap(pBitmap, hCorList, pPoints, puListIndex, uMaxPoints, puNumOfPoints, uXStep, uYStep, uThreshold, uFlags)

pBITMAPHANDLE pBitmap;	/* pointer to the bitmap handle */
HBITMAPLIST hCorList;	/* correlation list handle */
POINT *pPoints;	/* pointer to an array of points */
L_UINT *puListIndex;	/* pointer to index array */
L_UINT uMaxPoints;	/* array size */
L_UINT *puNumOfPoints;	/* pointer to the array size */
L_UINT uXStep;	/* size of the X step */
L_UINT uYStep;	/* size of the Y step */
L_UINT uThreshold;	/* threshold */
L_UINT32 uFlags;	/* flags */

Compares the images in hCorList with all the areas of the same dimensions in pBitmap and finds those portions that match according to the measure of correlation.

Parameter	Description
pBitmap	Pointer to the bitmap handle referencing the bitmap to be searched.
hCorList	Bitmap list handle that contains the images for which to search. All the images in the list should have the same dimensions.
pPoints	Pointer to an array of points. This array will be filled with the starting points for the correlated areas.
puListIndex	Pointer to an array of unsigned integers. This array will be filled with the indices of the images that match correlated areas.
uMaxPoints	Size of the point array. This is also equal to the maximum number of regions in pBitmap that can be found to be correlated.
puNumOfPoints	Pointer to a variable to be updated with the number of areas in pBitmap that correlate to an image in pCorBitmap. Its maximum value is uMaxPoints.
uXStep	Step size in the X direction (along image width), in pixels. For best results, use 1.
uYStep	Step size in the Y direction (along image height), in pixels. For best results, use 1.
uThreshold	Value that indicates the correlation threshold, which is a measure of the association necessary for two areas to be considered to be correlated. If the correlation value between an image in hCorList and an area in pBitmap is less than the correlation threshold they are uncorrelated. Valid values range from 0 (zero resemblance) to 100 (perfect resemblance).
uFlags	Reserved for future use. Must be 0.

Returns

SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

Comments

This function does not support signed data images. It returns the error code ERROR_SIGNED_DATA_NOT_SUPPORTED if a signed data image is passed to this function.

This function compares the images in hCorList with all the areas of the same dimensions in pBitmap and finds those areas that match according to the measure of correlation. All the images in hCorList must have the same dimensions. Correlation is a measure of the association (resemblance) between two images. It varies from 0 (zero resemblance) to 100 (perfect resemblance). This function updates the pPoints parameter with the point of origin for those areas of pBitmap where the resemblance with an image in hCorList is greater than the value of uThreshold and also updates puListIndex with the index of that image. The dimensions of the hCorList images must be less than or equal to the pBitmap dimensions.

For example:

1. Select bitmaps of the objects for which you want to look. Put them in hCorList.

For example:

$image\letterA.gif$

$image\letterD.gif$

2. Select a bitmap that contains the objects for which you are searching and put it in pBitmap.

For example:

$image\SampleTextSearch.gif$

3. Call the L_CorrelationListBitmap function.

4. The function will update the pPoints array parameter with the point of origin (top-left) for each area of the bitmap pBitmap where the correlation with the image in hCorList is greater than the correlation threshold. The height and width of the rectangles are the same as for hCorList image.

5. The result is:

$image\SampleResults.gif$

To look for one object in a bitmap, use the L_CorrelationBitmap function.

To update a status bar or detect a user interrupt during execution of this function, refer to L_SetStatusCallback.

This function supports 12 and 16-bit grayscale and 48 and 64-bit color images. Support for 12 and 16-bit grayscale and 48 and 64-bit color images is available in the Document and Medical Imaging toolkits.

If the bitmap has a region, this function works only on the region. If the bitmap does not have a region, this function works on the entire bitmap.

This function does not support 32-bit grayscale images. It returns the error code ERROR_GRAY32_UNSUPPORTED if a 32-bit grayscale image is passed to this function.

Required DLLs and Libraries

LTIMGEFX

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Win32, x64.

See Also

Functions:	L_IntensityDetectBitmap, L_SpatialFilterBitmap, L_BinaryFilterBitmap, L_MaxFilterBitmap, L_MinFilterBitmap, L_CorrelationBitmap
Topics:	Processing an Image
	Raster Image Functions: Comparing Images
	Raster Image Functions: Processing an Image

Example

The following example loads a bitmap, and applies the correlation list filter:

#if defined (LEADTOOLS_V16_OR_LATER)
 L_INT CorrelationListBitmapExample(L_VOID)
{
   L_INT nRet;
   BITMAPHANDLE LeadBitmap;
   BITMAPHANDLE TmpBitmap;
   HBITMAPLIST hCorList;
   POINT    pPoints[10] = {0};
   L_UINT puListIndex [10] = {0};
   L_UINT  uNumOfPoints;
   /* Load the bitmap, keeping the bits per pixel of the file */
   nRet = L_LoadBitmap(MAKE_IMAGE_PATH(TEXT("IMAGE1.CMP")), &LeadBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR, NULL, NULL);
   if(nRet !=SUCCESS)
      return nRet;
   nRet = L_LoadBitmap (MAKE_IMAGE_PATH(TEXT("IMAGE2.CMP")), &TmpBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR, NULL, NULL);
   if(nRet !=SUCCESS)
      return nRet;
   nRet = L_CreateBitmapList(&hCorList); 
   if(nRet !=SUCCESS)
      return nRet;
   nRet = L_InsertBitmapListItem(hCorList, (L_UINT)-1, &TmpBitmap);
   if(nRet !=SUCCESS)
      return nRet;
   /*Apply the correlation filter*/
   nRet = L_CorrelationListBitmap(&LeadBitmap, hCorList, pPoints, puListIndex, 10, &uNumOfPoints, 1, 2, 90, 0);
   if(nRet !=SUCCESS)
      return nRet;
   nRet = L_DestroyBitmapList(hCorList);
   if(nRet !=SUCCESS)
      return nRet;
   nRet = L_SaveBitmap(MAKE_IMAGE_PATH(TEXT("Result.BMP")), &LeadBitmap, FILE_BMP, 24, 0, NULL);
   if(nRet !=SUCCESS)
      return nRet;
   //free bitmap 
   if(LeadBitmap.Flags.Allocated)  
      L_FreeBitmap(&LeadBitmap);  
   return SUCCESS;
}
#else
 L_INT CorrelationListBitmapExample(L_VOID)
{
   L_INT nRet;
   BITMAPHANDLE LeadBitmap;
   BITMAPHANDLE TmpBitmap;
   HBITMAPLIST hCorList;
   POINT    pPoints[10] = {0};
   L_UINT puListIndex [10] = {0};
   L_UINT  uNumOfPoints;
   /* Load the bitmap, keeping the bits per pixel of the file */
   nRet = L_LoadBitmap(MAKE_IMAGE_PATH(TEXT("IMAGE1.CMP")), &LeadBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR, NULL, NULL);
   if(nRet !=SUCCESS)
      return nRet;
   nRet = L_LoadBitmap (MAKE_IMAGE_PATH(TEXT("IMAGE2.CMP")), &TmpBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR, NULL, NULL);
   if(nRet !=SUCCESS)
      return nRet;
   nRet = L_CreateBitmapList(&hCorList); 
   if(nRet !=SUCCESS)
      return nRet;
   nRet = L_InsertBitmapListItem(hCorList, (L_UINT)-1, &TmpBitmap);
   if(nRet !=SUCCESS)
      return nRet;
   /*Apply the correlation filter*/
   nRet = L_CorrelationListBitmap(&LeadBitmap, hCorList, pPoints, puListIndex, 10, &uNumOfPoints, 1, 2, 90);
   if(nRet !=SUCCESS)
      return nRet;
   nRet = L_DestroyBitmapList(hCorList);
   if(nRet !=SUCCESS)
      return nRet;
   nRet = L_SaveBitmap(MAKE_IMAGE_PATH(TEXT("Result.BMP")), &LeadBitmap, FILE_BMP, 24, 0, NULL);
   if(nRet !=SUCCESS)
      return nRet;
   //free bitmap 
   if(LeadBitmap.Flags.Allocated)  
      L_FreeBitmap(&LeadBitmap);  
   return SUCCESS;
}
#endif // LEADTOOLS_V16_OR_LATER