Description

The Picture.Difference method compares two images pixel by pixel (the first image is represented by the given Picture object, the second one is specified by the Picture parameter) and returns an image indicating differences between the bitmaps under comparison. This resulting image is also represented by a Picture object.

To learn more about image comparison, read the How Image Comparison Works topic.

Declaration

PictureObj.Difference(Picture, 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
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 `Picture` object

Applies To

The method is applied to the following object:

Picture

Parameters

The method has the following parameters:

Picture

The Picture object that represents the image to be compared with the given image. Alternatively, this can be an object that has the Picture method which returns the desired Picture object.

Transparent

False by default. If it is True, the top left pixel of the given image will be treated as the “transparent” (background) color in this image. Therefore, any transparent pixels in the first image will be excluded when compared to the second image. All pixels with this color are excluded from comparison.

PixelTolerance

Lets you ignore slight 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 except for those set by the Transparent parameter are ignored.

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.

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 compared images are identical, the Difference method returns an empty value (Nothing in VBScript, null in JavaScript, JScript, C++Script and C#Script, None in Python and nil in DelphiScript). If the images differ, the method returns a picture (represented by the Picture object) that shows the difference between the images. The following color highlighting scheme is used:

Identical pixels are filled with white.
The pixels that differ from one image to another are highlighted with red.
The excess areas (when the images' height or width is different) are highlighted with fuchsia.
Dissimilar pixels that were skipped due to the PixelTolerance parameter are highlighted with blue.
The pixels that were skipped due to the Transparent or Mask parameter are filled with gray.
The pixels that were ignored due to the ColorTolerance parameter are highlighted with yellow.

Remarks

To learn why the method reports that the images are different while they seem to be identical (and on the contrary, why the method reports the images are identical while they are different), see Factors Affecting Image Comparison and Why Image Comparison Fails.

Example

The following code compares two images, which are represented by the Picture objects.

JavaScript

function Test1()
{
  Pict1 = Utils.Picture;
  Pict2 = Utils.Picture;

  Pict1.LoadFromFile("D:\\Data\\img1.png");
  Pict2.LoadFromFile("D:\\Data\\img2.png");

  // Comparing the images using the Compare method
  if (!Pict1.Compare(Pict2))
  {
    Log.Picture(Pict1);
    Log.Picture(Pict2);
    Log.Error("The compared images are not identical");
  }

  /* Comparing the images using the Difference method
  ResultImage = Pict1.Difference(Pict2);
  if (strictEqual(ResultImage, null))
    Log.Message("The images are identical");
  else
    Log.Picture(ResultImage);*/
}

JScript

function Test1()
{
  Pict1 = Utils.Picture;
  Pict2 = Utils.Picture;

  Pict1.LoadFromFile("D:\\Data\\img1.png");
  Pict2.LoadFromFile("D:\\Data\\img2.png");

  // Comparing the images using the Compare method
  if (!Pict1.Compare(Pict2))
  {
    Log.Picture(Pict1);
    Log.Picture(Pict2);
    Log.Error("The compared images are not identical");
  }

  /* Comparing the images using the Difference method
  ResultImage = Pict1.Difference(Pict2);
  if (ResultImage == null)
    Log.Message("The images are identical");
  else
    Log.Picture(ResultImage);*/
}

Python

def Test1():
  Pict1 = Utils.Picture
  Pict2 = Utils.Picture
  Pict1.LoadFromFile("D:\\Data\\img1.png")
  Pict2.LoadFromFile("D:\\Data\\img2.png")
  # Comparing the images using the Compare method
  if not Pict1.Compare(Pict2):
    Log.Picture(Pict1)
    Log.Picture(Pict2)
    Log.Error("The compared images are not identical")
  # Comparing the images using the Difference method
  # ResultImage = Pict1.Difference(Pict2)
  # if ResultImage == None:
    # Log.Message("The images are identical")
  # else:
    # Log.Picture(ResultImage)

VBScript

Sub Test1
  Set Pict1 = Utils.Picture
  Set Pict2 = Utils.Picture

  Pict1.LoadFromFile("D:\Data\img1.png")
  Pict2.LoadFromFile("D:\Data\img2.png")

  ' Comparing the images using the Compare method
  If Not Pict1.Compare(Pict2) Then
    Log.Picture(Pict1)
    Log.Picture(Pict2)
    Log.Error "The compared images are not identical"
  End If

  ' Comparing the images using the Difference method
   ' Set ResultImage = Pict1.Difference(Pict2)
  ' If ResultImage Is Nothing Then
    ' Log.Message("The images are identical")
  ' Else
    ' Log.Picture(ResultImage)
  ' End If
End Sub

DelphiScript

procedure Test1;
begin
  Pict1 := Utils.Picture;
  Pict2 := Utils.Picture;

  Pict1.LoadFromFile('D:\\Data\\img1.png');
  Pict2.LoadFromFile('D:\\Data\\img2.png');

  // Comparing the images using the Compare method
  if not Pict1.Compare(Pict2) then
  begin
    Log.Picture(Pict1);
    Log.Picture(Pict2);
    Log.Error('The compared images are not identical');
  end;

  { Comparing the images using the Difference method
  ResultImage := Pict1.Difference(Pict2);
  if ResultImage = nil then
    Log.Message('The images are identical')
  else
    Log.Picture(ResultImage);}
end;

C++Script, C#Script

function Test1()
{
  Pict1 = Utils["Picture"];
  Pict2 = Utils["Picture"];

  Pict1["LoadFromFile"]("D:\\Data\\img1.png");
  Pict2["LoadFromFile"]("D:\\Data\\img2.png");

  // Comparing the images using the Compare method
  if (!Pict1["Compare"](Pict2))
  {
    Log["Picture"](Pict1);
    Log["Picture"](Pict2);
    Log["Error"]("The compared images are not identical");
  }

  /* Comparing the images using the Difference method
  ResultImage = Pict1["Difference"](Pict2);
  if (ResultImage == null)
    Log["Message"]("The images are identical");
  else
    Log["Picture"](ResultImage);*/
}

Difference Method

Description

Declaration

Applies To

Parameters

Result Value

Remarks

Example

See Also