scan_subsets

scan_subsets(matching_data, matching_score, matching_setup, callback_class=None, callback_class_args={}, job_schedule=(1, 1), target_splits={}, template_splits={}, pad_target_edges=False, pad_fourier=True, pad_template_filter=True, interpolation_order=3, jobs_per_callback_class=8, backend_name=None, backend_args={})

Wrapper around scan() that supports matching on splits of matching_data.

Parameters:

matching_datatme.matching_data.MatchingData

MatchingData instance containing relevant data.

matching_setuptype

Function pointer to setup function.

matching_scoretype

Function pointer to scoring function.

callback_classtype, optional

Analyzer class pointer to operate on computed scores.

callback_class_argsdict, optional

Arguments passed to the callback_class. Default is an empty dictionary.

job_scheduletuple of int, optional

Job scheduling scheme, default is (1, 1). First value corresponds to the number of splits that are processed in parallel, the second to the number of angles evaluated in parallel on each split.

target_splitsdict, optional

Splits for target. Default is an empty dictionary, i.e. no splits. See tme.matching_utils.compute_parallelization_schedule().

template_splitsdict, optional

Splits for template. Default is an empty dictionary, i.e. no splits. See tme.matching_utils.compute_parallelization_schedule().

pad_target_edgesbool, optional

Whether to pad the target boundaries by half the template shape along each axis.

pad_fourier: bool, optional

Whether to pad target and template to the full convolution shape.

pad_template_filter: bool, optional

Whether to pad potential template filters to the full convolution shape.

interpolation_orderint, optional

Order of spline interpolation for rotations.

jobs_per_callback_classint, optional

How many jobs should be processed by a single callback_class instance, if ones is provided.

Returns:

Optional[Tuple]

The merged results from callback_class if provided otherwise None.

See also

tme.matching_utils.compute_parallelization_schedule()

Examples

All data relevant to template matching will be contained in matching_data, which is a tme.matching_data.MatchingData instance and can be created like so

>>> import numpy as np
>>> from tme.matching_data import MatchingData
>>> from tme.matching_utils import get_rotation_matrices
>>> target = np.random.rand(50,40,60)
>>> template = target[15:25, 10:20, 30:40]
>>> matching_data = MatchingData(target, template)
>>> matching_data.rotations = get_rotation_matrices(
>>>    angular_sampling = 60, dim = target.ndim
>>> )

The template matching procedure is determined by matching_setup and matching_score, which are unique to each score. In the following, we will be using the FLCSphericalMask score, which is composed of tme.matching_scores.flcSphericalMask_setup() and tme.matching_scores.corr_scoring()

>>> from tme.matching_exhaustive import MATCHING_EXHAUSTIVE_REGISTER
>>> funcs = MATCHING_EXHAUSTIVE_REGISTER.get("FLCSphericalMask")
>>> matching_setup, matching_score = funcs

Computed scores are flexibly analyzed by being passed through an analyzer. In the following, we will use tme.analyzer.MaxScoreOverRotations to aggregate sores over rotations

>>> from tme.analyzer import MaxScoreOverRotations
>>> callback_class = MaxScoreOverRotations
>>> callback_class_args = {"score_threshold" : 0}

In case the entire template matching problem does not fit into memory, we can determine the splitting procedure. In this case, we halv the first axis of the target once. Splitting and job_schedule is typically computed using tme.matching_utils.compute_parallelization_schedule().

>>> target_splits = {0 : 1}

Finally, we can perform template matching. Note that the data contained in matching_data will be destroyed when running the following

>>> from tme.matching_exhaustive import scan_subsets
>>> results = scan_subsets(
>>>    matching_data = matching_data,
>>>    matching_score = matching_score,
>>>    matching_setup = matching_setup,
>>>    callback_class = callback_class,
>>>    callback_class_args = callback_class_args,
>>>    target_splits = target_splits,
>>> )

The results tuple contains the output of the chosen analyzer.