com.vncrobot.api
Interface ImageComparisonModule


public interface ImageComparisonModule

This class declares methods of image comparison used by the CompareTo, Screenshot and WaitFor commands of the VNCRobot 1.3.6 scripting language. You may implement this interface to create your own image comparison algorithm and plug it into VNCRobot. The interface also allows to create a method of analysis of the desktop image.

The following example implements a dummy comparison method.

 package mystuff;

 import java.awt.*;

 public class DummyComparisonModule implements com.vncrobot.api.ImageComparisonModule {

     // 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 VNCRobot 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, Hashtable 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, Hashtable 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;
     }
 }
 
NOTE: To compile this dummy module you need to place the vncrobot.jar file to your Java class path.

Once you compile your comparison module to a Java .class format, you have to perform the following two steps to plug it into VNCRobot:

To place your class file into VNCRobot class path edit either vncrobot.sh (Linux/Unix) or vncrobot.bat (Windows). It contains a java call like java -classpath jh.jar:vncrobot.jar com.vncrobot.VNCRobot <params>. You need to add the path to your class file to the list after the -classpath parameter.

Let's suppose your .class file is located at /root/projects/classes/mystuff/DummyComparisonModule.class. The java call will then look like:

You can of course use a relative path instead. Note that the only difference between Linux/Unix and Windows calls is the path separator ':', resp. ';'.

Next step is to configure VNCRobot to load the module. Search your home folder for a file called config.properties. It usually gets created by VNCRobot when you modify something in the user preferences for the first time. The file should contain the following two parameters which control module loading and behavior. If they are not there, simply add them to the end of the file:

The configuration is now complete. You can start the VNCRobot application 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 e.g. our dummy comparison module create commands like CompareTo <image file> method=dummy, Screenshot <image file> method=dummy or Waitfor update method=dummy.

NOTE: This interface is incompatible with versions lower than VNCRobot 1.3.6. The difference is that there's a new argument passRate in methods compare() and compareToBaseImage(). The reason for this change was to allow the built-in "search" image comparison module to handle custom pass rates to search non-exact matches of template images. See also bug #13035. To migrate your custom module to a new version simply add the new argument to your methods and recompile. No further change is neccessary.

Since: VNCRobot 1.2

(C) 2007 Robert Pes. All rights reserved. Date: Oct 13, 2007


Field Summary
static java.lang.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(java.awt.Image desktopImage, java.awt.Rectangle area, java.awt.Image image, java.lang.String methodParams, java.util.Hashtable repository, float passRate)
          Compare the desktop image to another image and return a number indicating how much they match.
 float compareToBaseImage(java.awt.Image desktopImage, java.awt.Rectangle area, java.lang.String methodParams, java.util.Hashtable repository, float passRate)
          Compare the desktop image to the base image and return a number indicating how much they match.
 java.lang.String getMethodDescription()
          Get the method description.
 java.lang.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 VNCRobot scripting language.
 boolean isSecondImageRequired()
          Determine whether we are comparing two images or just analyze the desktop image.
 void setBaseImage(java.awt.Image img)
          Set the base image.
 

Field Detail

SEARCH_COORD_LIST

static final java.lang.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
Method Detail

getMethodName

java.lang.String getMethodName()
Get the method name. It will be used as an identificator of the image comparison module in commands of the VNCRobot scripting language (parameter module of the 'CompareTo' and 'Waitfor update' commands) and in default comparison method configuration (user config parameter com.vcrobot.scripting.commands.CompareToCommand.defaultComparisonModule).

Method names are not case sensitive. Be sure not to specify a name which is reserved by VNCRobot or already used by another method. VNCRobot 1.3 reserves two names, 'default' and search. You can't override these names.

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

getMethodDescription

java.lang.String getMethodDescription()
Get the method description. Though this method is not used in VNCRobot 1.2, 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(java.awt.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 VNCRobot 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(java.awt.Image desktopImage,
              java.awt.Rectangle area,
              java.awt.Image image,
              java.lang.String methodParams,
              java.util.Hashtable 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 Hashtable 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 VNCRobot 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(java.awt.Image desktopImage,
                         java.awt.Rectangle area,
                         java.lang.String methodParams,
                         java.util.Hashtable 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 VNCRobot 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 Hashtable 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 VNCRobot 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 VNCRobot 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. VNCRobot will not validate whether an image from the file system is passed correctly. Note that VNCRobot 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 VNCRobot scripting language.

When this method returns false, VNCRobot 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 VNCRobot scripting language.

The default VNCRobot image comparison algorithm doesn't provide any custom parameters.

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