Image Comparison Overview
4.1 Image Comparison Overview
Image comparison methods are algorithms and/or technologies which analyze the image of the connected desktop. They are used in scripts to verify the desktop contents, retrieve artefacts such as GUI components or text and act upon the results. Most methods work with one or more image files ("template images") and/or image folders ("template image collections"). These artefacts are described closer in the Image Collections and Image Meta Data chapters.
Image comparison method plugins are closely integrated with the three following scripting language commands and their Java method counterparts. These are in the comparison method context usually called hosting commands or Java methods:
Command | Java Method(s) | Description |
|---|---|---|
Apply the selected image comparison method to the currently connected desktop once. Typically used to verify the existence of a component or to get its coordinates, to retrieve text or to verify whether the screen content is expected. | ||
Save a screenshot of the remote desktop to a file and optionally apply the selected image comparison method through an internal call of the Compareto command. | ||
Pause the execution until ('match') or while ('mismatch') the selected image comparison method produces the result of "success" (the return code of 0). Typically used to wait until the expected component or text appears on the screen or disappears from the screen. |
Each comparison method is identified by its unique name (also referred to as code), for example, "search2" or "object". Besides the standard "passrate" and "cmparea" parameters supported by the command framework, each method may declare any number of optional parameters specific for the particular algorithm. These parameters are then visible to the calling command.
As all image comparison methods are internally implemented as plugins, users are free to develop their custom algorithms and integrate them into the scripting language and the Java script API. See the ImageComparisonModule interface for details.
The following examples demonstrate the call of the most frequently used "search2" algorithm with all the framework provided parameters of "passrate" and "cmparea" and its own specific parameter of "order":
Compareto
"buttonOk.png" passrate="70" method="search2" cmparea="x:258,y:114,w:417,h:298" sort="none"
Screenshot "s.jpg" template="buttonOk.png" passrate="70" method="search2" cmparea="x:258,y:114,w:417,h:298" sort="none"
Waitfor "match" template="buttonOk.png" passrate="70" method="search2" cmparea="x:258,y:114,w:417,h:298" sort="none"
The same example in the form of a Java Script:
compareTo(new File[] { new File( "buttonOk.png" ) }, 70.0f, new Rectangle(258, 114, 417, 298), "none" ); screenshot(new File( "s.jpg" ), (String) null , (Rectangle) null , new File[] { new File( "buttonOk.png" ) }, 70.0f, new Rectangle(258, 114, 417, 298), "none" , false); waitForMatch(new File[] { new File( "buttonOk.png" ) }, 70.0f, (String) null , new Rectangle(258, 114, 417, 298), (String) null , "none" , (String) null);
There are two built-in mechanisms allowing to handle failed image comparisons in a general way:
- The ComparisonFailureFallback fall back procedure (since v2.3),
- The Image Doctor wizard and the Imagedoctor command (since v3.5).