guibot.calibrator module

class guibot.calibrator.Calibrator(needle=None, haystack=None, config=None)[source]

Bases: object

Provides with a group of methods to facilitate and automate the selection of algorithms and parameters that are most suitable for a given preselected image matching pair.

Use the benchmarking method to choose the best algorithm to find your image. Use the calibration method to find the best parameters if you have already chosen the algorithm. Use the search method to find the best parameters from multiple random starts from a uniform or normal probability distribution.

__init__(needle=None, haystack=None, config=None)[source]

Build a calibrator object for a given match case.

Parameters:
  • haystack (target.Image or None) – image to look in
  • needle (target.Target or None) – target to look for
benchmark(finder, random_starts=0, uniform=False, calibration=False, max_attempts=3, **kwargs)[source]

Perform benchmarking on all available algorithms of a finder for a given needle and haystack.

Parameters:
  • finder (finder.Finder) – CV backend whose backend algorithms will be benchmarked
  • random_starts (int) – number of random starts to try with (0 for nonrandom)
  • uniform (bool) – whether to use uniform or normal distribution
  • calibration (bool) – whether to use calibration
  • max_attempts (int) – maximal number of refinements to reach the parameter delta below the tolerance
Returns:

list of (method, similarity, location, time) tuples sorted according to similarity

Return type:

[(str, float, location.Location, float)]

Note

Methods that are supported by OpenCV and others but currently don’t work are excluded from the dictionary. The dictionary can thus also be used to assess what are the available and working methods besides their success for a given needle and haystack.

search(finder, random_starts=1, uniform=False, calibration=True, max_attempts=3, **kwargs)[source]

Search for the best match configuration for a given needle and haystack using calibration from random initial conditions.

Parameters:
  • finder (finder.Finder) – CV backend to use in order to determine deltas, fixed, and free parameters and ultimately tweak to minimize error
  • random_starts (int) – number of random starts to try with
  • uniform (bool) – whether to use uniform or normal distribution
  • calibration (bool) – whether to use calibration
  • max_attempts (int) – maximal number of refinements to reach the parameter delta below the tolerance
Returns:

maximized similarity

Return type:

float

If normal distribution is used, the mean will be the current value of the respective CV parameter and the standard variation will be determined from its delta.

calibrate(finder, max_attempts=3, **kwargs)[source]

Calibrate the available match configuration for a given needle and haystack minimizing the matchign error.

Parameters:
  • finder (finder.Finder) – configuration for the CV backend to calibrate
  • max_attempts (int) – maximal number of refinements to reach the parameter delta below the tolerance
Returns:

maximized similarity

Return type:

float

This method calibrates only parameters that are not protected from calibration, i.e. that have fixed attribute set to false. In order to set all parameters of a background algorithm for calibration use the finder.Finder.can_calibrate() method first. Any parameter values will only be changed if they improve the similarity, i.e. minimize the error. The deltas of the final parameters will represent the maximal flat regions in positive and/or negative direction where the same error is still obtained.

Note

All similarity parameters will be reset to 0.0 after calibration and can be set by client code afterwards.

Note

Special credits for this approach should be given to Prof. Sebastian Thrun, who explained it in his Artificial Intelligence for Robotics class.

run_default(finder, **_kwargs)[source]

Run a match case and return error from the match as dissimilarity.

Parameters:finder (finder.Finder) – finder with match configuration to use for the run
Returns:error obtained as unity minus similarity
Return type:float
run_performance(finder, **kwargs)[source]

Run a match case and return error from the match as dissimilarity and linear performance penalty.

Parameters:
  • finder (finder.Finder) – finder with match configuration to use for the run
  • max_exec_time (float) – maximum execution time before penalizing the run by increasing the error linearly
Returns:

error obtained as unity minus similarity

Return type:

float

run_peak(finder, **kwargs)[source]

Run a match case and return error from the match as failure to obtain high similarity of one match and low similarity of all others.

Parameters:
  • finder (finder.Finder) – finder with match configuration to use for the run
  • peak_location ((int, int)) – (x, y) of the match whose similarity should be maximized while all the rest minimized
Returns:

error obtained as unity minus similarity

Return type:

float

This run function doesn’t just obtain the optimum similarity for the best match in each case of needle and haystack but it minimizes the similarity for spatial competitors where spatial means other matches in the same haystack. Keep in mind that since matching is performed with zero similarity requirement, such matches might not be anything close to the needle. This run function finds use cases where the other matches could resemble the best one and we want to find configuration to better discriminate against those.