HistogramComparisonModule (T-Plan Robot Enterprise 7.0 Code Documentation)

java.lang.Object
- com.tplan.robot.imagecomparison.histogram.HistogramComparisonModule

All Implemented Interfaces:

ImageComparisonModule, Plugin, ConfigurationKeys, Measurable, Stoppable
```
public class HistogramComparisonModule
extends Object
implements ImageComparisonModule, ConfigurationKeys, Stoppable, Measurable, Plugin
```
Image comparison module based on color histogram.

T-Plan Robot Enterprise, (C) 2009-2022 T-Plan Limited. All rights reserved.

Field Summary
- Fields inherited from interface com.tplan.robot.imagecomparison.ImageComparisonModule
  CONTEXT_OBJECT_IMAGE_COMPARISON_FAILURE_DESC, SEARCH_COORD_LIST
- Fields inherited from interface com.tplan.robot.preferences.ConfigurationKeys
  CAPTURE_USE_LEGACY_DIALOG, COMPARETO_MAX_LOADED_PIXEL_ROWS, COMPARETO_MAX_SEARCH_HITS, DEFAULT_MODULE_PARAM_NAME, EDITOR_BREAKPOINT_COLOR, EDITOR_EXECUTED_LINE_COLOR, EDITOR_SYNTAX_ERROR_COLOR, IO_ACTIVE_FILE, IO_OPEN_FILE_LIST, IO_RECENT_SCRIPTS, IO_RECENT_SERVERS, MAX_DYNAMIC_MENU_ITEMS, MODULE_LIST_PARAM_NAME, REFRESH_DAEMON_ENABLE, REFRESH_DAEMON_MAX_IDLE_TIME, REPEAT_COMPARISON_FOR_MOVED_MOUSE, SCRIPT_HANDLER_CHECK_SYNTAX_BEFORE_EXECUTION, SCRIPT_HANDLER_OPEN_INCLUDED_FILES, STATUS_BAR_MINIMUM_DISPLAYED_UPDATE_SIZE, TOOLBAR_LOCATION

Constructor Summary

Constructors
Constructor and Description

HistogramComparisonModule()

Constructors
Constructor and Description
`HistogramComparisonModule()`

Method Summary

All Methods Instance Methods Concrete Methods
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(ImageHistogram h, Image img, Rectangle rect)`
`float`	`compare(Image img1, Rectangle area, Image img2, String methodParams, ScriptingContext repository, float passRate)` Compare the desktop image to another image and return a number indicating how much they match.
`float`	`compareHistograms(ImageHistogram h1, ImageHistogram h2)`
`float`	`compareToBaseImage(Image img2, 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`	`getCode()` Get plugin code.
`Date`	`getDate()` Get plugin release date.
`String`	`getDescription()` Get plugin description to be displayed in the GUI.
`String`	`getDisplayName()` Get short plugin name to be displayed in the GUI.
`ImageHistogram`	`getHistogram(Image img, Rectangle rect)`
`ImageHistogram`	`getHistogram(int[] pixels, Rectangle histRect, Rectangle sourceRect)`
`Class`	`getImplementedInterface()` Get Class of the exposed functional interface that this plugin implements.
`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.
`int[]`	`getPixels(Image img, Rectangle r)`
`float`	`getProgress()` Get the task progress where 0 means "0% done" and 1 means "100% done".
`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.
`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`	`requiresRestart()` Indicate whether installation of this plugin requires application restart.
`void`	`setBaseImage(Image img)` Set the base image.
`void`	`stop()` Call this method to request the implementing object to stop the current task or activity.
`String`	`toString()`

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - HistogramComparisonModule
```
public HistogramComparisonModule()
```
- Method Detail
  - stop
```
public void stop()
```
    Description copied from interface: Stoppable
    
    Call this method to request the implementing object to stop the current task or activity.
    
    Specified by:
    
    stop in interface Stoppable
  - isStopped
```
public boolean isStopped()
```
    Description copied from interface: Stoppable
    
    Find out whether the task has been already stopped.
    
    Specified by:
    
    isStopped in interface Stoppable
    
    Returns:
    
    true if the task has been stopped, false otherwise. If the task hasn't been started yet, the method should return false.
  - getProgress
```
public float getProgress()
```
    Description copied from interface: Measurable
    
    Get the task progress where 0 means "0% done" and 1 means "100% done".
    
    Specified by:
    
    getProgress in interface Measurable
    
    Returns:
    
    a relative number between 0 and 1 indicating how much has been completed.
  - compare
```
public float compare(Image img1,
                     Rectangle area,
                     Image img2,
                     String methodParams,
                     ScriptingContext repository,
                     float passRate)
```
    Description copied from interface: ImageComparisonModule
    
    Compare the desktop image to another image and return a number indicating how much they match.
    
    Specified by:
    
    compare in interface ImageComparisonModule
    
    Parameters:
    
    img1 - 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.
    
    img2 - 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.
    
    Returns:
    
    a number between 0 and 1. While a value of 0 indicates 0% match (images do not match at all), 1 indicates a 100% match (images are equal).
  - setBaseImage
```
public void setBaseImage(Image img)
```
    Description copied from interface: ImageComparisonModule
    
    Set the base image.
    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.
    
    Specified by:
    
    setBaseImage in interface ImageComparisonModule
    
    Parameters:
    
    img - the base (component) image.
  - compareToBaseImage
```
public float compareToBaseImage(Image img2,
                                Rectangle area,
                                String methodParams,
                                ScriptingContext repository,
                                float passRate)
```
    Description copied from interface: ImageComparisonModule
    Compare the desktop image to the base image and return a number indicating how much they match.
    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); }
    Specified by:
    
    compareToBaseImage in interface ImageComparisonModule
    
    Parameters:
    
    img2 - 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.
    
    Returns:
    
    a number between 0 and 1. While a value of 0 indicates 0% match (images do not match at all), 1 indicates a 100% match (images are equal).
  - isSecondImageRequired
```
public boolean isSecondImageRequired()
```
    Description copied from interface: ImageComparisonModule
    
    Determine whether we are comparing two images or just analyze the desktop image.
    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).
    
    Specified by:
    
    isSecondImageRequired in interface ImageComparisonModule
    
    Returns:
    
    true for comparison mode, false for image analysis.
  - isMethodParamsSupported
```
public boolean isMethodParamsSupported()
```
    Description copied from interface: ImageComparisonModule
    
    Define whether this module supports some custom parameters which can be passed via the 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.
    
    Specified by:
    
    isMethodParamsSupported in interface ImageComparisonModule
    
    Returns:
    
    true if the module supports customized parameters, false if not.
  - getMethodName
```
public String getMethodName()
```
    Description copied from interface: ImageComparisonModule
    
    Get the method name. It will be used as an identificator of the image comparison module in commands of the scripting language (parameter 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.
    
    Specified by:
    
    getMethodName in interface ImageComparisonModule
    
    Returns:
    
    name of the module (image comparison method).
  - getMethodDescription
```
public String getMethodDescription()
```
    Description copied from interface: ImageComparisonModule
    
    Get the method description. Though this method is not used in versions 1.2 and lower, future versions may provide a GUI method of adding custom comparison method which will take advantage of the method description.
    
    Specified by:
    
    getMethodDescription in interface ImageComparisonModule
    
    Returns:
    
    Description of the image comparison method (algorithm).
  - getHistogram
```
public ImageHistogram getHistogram(Image img,
                                   Rectangle rect)
```
  - getHistogram
```
public ImageHistogram getHistogram(int[] pixels,
                                   Rectangle histRect,
                                   Rectangle sourceRect)
```
  - compare
```
public float compare(ImageHistogram h,
                     Image img,
                     Rectangle rect)
```
  - getPixels
```
public int[] getPixels(Image img,
                       Rectangle r)
```
  - compareHistograms
```
public float compareHistograms(ImageHistogram h1,
                               ImageHistogram h2)
```
  - getCode
```
public String getCode()
```
    Description copied from interface: 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.
    
    Specified by:
    
    getCode in interface Plugin
    
    Returns:
    
    plugin code (identifier). The name must not be null.
  - getDisplayName
```
public String getDisplayName()
```
    Description copied from interface: Plugin
    
    Get short plugin name to be displayed in the GUI.
    
    Specified by:
    
    getDisplayName in interface Plugin
    
    Returns:
    
    short plugin name.
  - getDescription
```
public String getDescription()
```
    Description copied from interface: Plugin
    
    Get plugin description to be displayed in the GUI.
    
    Specified by:
    
    getDescription in interface Plugin
    
    Returns:
    
    plugin description. May be null.
  - getVendorName
```
public String getVendorName()
```
    Description copied from interface: Plugin
    
    Get vendor (provider) name to be displayed in the GUI.
    
    Specified by:
    
    getVendorName in interface Plugin
    
    Returns:
    
    vendor name. May be null.
  - getSupportContact
```
public String getSupportContact()
```
    Description copied from interface: Plugin
    
    Get support contact. If the contact is a valid mail link like "mailto:<mailaddress>" or an HTTP link like "http://<link>", the application may follow it with appropriate program (mail client or web browser).
    
    Specified by:
    
    getSupportContact in interface Plugin
    
    Returns:
    
    support contact. May be null or a text to be displayed by the GUI or a valid URI.
  - getVersion
```
public int[] getVersion()
```
    Description copied from interface: Plugin
    
    Get plugin version in form of an integer array. Major version numbers are first. For example, version 1.2.3 should be represented as new int[] { 1, 2, 3 }.
    
    Specified by:
    
    getVersion in interface Plugin
    
    Returns:
    
    version number.
  - getImplementedInterface
```
public Class getImplementedInterface()
```
    Description copied from interface: Plugin
    
    Get Class of the exposed functional interface that this plugin implements. For example remote desktop clients return com.tplan.robot.remoteclient.RemoteDesktopClient.class.
    
    Specified by:
    
    getImplementedInterface in interface Plugin
    
    Returns:
    
    class instance of the implemented functional interface.
  - requiresRestart
```
public boolean requiresRestart()
```
    Description copied from interface: Plugin
    
    Indicate whether installation of this plugin requires application restart. If it returns true, users are asked to restart after plugin installation via GUI.
    
    Specified by:
    
    requiresRestart in interface Plugin
    
    Returns:
    
    true if installation of the plugin requires application restart, false otherwise.
  - getVendorHomePage
```
public String getVendorHomePage()
```
    Description copied from interface: Plugin
    
    Get the vendor home page. If the contact is a valid HTTP link like "http://<link>", the application may follow it with appropriate program (typically web browser).
    
    Specified by:
    
    getVendorHomePage in interface Plugin
    
    Returns:
    
    vendor home page URL.
  - getDate
```
public Date getDate()
```
    Description copied from interface: Plugin
    
    Get plugin release date.
    
    Specified by:
    
    getDate in interface Plugin
    
    Returns:
    
    plugin release date.
  - getUniqueId
```
public String getUniqueId()
```
    Description copied from interface: 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".
    
    Specified by:
    
    getUniqueId in interface Plugin
    
    Returns:
    
    unique plugin ID.
  - getLowestSupportedVersion
```
public int[] getLowestSupportedVersion()
```
    Description copied from interface: Plugin
    
    Get the lowest required version of T-Plan Robot Enterprise. If user attempts to install the plugin on a lower version, an error is reported.
    
    Specified by:
    
    getLowestSupportedVersion in interface Plugin
    
    Returns:
    
    the lowest T-Plan Robot Enterprise version supported by this plugin.
  - getMessageBeforeInstall
```
public String getMessageBeforeInstall()
```
    Description copied from interface: Plugin
    
    Get text of a message to be displayed before installation of this plugin. It may contain any relevant user information.
    
    Specified by:
    
    getMessageBeforeInstall in interface Plugin
    
    Returns:
    
    message to be displayed before installation.
  - getMessageAfterInstall
```
public String getMessageAfterInstall()
```
    Description copied from interface: Plugin
    
    Get text of a message to be displayed after installation of this plugin. It may contain any relevant user information.
    
    Specified by:
    
    getMessageAfterInstall in interface Plugin
    
    Returns:
    
    message to be displayed after installation.
  - checkDependencies
```
public void checkDependencies(PluginManager manager)
                       throws DependencyMissingException
```
    Description copied from interface: Plugin
    
    Check whether the current product installation contains all dependencies (other plugins) required to install this plugin. This method is called before the plugin is installed and it should throw a DependencyMissingException if one or more dependencies are missing.
    
    Specified by:
    
    checkDependencies in interface Plugin
    
    Parameters:
    
    manager - shared instance of the plugin manager.
    
    Throws:
    
    DependencyMissingException - when one or more dependencies requested by this plugin is missing.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class HistogramComparisonModule

Field Summary

Fields inherited from interface com.tplan.robot.imagecomparison.ImageComparisonModule

Fields inherited from interface com.tplan.robot.preferences.ConfigurationKeys

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

HistogramComparisonModule

Method Detail

stop

isStopped

getProgress

compare

setBaseImage

compareToBaseImage

isSecondImageRequired

isMethodParamsSupported

getMethodName

getMethodDescription

getHistogram

getHistogram

compare

getPixels

compareHistograms

getCode

getDisplayName

getDescription

getVendorName

getSupportContact

getVersion

getImplementedInterface

requiresRestart

getVendorHomePage

getDate

getUniqueId

getLowestSupportedVersion

getMessageBeforeInstall

getMessageAfterInstall

checkDependencies

toString