public class ImageDiffModule extends Object implements ImageComparisonModule, ScreenDifferenceMethod, Plugin, ExtendedSearchCapabilities, SimilarityDrivenModule, com.tplan.robot.gui.components.ComparisonModuleGuiSupport, AdvancedImageComparisonModule, ConstantSupportingModule, ExtendedParamsObject, Stoppable
T-Plan Robot Enterprise, (C) 2009-2022 T-Plan Limited. All rights reserved.
Modifier and Type | Field and Description |
---|---|
static float |
DEFAULT_PASS_RATE |
CONTEXT_OBJECT_IMAGE_COMPARISON_FAILURE_DESC, SEARCH_COORD_LIST
Constructor and Description |
---|
ImageDiffModule() |
Modifier and Type | Method and Description |
---|---|
void |
checkDependencies(PluginManager manager)
Check whether the current product installation contains all dependencies
(other plugins) required to install this plugin.
|
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.
|
Map<Rectangle,int[]> |
getAllFailedPixels() |
String |
getCode()
Get plugin code.
|
Date |
getDate()
Get plugin release date.
|
float |
getDefaultPassRate()
Get the default pass rate value.
|
String |
getDescription()
Get plugin description to be displayed in the GUI.
|
String |
getDisplayName()
Get short plugin name to be displayed in the GUI.
|
String |
getHitDescription(Rectangle r,
StringBuilder label)
Get description of a particular match area.
|
List<Rectangle> |
getHits() |
List<Float> |
getHitSimilarities()
Get the list of match similarities as floats between 0 and 1.
|
Class |
getImplementedInterface()
Get Class of the exposed functional interface that this plugin implements.
|
String |
getLongDescription()
Get long description of the object - purpose, usage, parameter syntax etc.
|
int[] |
getLowestSupportedVersion()
Get the lowest required version of T-Plan Robot Enterprise.
|
String |
getMessageAfterInstall()
Get text of a message to be displayed after installation of this plugin.
|
String |
getMessageBeforeInstall()
Get text of a message to be displayed before installation of this plugin.
|
String |
getMethodDescription()
Get the method description.
|
String |
getMethodName()
Get the method name.
|
List<String> |
getParameters()
Get the list of parameter names supported by the object implementing this
interface.
|
List |
getParameterValues(String parameterName)
Get the list of acceptable values of a particular parameter (if known).
|
float |
getPassRateForConstant(String constantName) |
String |
getPassRateName()
Get alternative name for the default "pass rate".
|
Map<String,String> |
getPredefinedPassRateConstantDescriptions() |
Map<String,Number> |
getPredefinedPassRateConstants()
Define the optional map of the recognized pass rate constants.
|
Component |
getPreviewComponent(Window owner,
File selectedFile,
StringBuilder title)
Get the preview component.
|
Rectangle |
getRectangle() |
String |
getResultMessage(boolean useHtml,
StringBuilder title,
StringBuilder buttonLabel)
Get the message describing results of the last performed image
comparison.
|
String |
getShortDescription()
Get short description which describes in a few words purpose and role of
the object.
|
String |
getSupportContact()
Get support contact.
|
String |
getUniqueId()
Get unique ID associated with the plugin.
|
String |
getVendorHomePage()
Get the vendor home page.
|
String |
getVendorName()
Get vendor (provider) name to be displayed in the GUI.
|
int[] |
getVersion()
Get plugin version in form of an integer array.
|
List<Preference> |
getVisualParameters()
Get the list of supported parameters encapsulated in
Preference
instances. |
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.
|
boolean |
isStopped()
Find out whether the task has been already stopped.
|
boolean |
isTrackingOfFailedPixelsSupported() |
boolean |
requiresRestart()
Indicate whether installation of this plugin requires application restart.
|
void |
setBaseImage(Image img)
Set the base image.
|
void |
setParameters(Map<String,String> paramsAndValues)
Set parameters and their values in the object.
|
void |
setTrackingOfFailedPixelsEnabled(boolean enabled) |
void |
stop()
Call this method to request the implementing object to stop the current
task or activity.
|
String |
toString() |
boolean |
usesPassRate()
Indicate whether the module uses the pass rate as a parameter or not.
|
public static final float DEFAULT_PASS_RATE
public String getMethodName()
ImageComparisonModule
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.
getMethodName
in interface ImageComparisonModule
public String getMethodDescription()
ImageComparisonModule
getMethodDescription
in interface ImageComparisonModule
public void setBaseImage(Image img)
ImageComparisonModule
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.
setBaseImage
in interface ImageComparisonModule
img
- the base (component) image.public float compare(Image desktopImage, Rectangle area, Image image, String methodParams, ScriptingContext repository, float passRate)
ImageComparisonModule
compare
in interface ImageComparisonModule
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.public float compareToBaseImage(Image desktopImage, Rectangle area, String methodParams, ScriptingContext repository, float passRate)
ImageComparisonModule
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); }
compareToBaseImage
in interface ImageComparisonModule
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.public boolean isSecondImageRequired()
ImageComparisonModule
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)
.
isSecondImageRequired
in interface ImageComparisonModule
public boolean isMethodParamsSupported()
ImageComparisonModule
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.
isMethodParamsSupported
in interface ImageComparisonModule
public String getCode()
Plugin
Get plugin code. This string serves as an identifier of the functionality delivered by the plugin. For example, desktop client plugins return protocol name like "RFB" or "RDP" as their code.
Plugin code is used by pluggable instance factories to identify
a particular plugin. It may be used to replace internal plugins with
third party code. For
example if you develop a class which implements this and the
com.tplan.robot.remoteclient.RemoteDesktop
interfaces and the
getCode()
method returns "RFB", it will replace the internal
implementation of the RFB (VNC) client.
public String getDisplayName()
Plugin
getDisplayName
in interface Plugin
public String getDescription()
Plugin
getDescription
in interface Plugin
public String getVendorName()
Plugin
getVendorName
in interface Plugin
public String getSupportContact()
Plugin
getSupportContact
in interface Plugin
public int[] getVersion()
Plugin
new int[] { 1, 2, 3 }
.getVersion
in interface Plugin
public Class getImplementedInterface()
Plugin
com.tplan.robot.remoteclient.RemoteDesktopClient.class
.getImplementedInterface
in interface Plugin
public boolean requiresRestart()
Plugin
requiresRestart
in interface Plugin
public String getVendorHomePage()
Plugin
getVendorHomePage
in interface Plugin
public String getUniqueId()
Plugin
Get unique ID associated with the plugin. The plugin manager uses the ID together with the version string to identify whether a plugin is already installed and whether a newer version of the same plugin is available.
The unique ID in fact identifies a particular plugin delivered by a particular vendor. Plugin developers are recommended to choose an ID and keep it constant for all versions of one particular plugin. The ID is never displayed in the GUI so it doesn't have to be a readable text. To avoid conflicts with other vendors it is recommended to elaborate vendor or author name and feature description into the ID, for example "custom RFB client implemented by John Doe".
getUniqueId
in interface Plugin
public int[] getLowestSupportedVersion()
Plugin
getLowestSupportedVersion
in interface Plugin
public String getMessageBeforeInstall()
Plugin
getMessageBeforeInstall
in interface Plugin
public String getMessageAfterInstall()
Plugin
getMessageAfterInstall
in interface Plugin
public void checkDependencies(PluginManager manager) throws DependencyMissingException
Plugin
DependencyMissingException
if one or more dependencies are missing.checkDependencies
in interface Plugin
manager
- shared instance of the plugin manager.DependencyMissingException
- when one or more dependencies requested by this plugin is missing.public Map<Rectangle,int[]> getAllFailedPixels()
getAllFailedPixels
in interface ExtendedSearchCapabilities
public void setTrackingOfFailedPixelsEnabled(boolean enabled)
setTrackingOfFailedPixelsEnabled
in interface ExtendedSearchCapabilities
public boolean isTrackingOfFailedPixelsSupported()
isTrackingOfFailedPixelsSupported
in interface ExtendedSearchCapabilities
public Rectangle getRectangle()
getRectangle
in interface ExtendedSearchCapabilities
public List<Rectangle> getHits()
getHits
in interface ExtendedSearchCapabilities
public List<Float> getHitSimilarities()
SimilarityDrivenModule
getHitSimilarities
in interface SimilarityDrivenModule
public Map<String,Number> getPredefinedPassRateConstants()
ConstantSupportingModule
getPredefinedPassRateConstants
in interface ConstantSupportingModule
public Map<String,String> getPredefinedPassRateConstantDescriptions()
getPredefinedPassRateConstantDescriptions
in interface ConstantSupportingModule
public float getPassRateForConstant(String constantName)
getPassRateForConstant
in interface ConstantSupportingModule
public float getDefaultPassRate()
AdvancedImageComparisonModule
AdvancedImageComparisonModule.usesPassRate()
returns true.getDefaultPassRate
in interface AdvancedImageComparisonModule
public boolean usesPassRate()
AdvancedImageComparisonModule
usesPassRate
in interface AdvancedImageComparisonModule
public String getPassRateName()
AdvancedImageComparisonModule
getPassRateName
in interface AdvancedImageComparisonModule
public List<String> getParameters()
ExtendedParamsObject
getParameters
in interface ExtendedParamsObject
public List getParameterValues(String parameterName)
ExtendedParamsObject
getParameterValues
in interface ExtendedParamsObject
parameterName
- parameter namepublic void setParameters(Map<String,String> paramsAndValues)
ExtendedParamsObject
CaseTolerantHashMap
class);setParameters
in interface ExtendedParamsObject
paramsAndValues
- map of parameters and their values.public List<Preference> getVisualParameters()
ExtendedParamsObject
Preference
instances. It allows to specify a larger set of parameter properties such as
parameter name ("configuration key" in the Preferences object), label (short description),
description, expected value type and optional value limits and relationships with other
parameters. This allows the GUI to build and display the parameters in form of GUI components
in command property dialogs and validate the values entered by users..getVisualParameters
in interface ExtendedParamsObject
Preference
instances.public String getShortDescription()
ExtendedParamsObject
getShortDescription
in interface ExtendedParamsObject
public String getLongDescription()
ExtendedParamsObject
CustomHyperlinkListener
. This is optional
and the method may return null. The long description is typically
displayed by the GUI when user selects to view details of the object.getLongDescription
in interface ExtendedParamsObject
public Component getPreviewComponent(Window owner, File selectedFile, StringBuilder title)
com.tplan.robot.gui.components.ComparisonModuleGuiSupport
getPreviewComponent
in interface com.tplan.robot.gui.components.ComparisonModuleGuiSupport
owner
- the owning window.selectedFile
- the selected template image file.title
- optional output buffer for the preview title.public String getResultMessage(boolean useHtml, StringBuilder title, StringBuilder buttonLabel)
com.tplan.robot.gui.components.ComparisonModuleGuiSupport
getResultMessage
in interface com.tplan.robot.gui.components.ComparisonModuleGuiSupport
useHtml
- true should return the message in HTML, false in plain
text.title
- a buffer for the optional custom message title.buttonLabel
- label (name) for the button in the intended pop up.
The message mentions it.public String getHitDescription(Rectangle r, StringBuilder label)
com.tplan.robot.gui.components.ComparisonModuleGuiSupport
Get description of a particular match area. This is used by the
Search Hits
dialog which displays the text in a
text field whenever the match is selected in the drop down. This is
useful for example for OCR modules which wish to display the recognized
text along with its rectangle.
Modules which want to skip this functionality and made the description components invisible should make the method return null when the rectangle argument is null.
getHitDescription
in interface com.tplan.robot.gui.components.ComparisonModuleGuiSupport
r
- selected rectangle. The argument is null if no rectangle is
selected. As this typically corresponds to the view of all matches the
method should return a general text and/or label.label
- optional label to display the text with.public void stop()
Stoppable
public boolean isStopped()
Stoppable