public interface ImageComparisonModule
This class declares methods of image comparison used by the CompareTo, Screenshot and WaitFor commands of the T-Plan Robot Enterprise scripting language. You may implement this interface to create your own image comparison algorithm and plug it into the application. The interface also allows to create a method of analysis of the desktop image.
The following example implements a dummy comparison method. It also
implements the Plugin interface so that it can be
plugged in to T-Plan Robot Enterprise through PluginManager.
import com.tplan.robot.imagecomparison.ImageComparisonModule;
import com.tplan.robot.plugin.*;
import com.tplan.robot.scripting.ScriptingContext;
import java.awt.*;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;
public class DummyComparisonModule implements ImageComparisonModule, Plugin {
// Base image. Not really used in this dummy module.
private Image baseImage;
// Name of the method. It will be used as an identificator in the scripting language.
public String getMethodName() {
return "dummy";
}
// Method description
public String getMethodDescription() {
return "This is a dummy module which doesn't perform any comparison and always returns 100% match.";
}
public float compare(Image image, Rectangle rectangle, Image image1, String methodParams, ScriptingContext repository, float passRate) {
// This is just a dummy module which always returns 1, i.e. 100% match.
// Implement your own image comparison code here.
return 1.0f;
}
// Set the base image. It is just a convenience method used for multiple comparisons against one image.
public void setBaseImage(Image img) {
baseImage = img;
}
// Compare an image with the base image
public float compareToBaseImage(Image image, Rectangle area, String methodParams, ScriptingContext repository, float passRate) {
return compare(baseImage, area, image, methodParams, repository, passRate);
}
// We are doing image comparison, not just desktop analysis
public boolean isSecondImageRequired() {
return true;
}
// No custom method params are supported
public boolean isMethodParamsSupported() {
return false;
}
// Plugin method - get plugin code (identifier).
public String getCode() {
return "dummy";
}
// Plugin method - get plugin display name.
public String getDisplayName() {
return "Dummy image comparison module";
}
// Plugin method - get detailed plugin description.
public String getDescription() {
return "This is my dummy image comparison module. It does nothing and always returns 1.";
}
// Plugin method - get name of the vendor who provides this plugin.
public String getVendorName() {
return "John Doe";
}
// Plugin method - get vendor home page URL.
public String getVendorHomePage() {
return null;
}
// Plugin method - get vendor support contact.
public String getSupportContact() {
return null;
}
// Plugin method - get plugin version. We return 1.0
public int[] getVersion() {
return new int[] { 1, 0};
}
// Plugin method - get unique name which identifies one particular plugin accross all versions and releases.
public String getUniqueId() {
return "dummy image comparison method by John Doe";
}
// Plugin method - get release date. We return January 1, 2009.
public Date getDate() {
Calendar cal = GregorianCalendar.getInstance();
cal.set(2009, 1, 1);
return cal.getTime();
}
// Plugin method - get the implemented inteface. We return ImageComparisonModule.class
public Class getImplementedInterface() {
return ImageComparisonModule.class;
}
// Plugin method - does the application have to be restarted after plugin installation?
public boolean requiresRestart() {
return false;
}
// Plugin method - get lowest supported version of this framework. We return 2.0.
public int[] getLowestSupportedVersion() {
return new int[] { 2 };
}
// Plugin method - message to be displayed before plugin installation.
public String getMessageBeforeInstall() {
return null;
}
// Plugin method - message to be displayed after plugin installation.
public String getMessageAfterInstall() {
return null;
}
// Plugin method - check dependencies (none in this case).
public void checkDependencies(PluginManager manager) throws DependencyMissingException {
}
}
NOTE: To compile this dummy module you need to place the application JAR file
to your Java class path.
Once you compile your comparison module to the Java .class format,
take advantage of the Tools->Plugin Manager dialog to
plug the new module to the application. To plug in the code from a Java program
get instance of the Plugin Manager and
add call the PluginManager.installPlugin(java.lang.String, java.lang.String, boolean, boolean)
method. Another option is to add your new module to the plugin list XML file manually.
See the Plugin Manager documentation
for details.
The configuration is now complete. You can start the tool and verify availability of your module.
If you set your module as the default one, all calls of the CompareTo, Screenshot
and WaitFor update commands will by default perform image comparisons using your module. If you didn't
modify the default method setting, you can still explicitly specify your custom method using the method
parameter. To use your dummy comparison module create commands like
CompareTo <image file> method=dummy, Screenshot <image file> method=dummy,
Waitfor match method=dummy or Waitfor mismatch method=dummy.
T-Plan Robot Enterprise, (C) 2009-2022 T-Plan Limited. All rights reserved.
| Modifier and Type | Field and Description |
|---|---|
static String |
CONTEXT_OBJECT_IMAGE_COMPARISON_FAILURE_DESC
The key the image comparison method may store the failure description
to the context.
|
static String |
SEARCH_COORD_LIST
This is a key used by the search image comparison module to save
list of coordinates to the repository table.
|
| Modifier and Type | Method and Description |
|---|---|
float |
compare(Image desktopImage,
Rectangle area,
Image image,
String methodParams,
ScriptingContext repository,
float passRate)
Compare the desktop image to another image and return a number indicating how much they match.
|
float |
compareToBaseImage(Image desktopImage,
Rectangle area,
String methodParams,
ScriptingContext repository,
float passRate)
Compare the desktop image to the base image and return a number indicating how much they match.
|
String |
getMethodDescription()
Get the method description.
|
String |
getMethodName()
Get the method name.
|
boolean |
isMethodParamsSupported()
Define whether this module supports some custom parameters which can be passed via the
methodparams
parameter of the scripting language. |
boolean |
isSecondImageRequired()
Determine whether we are comparing two images or just analyze the desktop image.
|
void |
setBaseImage(Image img)
Set the base image.
|
static final String SEARCH_COORD_LIST
static final String CONTEXT_OBJECT_IMAGE_COMPARISON_FAILURE_DESC
String getMethodName()
module of the 'CompareTo' and 'Waitfor update'
commands) and in default comparison method configuration (user config parameter
CompareToCommand.defaultComparisonModule).
Method names are not case sensitive. Be sure not to specify a name which is reserved by
the tool or already used by another method. Version 1.3 reserves two names, 'default'
and search. You can't override these names.
String getMethodDescription()
void setBaseImage(Image img)
This is just a convenience method used by the 'Waitfor match' command to perform repeated image
comparisons against one image.
The default image comparison algorithm is based on color histograms. When you call this method,
a histogram is calculated for the base image and cached for future repeated comparisons performed through the
compareToBaseImage() method calls. As calculation of a color histograms is quite a time expensive
operation, this approach allows to achieve higher performance.
See the compareToBaseImage() method doc for more info.
img - the base (component) image.float compare(Image desktopImage, Rectangle area, Image image, String methodParams, ScriptingContext repository, float passRate)
desktopImage - desktop image.area - a rectangle area of the remote desktop to be used for image comparison. If the argument is null,
the whole remote desktop image will be used.image - another image to be compared to the desktop image.methodParams - method parameters passed by the 'methodparams' parameter of
the 'CompareTo' and 'Waitfor update' commands. You can use this to pass custom
parameters from the script to this module.repository - a Map with execution context. Note that most of the objects contain there are not public
and the parameter is specified here to allow compatibility among the custom and internal comparsion methods.passRate - pass rate in form of a float value between 0 and 1. This user input value indicates
the lowest result which will be considered as match ("passed"). It is in fact the number specified by the
'passrate' parameter of the
commands Screenshot,
Compareto and
Waitfor match/mismatch.float compareToBaseImage(Image desktopImage, Rectangle area, String methodParams, ScriptingContext repository, float passRate)
This is just a convenience method used by the 'Waitfor match' command to perform repeated image
comparisons against one image.
The default image comparison algorithm is based on color histograms. A call of this method performs image comparison against precalculated base image histogram rather that against the base image pixels. As calculation of a color histograms is quite a time expensive operation, this approach allows to achieve higher performance.
Any custom implementation of this interface may or may not take advantage of this approach. If you don't want
to diferentiate between repeated and one time comparison calls, define the setBaseImage() and
compareToBaseImage() methods as follows:
// Base image
private Image baseImage;
// Set the base image
public void setBaseImage(Image img) {
baseImage = img;
}
// Compare an image with the base image
public float compareToBaseImage(Image desktopImage) {
return compare(desktopImage, baseImage);
}
desktopImage - an image to be compared to the base image.area - a rectangle area of the remote desktop to be used for image comparison. If the argument is null,
the whole remote desktop image will be used.methodParams - method parameters passed by the 'methodparams' parameter of
the 'CompareTo' or 'Waitfor update' command.repository - a Map with execution context. Note that most of the objects contain there are not public
and the parameter is specified here to allow compatibility among the custom and internal comparsion methods.passRate - pass rate in form of a float value between 0 and 1. This user input value indicates
the lowest result which will be considered as match ("passed"). It is in fact the number specified by the
'passrate' parameter of the commands Screenshot,
Compareto and
Waitfor match/mismatch.boolean isSecondImageRequired()
If this method returns true, commands CompareTo and WaitFor update
of the scripting language will require presence of the 'template' parameter which
specifies an image located in the filesystem to be compared to the current desktop.
If you wish just to analyze the desktop image instead of comparing it to another one, implement this method
to return false. The tool will not validate whether an image from the file system is
passed correctly. Note that commands will supply null instead of an image in all arguments
corresponding to the template image, i.e. expect method calls like compare(desktopImage, null) and
setBaseImage(null).
boolean isMethodParamsSupported()
methodparams
parameter of the scripting language.
When this method returns false, the tool will report a syntax error when this module gets used in a command
together with the methodparams parameter.
When this method returns true, commands using this module may take advantage of the methodparams
parameter to pass custom parameters which are not defined by the scripting language.
The default image comparison algorithm doesn't provide any custom parameters.