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
 haystack (

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.
 finder (

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.
 finder (

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.
 finder (

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 runReturns: 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
 finder (

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.
 finder (
