|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
NOTE: To compile this dummy module you need to place the vncrobot.jar file to your Java class path.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; } }
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:
java -classpath jh.jar:vncrobot.jar:/root/projects/classes com.vncrobot.VNCRobot <params>
java -classpath jh.jar;vncrobot.jar;/root/projects/classes com.vncrobot.VNCRobot <params>
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:
com.vcrobot.scripting.commands.CompareToCommand.customComparisonClasses
- this parameter should
contain a semicolon separated list of image comparison module classes.
It is by default empty because the default comparison method is loaded internally. To add our dummy example
change the line like this:
com.vcrobot.scripting.commands.CompareToCommand.customComparisonClasses=mystuff.DummyComparisonModule
com.vcrobot.scripting.commands.CompareToCommand.defaultComparisonModule
- default method used for
image comparison. This is by default set to default
. If
you want VNCRobot to use your custom comparison module by default, set this parameter to the name of your method,
i.e. to the string returned by the getMethodName()
method of your module. To set e.g. our dummy module as
the default comparison method use:
com.vcrobot.scripting.commands.CompareToCommand.defaultComparisonModule=dummy
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
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. |
Method Detail |
---|
java.lang.String getMethodName()
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.
java.lang.String getMethodDescription()
void setBaseImage(java.awt.Image img)
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.
img
- float compare(java.awt.Image desktopImage, java.awt.Rectangle area, java.awt.Image image, java.lang.String methodParams, java.util.Hashtable 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 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.
float compareToBaseImage(java.awt.Image desktopImage, java.awt.Rectangle area, java.lang.String methodParams, java.util.Hashtable 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 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); }
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.
boolean isSecondImageRequired()
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)
.
boolean isMethodParamsSupported()
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.
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |