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

   • The first step is to prepare the data and set the stage for the matching operation. This step typically involves configuring FFT operations, selecting the appropriate backend for the computations, and defining parameters for the matching. The outcome of this step is a context where template matching is poised to be carried out efficiently. See the Setup functions section for available setup methods.

2. Scoring

   • Once the environment is set, the actual template matching is done using the scoring method. This method essentially computes how well the template fits at every possible location within the target. Depending on the application, various scoring methods might be employed (e.g., correlation, convolution). See the Scoring functions section for available scoring methods.

3. Callback

   • After scoring, it’s often essential to post-process the results, extract valuable metrics, or make decisions based on the scores. The callback is a mechanism that allows for such post-scoring operations. It could be visualizing the results, finding the maximum score, etc. Further details and callback options can be found in Analyzers.

This concept is embodied in the scan and scan_subsets methods below.

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

Methods

scan_subsets orchestrates the matching process, supporting parallel processing and post-scoring operations. scan_subsets is a wrapper around scan that enables template matching on data subsets, making it particularly useful for handling large datasets or targeting specific regions.

scan(matching_data, matching_setup, ...[, ...])	Run template matching.
scan_subsets(matching_data, matching_score, ...)	Wrapper around scan() that supports matching on splits of matching_data.

Setup functions

cc_setup(rfftn, irfftn, template, target, ...)	Setup function for comuting a unnormalized cross-correlation between target (f) and template (g)
lcc_setup(target, template, **kwargs)	Setup function for computing a laplace cross-correlation between target (f) and template (g)
corr_setup(rfftn, irfftn, template, ...)	Setup for computing a normalized cross-correlation between a target (f), a template (g) given template_mask (m)
cam_setup(template, target, **kwargs)	Like corr_setup() but with standardized target, template
flc_setup(rfftn, irfftn, template, ...)	Setup function for flc_scoring().
flcSphericalMask_setup(rfftn, irfftn, ...)	Setup for corr_scoring(), like flc_setup() but for rotation invariant masks.
mcc_setup(rfftn, irfftn, template, ...)	Setup function for mcc_scoring().

Scoring functions

corr_scoring(template, template_filter, ...)	Calculates a normalized cross-correlation between a target f and a template g.
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

For a method to be considered by pytme’s template matching engine, it needs to be registered via register_matching_exhaustive(). This enables developers to specify a unique name, setup function, scoring function, and a custom memory estimation class for their method. This ensures the modular and extensible design of pytme, allowing developers to continuously expand tme’s capabilities.

Adding a new template matching methods requires defining the following parameters:

• matching: Name of the matching method.

• matching_setup: The setup function associated with the name.

• matching_scoring: The scoring function associated with the name.

• memory_class: A custom memory estimation class, which inherits from MatchingMemoryUsage

register_matching_exhaustive(matching, ...)

Registers a new matching scheme.