T-Plan Robot Enterprise 4.2.2
Build No. 4.2.2-20170710.1

com.tplan.robot.imagecomparison
Interface ImageComparisonModule

All Known Implementing Classes:
HistogramComparisonModule, ObjectSearchModule, SearchImageComparisonModule, SearchImageComparisonModule2, TesseractOCR, TextRecognitionComparisonModule

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-2017 T-Plan Limited. All rights reserved.


Field Summary
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.
 
Method Summary
 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.
 

Field Detail

SEARCH_COORD_LIST

static final String SEARCH_COORD_LIST
This is a key used by the search image comparison module to save list of coordinates to the repository table.

See Also:
Constant Field Values

CONTEXT_OBJECT_IMAGE_COMPARISON_FAILURE_DESC

static final String CONTEXT_OBJECT_IMAGE_COMPARISON_FAILURE_DESC
The key the image comparison method may store the failure description to the context. It will be then displayed by the log and in the GUI to make debugging easier. Supported since 4.1.1.

See Also:
Constant Field Values
Method Detail

getMethodName

String getMethodName()
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.

Returns:
name of the module (image comparison method).

getMethodDescription

String getMethodDescription()
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.

Returns:
Description of the image comparison method (algorithm).

setBaseImage

void setBaseImage(Image img)
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.

Parameters:
img -

compare

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.

Parameters:
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.
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).

compareToBaseImage

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.

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);
     }
 

Parameters:
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.
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

boolean isSecondImageRequired()
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).

Returns:
true for comparison mode, false for image analysis.

isMethodParamsSupported

boolean isMethodParamsSupported()
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.

Returns:
true if the module supports customized parameters, false if not.

T-Plan Robot Enterprise 4.2.2
Build No. 4.2.2-20170710.1