optimize_match#

optimize_match(score_object, bounds_translation=None, bounds_rotation=None, optimization_method='basinhopping', maxiter=50, x0=None)[source]#

Find the translation and rotation optimizing the score returned by score_object with respect to provided bounds.

Parameters:

score_object: object

Class object that defines a score method, which returns a floating point value given a tuple of floating points where the first half describes a translation and the second a rotation. The score will be minimized, i.e. it has to be negated if similarity should be optimized.

bounds_translationtuple of tuple float, optional

Bounds on the evaluated translations. Has to be specified per dimension as tuple of (min, max). Default is None.

bounds_rotationtuple of tuple float, optional

Bounds on the evaluated zyx Euler angles. Has to be specified per dimension as tuple of (min, max). Default is None.

optimization_methodstr, optional

Optimizer that will be used, basinhopping by default. For further information refer to Optimization and root finding (scipy.optimize).

differential_evolution	Highest accuracy but long runtime. Requires bounds on translation.
basinhopping	Decent accuracy, medium runtime.
minimize	If initial values are closed to optimum acceptable accuracy and short runtime

maxiterint, optional

The maximum number of iterations, 50 by default.

x0tuple of floats, optional

Initial values for the optimizer, zero by default.

Returns:

Tuple[ArrayLike, ArrayLike, float]: Optimal translation, rotation matrix and corresponding score.

Raises:

ValueError: If optimization_method is not supported.

Notes

This function currently only supports three-dimensional optimization and score_object will be modified during this operation.

Examples

Having defined score_object, for instance via create_score_object(), non-exhaustive template matching can be performed as follows

>>> translation_fit, rotation_fit, score = optimize_match(score_object)

translation_fit and rotation_fit correspond to the inverse of the applied translation and rotation, so the following statements should hold within tolerance

>>> np.allclose(translation, -translation_fit, atol = 1) # True
>>> np.allclose(rotation, np.linalg.inv(rotation_fit), rtol = .1) # True

Bounds on translation and rotation can be defined as follows

>>> translation_fit, rotation_fit, score = optimize_match(
>>>     score_object=score_object,
>>>     bounds_translation=((-5,5),(-2,2),(0,0)),
>>>     bounds_rotation=((-10,10), (-5,5), (0,0)),
>>> )

The optimization scheme and the initial parameter estimates can also be adapted

>>> translation_fit, rotation_fit, score = optimize_match(
>>>     score_object=score_object,
>>>     optimization_method="minimize",
>>>     x0=(0,0,0,5,3,-5),
>>> )