LocateBitmap Method
The LocateBitmap method searches within the bitmap for a specified bitmap image. If the match parameter is true, the method determines whether the two bitmap objects contain identical images.
You can specify the region of the bitmap to be searched, and the direction of search (left to right, right to left, top to bottom, bottom to top).
Images with transparent areas can be located; this enables irregularly shaped images within the host bitmap to be found.
You can search for unlike images; this is useful when locating for example the "real" image on a transparent, plain, or tiled background, or the inside limit of a border or margin.
You can search for multiple instances of the image; results of this search are stored in a long byte object, which you provide as the locations parameter. To access the contents of this long byte object, call the method again, passing the previously populated locations parameter together with a locationsindex: the x and y parameters will be set to the coordinates at that index point.
The two bitmaps should have the same format: if they do not, correct matching is still likely, but this is not guaranteed, even if the displayed images appear identical.
This method has the following syntax:
integer = BitmapObject.LocateBitmap(bitmap = BitmapObject
[, xstart = integer][, ystart = integer][, searchwidth = integer]
[, searchheight = integer][, searchdirection = integer]
[, clearcolor = integer][, match = integer][, unlike = integer]
[, locations = LongByteObject], x = Byref(integer), y = Byref(integer))
When returning the location of one of multiple instances of the image (captured into the locations LongByteObject by a previous call to LocateBitmap):
integer = BitmapObject.LocateBitmap(bitmap = BitmapObject,
locations = LongByteObject, locationsindex = integer,
x = Byref(integer), y = Byref(integer))
When checking for an exact match (match parameter set to TRUE):
integer = BitmapObject.LocateBitmap(bitmap = BitmapObject,
match = integer)
This method has the following parameters:
bitmap
(Required) Specifies the bitmap image being searched for.
xstart
(Optional) Specifies the x-location to begin the search at, in pixels.
Default: 1
ystart
(Optional) Specifies the y-location to begin the search at, in pixels.
Default: 1
searchwidth
(Optional) Specifies the horizontal distance to search across, in pixels.
Default: the distance from xstart to the right edge of the host image
searchheight
(Optional) Specifies the vertical distance to search across, in pixels.
Default: the distance from ystart to the bottom edge of the host image
searchdirection
(Optional) Specifies the direction of search. Valid values are:
FO_HORIZONTAL
Search progresses from left to right.
-FO_HORIZONTAL
Search progresses from right to left.
FO_VERTICAL
Search progresses from top to bottom.
-FO_VERTICAL
Search progresses from bottom to top.
Default: FO_HORIZONTAL
clearcolor
(Optional) Specifies the color of those pixels in the passed bitmap that should be ignored when matching. The specified value must be an RGB value, not a CC constant.
Default: none
match
(Optional) Specifies that the search is to establish whether the two images are identical. Valid values are TRUE and FALSE.
Default: FALSE
locations
(Required, if locationsindex is specified) Specifies the set of locations at which the searched for image will be found.
If a locations LongByteObject parameter is passed, the method will not stop when the first match is found, but will continue, recording all matches as successive x,y coordinates in the LongByteObject, and the number of matches in the LongByteObject's ClientInteger.
To use this to locate a second or subsequent instance of the search image:
• First call LocateBitmap passing an empty LongByteObject to populate that LongByteObject with the coordinates of all matches found.
• Then call LocateBitmap, passing the populated LongByteObject (as the locations parameter), the index of the match you want (as the locationsindex parameter), and the x and y parameters (byref) to hold the coordinates of the match.
Default: NULL
locationsindex
(If specified, locations is also required) Specifies the index of those coordinates within the passed locations parameter, whose values x and y will be set to
Default: 0
x
(Required, unless match is specified) Specifies the x-location of the searched-for image within the bitmap.
This parameter is mandatory and must be provided byref.
y
(Required, unless match is specified) Specifies the y-location of the searched-for image within the bitmap.
This parameter is mandatory and must be provided byref.
unlike
Specifies that the search should find the first location that does not match the passed image.
This allows the "further limit" of a plain or repeating element to be found, for example, when trimming plain, tiled, or transparent borders or margins from an image.
The method returns ER_OK if successful. The bitmap object's errorstatus is also set to the return value.
Examples—LocateBitmap method:
The following code compares two bitmap objects to establish whether they contain identical images:
if (imageA.LocateBitmap(bitmap=imageB, match=TRUE)) = ER_OK then
message 'A matches B';
else
message 'A does not match B';
endif;
The following code determines where within the specified region of bitmap object imageA the image contained in bitmap object imageB can be found:
status = imageA.LocateBitmap(bitmap=imageB,xstart=24, ystart=12, searchwidth=75, searchheight=12, x=Byref(x), y=Byref(y));
if status = OK then
string.Value = 'image A contains image B at location :x,:y, ' +
'which is within the specified region :xstart,:ystart,:searchwidth,:searchheight';
message string.ExpandParms(scope=curframe.Scope).Value;
else
message 'image A does not contain image B within the specified region';
endif;
The following code determines where within bitmap object imageA the partially transparent image contained in bitmap object imageB can be found (the transparency color is white in this example).
The location returned is where the topleft of the imageB rectangle would be located in imageA, regardless of which areas of imageB are transparent:
status = imageA.LocateBitmap(bitmap=imageB, x=Byref(x), y=Byref(y),
clearcolor=RGB(red=255,green=255,blue=255));
if status = OK then
string.Value = 'image A contains image B at location :x,:y';
message string.ExpandParms(scope=curframe.Scope).Value;
else
message 'image A does not contain image B';
endif;
The following code determines where within bitmap object imageA the partially transparent image contained in bitmap object imageB can be found (the transparency color is red in this example).
The location identified is where the topleft of the non-transparent area of the imageB rectangle would be located in imageA (the calls with unlike=TRUE find the limits of the transparent areas to left and top of the search image):
status = imageA.LocateBitmap(bitmap=imageB, x=Byref(x), y=Byref(y),
clearcolor=RGB(red=255));
imageC.BlankBitmap(width=1, height=imageB.HeightPixels, color=RGB(red=255));
imageA.LocateBitmap(bitmap=imageB, x=Byref(xoff), clearcolor=RGB(red=255), unlike=TRUE);
x = x + xoff;
imageC.BlankBitmap(width=imageB.WidthPixels, height=1, color=RGB(red=255));
imageA.LocateBitmap(bitmap=imageB, y=Byref(yoff), clearcolor=RGB(red=255), unlike=TRUE);
y = y + yoff;
if status = OK then
string.Value = 'image A contains image B (solid area) at location :x,:y';
message string.ExpandParms(scope=curframe.Scope).Value;
else
message 'image A does not contain image B';
endif;
The following code determines where within bitmap object imageA the second image contained in bitmap object imageB can be found:
status = imageA.LocateBitmap(bitmap=imageB, x=Byref(x), y=Byref(y), locations=myLocations);
if myLocations.ClientInteger >= 2 then
status = imageA.LocateBitmap(bitmap=imageB, locations=myLocations, locationsindex=2);
endif;
if status = OK then
string.Value = 'image A contains a second instance of image B at location :x,:y, ';
message string.ExpandParms(scope=curframe.Scope).Value;
else
message 'image A does not contain image B within the specified region';
endif;