Exhaustive

Exhaustive template matching evaluates similarity along a provided set of rotations and all possible translations are sampled using Fast Fourier Transform (FFT) operations. Therefore, the algorithm is guaranteed to evaluate a provided set of configurations and to find a global optimum with a sufficiently high angular sampling rate.

Within pytme, exhaustive template matching is modularized into three primary stages: setup, scoring, and callback.

1. Setup: Creates a context where template matching is poised to be carried out efficiently. Setup functions involve data preparation, configuring FFT operations and pre-computing shared parameters.

2. Scoring: Sample scoring function across translational and rotational degrees of freedom.

3. Callback: Custom on the fly processing of template matching results using analyzers.

If you wish to integrate custom template matching methods into pytme, please refer to the Adding Custom Methods section.

Methods

match_exhaustive orchestrates the matching process, supporting parallel processing and analysis operations. Depending on user specification, parallelization can be performed by splitting the search region into subsets, and/or by distributing the angular search.

match_exhaustive(matching_data, ...[, ...])

Run exhaustive template matching over all translations and a subset of rotations specified in matching_data.

Concrete implementations are outlined below.

Setup functions

cc_setup(matching_data, fast_shape, ...)	Setup function for computing the unnormalized cross-correlation between target (f) and template (g)
lcc_setup(matching_data, **kwargs)	Setup function for computing the laplace cross-correlation between target (f) and template (g)
ncc_setup(matching_data, **kwargs)
cam_setup(matching_data, **kwargs)	Like flcSphericalMask_setup() but with standardized target and template
flc_setup(matching_data, fast_shape, ...)	Setup function for flc_scoring().
flcSphericalMask_setup(matching_data, ...)	Like flc_setup() for rotation invariant masks
mcc_setup(matching_data, fast_shape, ...)	Setup function for mcc_scoring().

Scoring functions

ncc_scoring(template, ft_target, fast_shape, ...)
flc_scoring(template, template_mask, ...[, ...])	Computes a normalized cross-correlation between target (f), template (g), and template_mask (m)
mcc_scoring(template, template_mask, ...[, ...])	Computes a normalized cross-correlation score between target (f), template (g), template_mask (m) and target_mask (t)

Adding Custom Methods

New scoring methods are registered via register_matching_exhaustive().

register_matching_exhaustive(matching, ...)

Registers a new matching scheme.

Adding a new template matching method requires defining the following:

• Name of the matching method

• Setup function associated with the name

• Scoring function associated with the name

• Custom memory estimation class inheriting from MatchingMemoryUsage

The following outlines an example implementation.

from tme.memory import MemoryProfile, register_memory
from tme.matching_exhaustive import register_matching_exhaustive

@register_memory("CustomMethod")
class CustomMethodMemoryUsage(MemoryProfile):
    """Memory estimator for CustomMethod."""
    base_float = 2
    base_complex = 1
    fork_float = 1
    fork_complex = 1

def custom_setup(target, template, **kwargs):
    """
    Prepare data structures for matching.

    Returns context dictionary with shared parameters.
    """
    # Setup implementation
    return context

def custom_scoring(score_space, rotated_template, **kwargs):
    """
    Compute similarity scores.
    """
    # Scoring implementation
    pass

register_matching_exhaustive("CustomMethod", custom_setup, custom_scoring)