org.safs.image

Class ScreenXYBTComparator

java.lang.Object

org.safs.image.ScreenXYBTComparator

All Implemented Interfaces:

java.lang.Runnable

public class ScreenXYBTComparator
extends java.lang.Object
implements java.lang.Runnable

Class which can be used by ImageUtils to provide parallel processing of screen image searches. This class is intended to be used to compare 1 single screen X,Y location for a target image--using that X,Y location as the top-left X,Y anchor for the pixels to test. The class supports "Bit Tolerance"-- in which the caller can specify that N bits are allowed to fail and still be considered a match.

Normal usage is to use an ExecutorService to handle multiple instances of this class searching multiple X,Y coordinates simultaneously.

Sample usage:

 
                ExecutorService pool = Executors.newFixedThreadPool(threads);
                ScreenXYBTComparator[] compare = new ScreenXYBTComparator[threads];
      ...
                if (useBitsTolerance){
                        if(compare[i]==null) {
                                compare[i] = new ScreenXYBTComparator(screenBuffer, screenModel, imageBuffer, imageModel, screenx, screeny, maxPixelErrors);
                                pool.execute(compare[tindex++]);
              ...
 

Once an instance has been created and run to completion, it can be reused. It is important, though, that the thread running the instance did, indeed, run to completion. This can be checked by calling the isDone() as needed.

Sample reuse:

 
                if(next_screenx  < maxScreenX && compare[i].isDone()){
                        compare[i].prepare(next_screenx, screeny);
                        pool.execute(compare[tindex++]);
                        ...
 

The overhead of parallel thread maintenance with each of these instances testing only 1 X,Y location per invocation probably makes this class a poor candidate when testing large areas of the screen. Initial testing suggests that when large areas of the screen are searched by a large number of Threads starting and stopping-- potentially thousands or hundreds of thousands of times--actually makes the search take longer.

Author:

Carl Nagle Nov 04, 2009

See Also:

ImageUtils, Executors, ExecutorService

Constructor Summary

Constructors

Constructor and Description
ScreenXYBTComparator(java.awt.image.DataBuffer screenshotBuffer, java.awt.image.SampleModel screenshot, java.awt.image.DataBuffer targetBuffer, java.awt.image.SampleModel target, int startScreenX, int startScreenY, int maxBTerrors) Initial instance and use of this class must be done through this constructor.

Method Summary

Modifier and Type	Method and Description
int	getPercentErrors() This is normally only called if the instance isDone() and getResult() signals a match and the calling thread wants to find out what percentage of pixel errors occurred during that match.
int	getPixelErrors() Normally only called if the instance isDone() and getResult() signals a match and the calling thread wants to find out how many pixel errors occurred during that match.
boolean	getResult() true if a completed search yielded a match.
int	getScreenX() Normally only called if the instance isDone() and getResult() signals a match and the calling thread wants to find out what screen x,y coordinate has that match.
int	getScreenY() Normally only called if the instance isDone() and getResult() signals a match and the calling thread wants to find out what screen x,y coordinate has that match.
boolean	isDone() true when a single thread execution has completed.
void	prepare(int screenX, int screenY) Used to prepare the instance for reuse on another screen X,Y location AFTER its initial search has completed.
void	run() Evaluate if the target image matches at the specified screen x,y coordinate.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ScreenXYBTComparator

public ScreenXYBTComparator(java.awt.image.DataBuffer screenshotBuffer,
                            java.awt.image.SampleModel screenshot,
                            java.awt.image.DataBuffer targetBuffer,
                            java.awt.image.SampleModel target,
                            int startScreenX,
                            int startScreenY,
                            int maxBTerrors)

Initial instance and use of this class must be done through this constructor. Following the constructor invocation, the instance is ready to be run by a Thread or Executor.

Parameters:

screenshotBuffer -

screenshot -

targetBuffer -

target -

startScreenX - -- the screen X coordinate to anchor this search.

startScreenY - -- the screen Y coordinate to anchor this search.

maxBTerrors - -- maximum number of "Bit Tolerance" pixel mismatches allowed before a search failure is reported.

See Also:

Thread, Executors

Method Detail

getResult

public boolean getResult()

true if a completed search yielded a match. false if no search has occurred, if the completed search yielded no match, or if the instance has been prepare()d for a new search. The value returned is not really valid unless isDone() returns true.

Returns:

true if a completed search yielded a match.

See Also:

isDone()

getScreenX

public int getScreenX()

Normally only called if the instance isDone() and getResult() signals a match and the calling thread wants to find out what screen x,y coordinate has that match.

Returns:

the screen x coordinate used to anchor the search.

getScreenY

public int getScreenY()

Normally only called if the instance isDone() and getResult() signals a match and the calling thread wants to find out what screen x,y coordinate has that match.

Returns:

the screen y coordinate used to anchor the search.

getPixelErrors

public int getPixelErrors()

Normally only called if the instance isDone() and getResult() signals a match and the calling thread wants to find out how many pixel errors occurred during that match.

Returns:

the number of pixel errors found during the search.

getPercentErrors

public int getPercentErrors()

This is normally only called if the instance isDone() and getResult() signals a match and the calling thread wants to find out what percentage of pixel errors occurred during that match. This is only calculated and valid after the search has completed with a successful match AND Bit Tolerance is in use allowing some number of pixel errors to be valid. Otherwise, the return value will always be 0--0% errors. This is because we do not proceed testing all pixels once the allowed errors have been exceeded. So we won't have a valid percentage of errors when a successful match is not achieved.

Returns:

the percentage of pixel errors found during the search.

prepare

public void prepare(int screenX,
                    int screenY)

Used to prepare the instance for reuse on another screen X,Y location AFTER its initial search has completed. Resets critical variables to their ready state. Following the invocation of this method the instance is ready to be run by a new Thread or Executor.

Parameters:

screenX - -- the new screen X coordinate to anchor the next search.

screenY - -- the new screen Y coordinate to anchor the next search.

See Also:

run()

isDone

public boolean isDone()

true when a single thread execution has completed. false if no thread has executed any search, or a search is in-progress. The value of the getResult() method is not really valid unless this method returns true.

Returns:

true when a single thread execution has completed.

See Also:

run(), getResult()

run

public void run()

Evaluate if the target image matches at the specified screen x,y coordinate. This is normally run by a separate Thread or Executor. The isDone() method can be used to determine when the instance is finished with its search. The getResult() method provides true or false after thread execution to know if the provided screen x,y coordinates is the location of the target image.

Specified by:

run in interface java.lang.Runnable

Parameters:

screenshotBuffer -

screenshot -

targetBuffer -

target -

startScreenX -

startScreenY -

maxBTerrors - - max number of pixel mismatches allowed (bit tolerance)

See Also:

isDone(), getResult()