Compareto Command

3.2.4 Compareto

Compareto - The Compareto command is intended to perform a one-time comparison of the current remote desktop image and a single image or an image collection using the specified image comparison method. An optional action may be executed based on the result either in the "onfail" and "onpass" parameters or through testing of the command exit code using an if/else structure. T-Plan Robot Enterprise 4.4.2Beta contains six image comparison methods which are in details described in the Image Comparison Capabilities chapter:

1. Image Search v2 ("search2", since v3.0) is the successor of the "search" method and performs a tolerant search of the desktop screen for the object represented by the template image(s).
2. Image search ("search", since v2.0) performs a tolerant search of the desktop screen for the object represented by the template image(s).
3. Object search ("object", since v2.2) searches objects on the screen by a single RGB colour or a range of similar colours.
4. Text OCR ("tocr", since 2.2) performs optical character recognition (OCR) on the desktop image using the OCR engine of choice.
5. Image-Based Text Recognition ("text", since 3.0) extracts text from the screen using a collection of pre-saved character images.
6. Histogram based comparison (code "default", since v2.0) is the legacy algorithm comparing histograms of the desktop image and the specified template image(s).

Besides the method-specific variables the command populates a set of COMPARETO prefixed variables as follows:

The command further supports one input variable which if defined controls the order of processing of the images loaded from image collections:

To make image comparison more reliable consider the factors listed in the Image Comparison Recommendations chapter. For information on how to set up a central point of failure for image comparisons see the ComparisonFailureFallback fallback procedure.

To display comparison result in the HTML report generated by the Report command use Screenshot. If you want to wait until the screen matches your template image, use 'Waitfor match'. Both Screenshot and 'Waitfor match' commands use the methods of the Compareto command internally and support the same parameters.

SYNOPSIS

compareto <image_collection> [passrate=<pass_rate_in_%>] [onpass=<command>] [onfail=<command>] [method=<comparison_method>] [methodparams=<custom_params>] [cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]]  [<method_specific_params>]
* Red colour indicates obligatory parameters

OPTIONS

image_collection

- An image collection - one or more image file names or folders with images separated by a semicolon (';') to be compared to the remote desktop image. On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. File names can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use a relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. Supported image formats are subject to the Java version. Java 1.6 supports at least PNG, JPG, GIF and BMP.

Template images will be compared with the remote desktop image in the specified list order. If a template comparison produces a positive result (either match or mismatch depending on the specified event), the condition is considered to be met and the command finishes with an exit code of 0 and skips any remaining templates in the list. Predefined variable _COMPARETO_TEMPLATE_INDEX may be then used to determine the index of the matching template image. See image comparison specific variables for a complete list of supported variables.

passrate=<pass_rate_in_%>

- The pass rate for image comparison. It must be a number between 0 and 100 which may optionally be followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted, the default pass rate defined by the method or in the Robot preferences will be used (default values are 95% for the "default" and 100% for the "search" and "search2" methods).

onpass=<command>

- A command to be executed when the comparison succeeds (the selected method reports success). It must be a single command. To call a sequence of commands to use either a procedure or a  subsequent if/else construction testing the command exit code.

onfail=<command>

- A command to be executed when the comparison fails (the selected method reports failure). It must be one single command. If you need to define a sequence of command to be executed, use a procedure.

method=<comparison_method>

- The method (algorithm) to be used for image comparison. It must be one of the supported method names (codes) described in the Image Comparison Capabilities chapter or the name of a third party method enabled through the plugin interface. If omitted the command will use the default one.

methodparams=<custom_params>

 - Custom parameters to be passed to the image comparison algorithm. As the T-Plan Robot 2.0 default image comparison algorithms don't support any custom parameters, you don't need to specify this parameter unless you write your own algorithm.

cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]

- The rectangular area of the desktop to limit the comparison to. If you omit this parameter the whole remote desktop will be processed. The area coordinates have format of 'x:,y:,w:,h:', where each coordinate can be specified in pixels (for example. "x:225") or as a percentage ("x:23%"). If any of x, y, width or height are omitted, T-Plan Robot will use the full-screen values to determine the missing parameters (x:0, y:0, w:, h:).

method_specific_params

- See the documentation of individual comparison methods for the list of supported method-specific parameters.

RETURNS

The command returns 0 (zero) when the comparison passes, 1 when it fails and 2 when the template image is not found or cannot be read.

EXAMPLES

Compareto netscape.png passrate=95% onfail="exit 1"

- Compare the image of the current remote desktop to image netscape.png using the "default" image comparison method. If there is not at least 95% match, terminate the script execution using the Exit command and return exit code 1.

Compareto button1.png;button2.png method=search
if ({_EXIT_CODE} == 0) {
  Mouse click to="x:{_SEARCH_X}+5,y:{_SEARCH_Y}+5"
}


- Search the remote desktop image for a button matching either button1.png or button2.png. If it is found, click on it. The command adds 5 pixels to the x and y coordinates to make sure you click in the middle of the button.

Compareto "search.png" method="search"
for (i=1; {i}<{_SEARCH_MATCH_COUNT}+1; i={i}+1) {
  # Nested variables compose the variable names of a suffix and an index
  Mouse click to=x:{_SEARCH_X_{i}},y:{_SEARCH_Y_{i}}
}

- Search the remote desktop image for an icon represented by the template image search.png and click onto each of the occurrences.

Var _TOCR_LINE_COUNT=0
Compareto method="tocr" cmparea="x:33,y:2,w:200,h:22"
for (i=1; {i}<{_TOCR_LINE_COUNT}+1; i={i}+1) {
   Typeline "{_TOCR_LINE{i}}"
}

- Extracts text from the specified desktop area using OCR and types it onto the desktop.

Compareto method="tocr" cmparea="x:33,y:2,w:200,h:22" pattern="[aA]pplication.*"
if ({_EXIT_CODE} > 0) {
  Exit 1
}


- Use regular expression to exit the script when the text recognized through Tesseract OCR doesn't start either with the 'Application' or 'application' word.

Compareto method="object" color="FF0000" draw="true"

- Find all solid colour red objects (RGB = (256, 0, 0)) on the screen and highlight them in the GUI.


Compareto circle.png method="object" color="00FF00" tolerance="100" passrate="80%" draw="true" rotations="30"

- Find all green-like objects which are at least 80% similar to the one in the circle.png image and highlight them in the GUI. The tolerance parameter defines the size of the palette of acceptable green colours. As the rotations parameter is set to 30, the algorithm will search the screen for objects rotated in 12-degree steps (360 degrees / 30).