Adding matching methods

This software offers two methods for spatial template matching:

• SVRMatcher: Uses a pretrained SVR model.

• MaskMatcher: Uses template masks.

If you want a different way of deciding when a template matches the current TR, you can add your own matching method by defining a new Matcher as a subclass of Matcher.

1. Create your matcher class

Define a new class that inherits from Matcher. Your class must implement the following:

• _match(self, tr_data): required This method performs the actual matching computation for the current TR. It must return a 1D NumPy array of length Ntemplates containing the match scores for each template at the current TR.

During initalization, your matcher must:

• Set self.template_labels: List of template labels used for scoring.

• Set self.Ntemplates: Number of templates.

• Call self.setup_shared_memory() to initialize shared memory buffers.

• Call self.mp_shm_ready.set() once your matcher is fully initialized. This allows for integration with the streaming process.

If needed, you can load any templates or models it needs from a filepath. Add --match_path <filepath> when running rtcog.

Example:

class CustomMatcher(Matcher):
    def __init__(self, match_opts, Nt, sync, match_path):
     super().__init__(match_opts, Nt, sync, match_path)

        self.input = load_custom_model(match_path)  # Load your templates/model
        self.template_labels = list(self.input["labels"])
        self.Ntemplates = len(self.template_labels)

        self.setup_shared_memory()
        self.mp_shm_ready.set()

     def _match(self, tr_data):
         # Implement your matching logic here
         scores = compute_custom_scores(self.input, tr_data)
         return scores

Naming convention: Class names ending with “Matcher” are registered using the lowercase prefix (e.g., CustomMatcher → "custom"). If your class does not end with “Matcher”, it is registered using the full class name in lowercase (e.g., CustomMethod → "custommethod").

Private classes (classes that start with _) are not registered.

2. Enable the matcher in your config

Specify the matcher in your YAML config file under the matching section using the registered name:

matching:
  match_method: custom

The string “custom” automatically maps to your CustomMatcher class because of the naming convention.