Histogram Based Comparison ("default")

4.4.1 Histogram Based Comparison ("default")


The Histogram Based Comparison Method (code "default") was historically the first method provided by T-Plan Robot in 2005. It was designed for a quick check of the desktop screen against one or more full-screen template image(s). Though it has been obsoleted by better verification means such as the "search2" and "search" methods it may be still used in special cases.

The method is based on a simple histogram comparison. An image histogram is in simple words a list of colours located in the image together with the number of pixels of each colour. The method first calculates histograms both of the remote desktop and template images and compares them. Result of the image comparison is then calculated as the number of matching pixels divided by the total number of image pixels.

The following example illustrates how the method works. Let us have two simple 120x100 images (12000 pixels each):

Image 1

Image 2


Image 1

Image 2

Matching Pixels
Sum of matching pixels:9000px

The comparison result is in this case 9000px/12000px, which is 0.75, or better 75%. This corresponds to what a human would say when comparing the images visually - they are different just in one quarter.

Though this is a very primitive algorithm it is sufficient where you need to verify whether the desktop displays correct application provided that the application and desktop background colours differ. The algorithm is also quite robust in terms of window location changes which don't affect the full-screen colour histogram.

Be aware that the default method is designed to compare two images of the same size. If your template image has a different size than the remote desktop, both images will be internally cropped to the size of their intersection. As this may lead to unpredictable results it is not recommended to use the default method together with a custom comparison area (the "cmparea" parameter).


The method requires one or more template images and/or image collections specified through the hosting command or Java method call. The parameter of "passrate" defines in the context of the "default" method the lowest acceptable result of the comparison of the template image and the screen histograms (see the example in the method description). It defaults to 95%. The "cmparea" is optional and defaults to the full screen when omitted.

No other method-specific parameters are supported.


The method makes the calling command (method call) return 0 (success) if the produced comparison result is greater than or equal to the specified pass rate. Otherwise, it returns the value of 1.


As the "default" method does not use any method-specific parameters, the only means of dealing with a failing histogram comparison is decreasing of the "passrate" parameter. To see the actual comparison result after a histogram comparison looks for the _COMPARE_RESULT variable in the variable viewer.

The general Image Comparison Recommendations consider the following reliability factors:

  • Remove all icons and items from the server desktop and make it as simple as possible. Note that most desktops also display a clock/date which introduces differences with the time & date updates. If such an object participates in the area you are comparing to, use the pass rate to increase the tolerance to mismatching pixels.
  • Check if the application window(s) you are testing have a stable size and open in a stable location. Variable window size and location significantly affects comparison results. It is a good idea to maximize the application window through a scripted key sequence (such as Alt+Space followed by X on Windows or Alt+F10 on Linux/Gnome) before comparison.


Compareto netscape1.png;netscape1.png  method="default" passrate="90"

if ({_EXIT_CODE} > 0) {
  Exit 1

- Compare the desktop screen to the netscape1.png and netscape1.png images with the pass rate of 90% and terminate the script with the exit code of 1 if neither of them matches the screen.