Template Matching¶

Locate instances of a template image within a larger image using template matching with normalized cross-correlation, finding exact or near-exact matches of the template pattern at any location in the image, outputting bounding box detections with optional NMS filtering for object detection, logo detection, pattern recognition, and template-based object localization workflows.

How This Block Works¶

This block searches for occurrences of a template image within a larger input image using normalized cross-correlation template matching. The block:

1. Receives an input image and a template image (smaller pattern to search for)
2. Converts both images to grayscale for template matching (template matching typically works on grayscale images for efficiency and robustness)
3. Performs template matching using OpenCV's matchTemplate with TM_CCOEFF_NORMED method:
4. Slides the template across the input image at every possible position
5. Computes normalized cross-correlation coefficient at each position (measures similarity between template and image region)
6. Generates a similarity map showing how well the template matches at each location
7. Identifies match locations where similarity exceeds the matching_threshold:
8. Finds all positions where the correlation coefficient is greater than or equal to the threshold
9. Threshold values range from 0.0 to 1.0, with higher values requiring closer matches
10. Lower thresholds find more potential matches (including partial matches), higher thresholds find only very similar matches
11. Creates bounding boxes for each match:
12. Each match location becomes a detection with a bounding box matching the template's dimensions
13. All detections have confidence of 1.0 (they met the threshold requirement)
14. All detections are assigned class "template_match" and class_id 0
15. Each detection gets a unique detection ID for tracking
16. Optionally applies Non-Maximum Suppression (NMS) to filter overlapping detections:
17. Template matching often produces many overlapping detections at the same location (duplicate matches)
18. NMS removes overlapping detections, keeping only the best match in each area
19. NMS threshold controls how much overlap is allowed before removing detections
20. Can be disabled (apply_nms=False) if NMS becomes computationally intractable with very large numbers of matches
21. Attaches metadata to detections:
22. Sets parent_id to reference the input image
23. Sets prediction_type to "object-detection"
24. Stores image dimensions for coordinate reference
25. Attaches parent coordinate information for workflow tracking
26. Returns detection predictions in sv.Detections format along with the total number of matches found

The block uses normalized cross-correlation which is effective for finding exact or near-exact template matches. It works best when the template appears in the image at the same scale, rotation, and lighting conditions. The method tends to produce many overlapping detections for the same match location, which is why NMS filtering is important. However, in cases with extremely large numbers of matches (e.g., repeating patterns), NMS may become computationally expensive and can be disabled if needed.

Common Use Cases¶

• Logo and Brand Detection: Find specific logos or brand elements within images (e.g., detect company logos in photos, find brand markers in images, locate specific logo patterns in scenes), enabling logo detection workflows
• Exact Pattern Matching: Locate specific patterns or objects that appear identically in images (e.g., find specific UI elements in screenshots, detect exact patterns in images, locate specific visual elements), enabling exact pattern detection workflows
• Quality Control and Inspection: Find reference patterns or features for quality inspection (e.g., detect specific features in manufacturing images, find reference markers for alignment, locate inspection targets), enabling quality control workflows
• Object Localization: Locate specific objects or regions when exact appearance is known (e.g., find specific objects with known appearance, locate reference objects in images, detect specific visual elements), enabling template-based object localization
• Document Processing: Find specific elements or regions in documents (e.g., locate form fields in documents, detect specific document elements, find reference markers in scanned documents), enabling document processing workflows
• UI Element Detection: Detect specific UI components or elements in interface images (e.g., find buttons in UI screenshots, locate specific UI elements, detect interface components), enabling UI analysis workflows

Connecting to Other Blocks¶

This block receives an image and template, and produces detection predictions:

• After image input blocks to find template patterns in input images (e.g., search for templates in input images, locate patterns in camera feeds, find templates in image streams), enabling template matching workflows
• After preprocessing blocks to find templates in preprocessed images (e.g., match templates after image enhancement, find patterns in filtered images, locate templates in normalized images), enabling preprocessed template matching
• Before visualization blocks to visualize template match locations (e.g., visualize detected template matches, display bounding boxes for matches, show template match results), enabling template match visualization workflows
• Before filtering blocks to filter template matches by criteria (e.g., filter matches by location, select specific match regions, refine template match results), enabling filtered template matching workflows
• Before crop blocks to extract regions around template matches (e.g., crop areas around matches, extract match regions for analysis, crop template match locations), enabling template-based region extraction
• In quality control workflows where template matching is used for inspection or alignment (e.g., find reference markers for alignment, detect inspection targets, locate quality control features), enabling quality control template matching workflows

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/template_matching@v1to add the block as as step in your workflow.

Properties¶

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Available Connections¶

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Template Matching in version v1 has.

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/template_matching@v1",
    "image": "$inputs.image",
    "template": "$inputs.template",
    "matching_threshold": 0.8,
    "apply_nms": "$inputs.apply_nms",
    "nms_threshold": "$inputs.nms_threshold"
}