Find Method

Applies to TestComplete 15.10, last modified on December 15, 2021

Description

The Picture.Find method searches pixel by pixel for one image specified by the Picture parameter within another represented by the given Picture object and returns the rectangular area that corresponds to the found image.

This method uses the TestComplete image comparison engine. To learn more about it, read the How Image Comparison Works topic.

Declaration

PictureObj.Find(Picture, Left, Top, Transparent, PixelTolerance, Mouse, ColorTolerance, Mask)

PictureObj An expression, variable or parameter that specifies a reference to a Picture object
Picture [in]    Required    A Picture object or an object that has the Picture method which returns a Picture object    
Left [in]    Optional    Integer Default value: 0   
Top [in]    Optional    Integer Default value: 0   
Transparent [in]    Optional    Boolean Default value: False   
PixelTolerance [in]    Optional    Integer Default value: 0   
Mouse [in]    Optional    Boolean Default value: True   
ColorTolerance [in]    Optional    Integer Default value: 0   
Mask [in]    Optional    A Picture object    
Result A Rect object

Applies To

The method is applied to the following object:

Picture

Parameters

The method has the following parameters:

Picture

The Picture object representing the image that will be searched for in the PictureObj image. Alternatively, this can be an object that has the Picture method which returns the desired Picture object.

Left

The horizontal coordinate of the given image’s pixel that serves as the top-level corner of the imaginary rectangle within that image. The method will search for the Picture picture inside this rectangle. This allows you to restrict the search area. 0 is the default value; it means that this imaginary rectangle starts from the left side of the given image.

Top

The vertical coordinate of the given image’s pixel that serves as the top-level corner of the imaginary rectangle within that image. The method will search for the Picture picture inside this rectangle. This allows you to restrict the search area. 0 is the default value; it means that this imaginary rectangle starts from the top side of the given image.

Transparent

False by default. If it is True, the top left pixel of Picture will be treated as the “transparent” (background) color in the given image, which is meaningless for comparison. For instance, if that pixel is gray, any gray pixel in Picture will match any color pixel in the given image.

PixelTolerance

Lets you ignore insignificant differences between the bitmaps during the search. If the number of different pixels is less than or equal to PixelTolerance, TestComplete considers the images to be identical. 0 is the default value; it means that no differences between the bitmaps are ignored, except for those set by the Transparent parameter.

Note: Using the PixelTolerance parameter with non-zero values may slow down the search process.

Mouse

This parameter is only meaningful if --

  • The Picture parameter specifies an object that has the Picture method that returns a Picture object.

-- and --

  • PictureObj corresponds to an image that has a mouse pointer on it.

If the Mouse parameter is True, the Find method includes the mouse pointer in the Picture image. The method will return True only if PictureObj also contains the mouse pointer image in the same position.

ColorTolerance

Allows ignoring hue differences when comparing bitmaps. The parameter specifies an acceptable color difference under which two pixels of a certain color should be treated as identical. The color difference is represented as an integer value within the range 0…255 that specifies an acceptable difference for each color component (red, green and blue) of the compared pixels. Two pixels are considered identical if the difference between intensities of each of their color components does not exceed the specified value.

When ColorTolerance is 0, which is the default value, compared pixels are considered identical only if they have exactly the same color. When ColorTolerance is 255, pixels of any color are considered identical.

Mask

Specifies which areas of bitmaps should be compared. A mask is another Picture object, whose pixels can be either black or white. If a mask is specified, the routine works in the following way: white pixels on the mask are taken into account during the comparison, whereas black pixels are ignored.

Result Value

If the search is successful, Find returns the Rect object whose properties are set to the values fitting the sought-for image found within the given image. This is the first image found, searching left-right and top-down. If the search fails, Find returns an empty value (Nothing in VBScript, nil in DelphiScript, None in Python, null in JavaScript, JScript, C++Script and C#Script).

Remarks

If the method fails to locate an image, while the sought-for image is part of another image, see the Why Image Comparison Fails and Factors Affecting Image Comparison help topics to determine the cause of the failure.

Example

The code below demonstrates how you can search for the desired image on a web page. To search the window, we use the Picture.Find method. This method returns a rectangle that specifies the coordinates of the image within the web browser window. To calculate the coordinates of the image center, we use methods of the Rect object. To obtain the scripting object corresponding to the found image, we use the Sys.Desktop.ObjectFromPoint method. This method returns an onscreen object that contains Click and other actions, which you can use to simulate mouse clicks over the image.

JavaScript
JScript
Python
VBScript
DelphiScript
C++Script, C#Script

JavaScript

function Test()
{

  let url = "http://smartbear.com/";
  // Launches the web browser and opens the web page
  Browsers.Item(btIexplorer).Run(url);
  let page = Sys.Browser().Page("*");

  // Obtains the image of the browser window
  let picture = page.PagePicture();

  // Loads the sought-for image
  let pict = Utils.Picture;
  pict.LoadFromFile("c:\my_image.bmp");

  // Searches for the image within the browser window
  let rect = picture.Find(pict);
  if (strictEqual(rect, null))
  {
    Log.Warning("The image was not found on the page.");
    return;
  }

  // Calculates the coordinates of the image center
  let x = page.ScreenLeft + rect.Left + rect.Width / 2;
  let y = page.ScreenTop + rect.Top + rect.Height / 2;
  // Obtains the IMG object by coordinates
  let img = Sys.Desktop.ObjectFromPoint(x, y);

  // Checks the results and simulates a mouse click over the image
  if (img.Exists)
    img.Click();
  else
    Log.Warning("Unable to simulate the click.");

}

JScript

function Test()
{

  var url = "http://smartbear.com/";
  // Launches the web browser and opens the web page
  Browsers.Item(btIexplorer).Run(url);
  var page = Sys.Browser().Page("*");

  // Obtains the image of the browser window
  var picture = page.PagePicture();

  // Loads the sought-for image
  var pict = Utils.Picture;
  pict.LoadFromFile("c:\my_image.bmp");

  // Searches for the image within the browser window
  var rect = picture.Find(pict);
  if (rect == null)
  {
    Log.Warning("The image was not found on the page.");
    return;
  }

  // Calculates the coordinates of the image center
  var x = page.ScreenLeft + rect.Left + rect.Width / 2;
  var y = page.ScreenTop + rect.Top + rect.Height / 2;
  // Obtains the IMG object by coordinates
  var img = Sys.Desktop.ObjectFromPoint(x, y);

  // Checks the results and simulates a mouse click over the image
  if (img.Exists)
    img.Click();
  else
    Log.Warning("Unable to simulate the click.");

}

Python

def Test():
  url = "http://smartbear.com/"
  # Launches the web browser and opens the web page 
  Browsers.Item(btIexplorer).Run(url)
  page = Sys.Browser().Page("*")
  # Obtains the image of the browser window 
  picture = page.PagePicture()
  # Loads the sought-for image 
  pict = Utils.Picture;
  pict.LoadFromFile("c:\my_image.bmp")
  # Searches for the image within the browser window 
  rect = picture.Find(pict)
  if rect == None:
    Log.Warning("The image was not found on the page.")
    return
  # Calculates the coordinates of the image center 
  x = page.ScreenLeft + rect.Left + rect.Width / 2
  y = page.ScreenTop + rect.Top + rect.Height / 2
  # Obtains the IMG object by coordinates 
  img = Sys.Desktop.ObjectFromPoint(x, y)
  # Checks the results and simulates a mouse click over the image 
  if img.Exists:
    img.Click()
  else:
    Log.Warning("Unable to simulate the click.")

VBScript

Sub Test
  Dim url, page, picture, pict, rect, img, x, y

  url = "http://smartbear.com/"
  ' Launches the web browser and opens the web page
  Browsers.Item(btIexplorer).Run(url)
  Set page = Sys.Browser.Page("*")

  ' Obtains the image of the browser window
  Set picture = page.PagePicture

  ' Loads the sought-for image
  Set pict = Utils.Picture
  pict.LoadFromFile("c:\my_image.bmp")

  ' Searches for the image within the browser window
  Set rect = picture.Find(pict)
  If rect Is Nothing Then
    Call Log.Warning("The image was not found on the page.")
    Exit Sub
  End If

  ' Calculates the coordinates of the image center
  x = page.ScreenLeft + rect.Left + rect.Width / 2
  y = page.ScreenTop + rect.Top + rect.Height / 2
  ' Obtains the IMG object by coordinates
  Set img = Sys.Desktop.ObjectFromPoint(x, y)

  ' Checks the results and simulates a mouse click over the image
  If img.Exists Then
    img.Click
  Else
    Call Log.Warning("Unable to simulate the click.")
  End If

End Sub

DelphiScript

procedure Test;
var
url, page, picture, pict, rect, img, x, y : OleVariant;
begin
  url := 'http://smartbear.com/';
  // Launches the web browser and opens the web page
  Browsers.Item(btIexplorer).Run(url);
  page := Sys.Browser.Page('*');

  // Obtains the image of the browser window
  picture := page.PagePicture;

  // Loads the sought-for image
  pict := Utils.Picture;
  pict.LoadFromFile('c:\my_image.bmp');

  // Searches for the image within the browser window
  rect := picture.Find(pict);
  if rect = nil then
  begin
    Log.Warning('The image was not found on the page.');
    Exit;
  end;

  // Calculates the coordinates of the image center
  x := page.ScreenLeft + Rect.Left + Rect.Width / 2;
  y := page.ScreenTop + Rect.Top + Rect.Height / 2;
  // Obtains the IMG object by coordinates
  img := Sys.Desktop.ObjectFromPoint(x, y);

  // Checks the results and simulates a mouse click over the image
  if (img.Exists) then
    img.Click
  else
    Log.Warning('Unable to simulate the click.');

end;

C++Script, C#Script

function Test()
{
  var url = "http://smartbear.com/";
  // Launches the web browser and opens the web page
  Browsers["Item"](btIexplorer)["Run"](url);
  var page = Sys["Browser"]()["Page"]("*");

  // Obtains the image of the browser window
  var picture = page["PagePicture"]();

  // Loads the sought-for image
  var pict = Utils["Picture"];
  pict["LoadFromFile"]("c:\my_image.bmp");

  // Searches for the image within the browser window
  var rect = picture["Find"](pict);
  if (rect == null)
  {
    Log["Warning"]("The image was not found on the page.");
    return;
  }

  // Calculates the coordinates of the image center
  var x = page["ScreenLeft"] + rect["Left"] + rect["Width"] / 2;
  var y = page["ScreenTop"] + rect["Top"] + rect["Height"] / 2;
  // Obtains the IMG object by coordinates
  var img = Sys["Desktop"]["ObjectFromPoint"](x, y);

  // Checks the results and simulates a mouse click over the image
  if (img["Exists"])
    img["Click"]();
  else
    Log["Warning"]("Unable to simulate the click.");

}

See Also

About Region Checkpoints
How Image Comparison Works
Finding an Image Within Another Image
Find Method
FindRegion Method
Compare Method
Difference Method
Pixels Property

Highlight search results