Template Matching

Class: TemplateMatchingBlockV1

Source: inference.core.workflows.core_steps.classical_cv.template_matching.v1.TemplateMatchingBlockV1

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

Name	Type	Description	Refs
name	str	Enter a unique identifier for this step..	❌
matching_threshold	float	Minimum similarity threshold (0.0 to 1.0) required for a template match. Higher values (closer to 1.0) require very close matches and find fewer but more precise matches. Lower values (closer to 0.0) allow more lenient matches and find more potential matches including partial matches. Default is 0.8, which requires fairly close matches. Use lower thresholds (0.6-0.7) to find more matches or handle slight variations. Use higher thresholds (0.85-0.95) for exact matches only. The threshold compares normalized cross-correlation coefficients from template matching..	✅
apply_nms	bool	Whether to apply Non-Maximum Suppression (NMS) to filter overlapping detections. Template matching often produces many overlapping detections at the same location. NMS removes overlapping detections, keeping only the best match in each area. Default is True (recommended for most cases). Set to False if: (1) the number of matches is extremely large (NMS may become computationally expensive), (2) you want to see all raw matches without filtering, or (3) matches are intentionally close together and should all be kept. When disabled, you may see many duplicate detections for the same match location..	✅
nms_threshold	float	Intersection over Union (IoU) threshold for Non-Maximum Suppression. Only relevant when apply_nms is True. Detections with IoU overlap greater than this threshold are considered duplicates, and only the detection with highest confidence is kept. Lower values (0.3-0.4) are more aggressive at removing overlaps, removing detections that are only slightly overlapping. Higher values (0.6-0.7) are more lenient, only removing heavily overlapping detections. Default is 0.5, which provides balanced overlap filtering. Adjust based on how much overlap you expect between template matches and how close together valid matches can be..	✅

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

Available Connections

Compatible Blocks

Check what blocks you can connect to Template Matching in version v1.

• inputs: Mask Visualization, Classification Label Visualization, Detections Consensus, Webhook Sink, Dynamic Zone, Email Notification, QR Code Generator, Dynamic Crop, VLM As Detector, VLM As Detector, Image Blur, Corner Visualization, Image Convert Grayscale, Stability AI Outpainting, Halo Visualization, Stability AI Inpainting, JSON Parser, Image Contours, Trace Visualization, Morphological Transformation, Triangle Visualization, Relative Static Crop, Text Display, Stitch Images, Camera Calibration, Grid Visualization, Local File Sink, Slack Notification, VLM As Classifier, Roboflow Dataset Upload, Camera Focus, PTZ Tracking (ONVIF).md), Color Visualization, Dot Visualization, Image Slicer, Polygon Visualization, Line Counter Visualization, Contrast Equalization, Identify Changes, SIFT Comparison, Camera Focus, Background Subtraction, Image Slicer, Circle Visualization, SIFT Comparison, Identify Outliers, Halo Visualization, Blur Visualization, Label Visualization, Twilio SMS/MMS Notification, Clip Comparison, Email Notification, Ellipse Visualization, SIFT, Image Preprocessing, Model Monitoring Inference Aggregator, Image Threshold, Background Color Visualization, Model Comparison Visualization, Depth Estimation, Cosine Similarity, Absolute Static Crop, Roboflow Custom Metadata, Gaze Detection, Perspective Correction, Pixelate Visualization, Stability AI Image Generation, Reference Path Visualization, Keypoint Visualization, Polygon Visualization, Twilio SMS Notification, VLM As Classifier, Bounding Box Visualization, Polygon Zone Visualization, Icon Visualization, Crop Visualization, Motion Detection, Roboflow Dataset Upload
• outputs: Anthropic Claude, Mask Visualization, Classification Label Visualization, Detections Consensus, Detections Merge, Instance Segmentation Model, Webhook Sink, Email Notification, Dynamic Zone, QR Code Generator, Dynamic Crop, Path Deviation, Detection Offset, Image Blur, Corner Visualization, Byte Tracker, Line Counter, Stability AI Outpainting, Segment Anything 2 Model, Halo Visualization, Stability AI Inpainting, Object Detection Model, Image Contours, Path Deviation, Trace Visualization, Morphological Transformation, Triangle Visualization, Detections Stitch, Instance Segmentation Model, Text Display, Stitch Images, Detections Filter, Grid Visualization, Slack Notification, Detections Stabilizer, Roboflow Dataset Upload, PTZ Tracking (ONVIF).md), Camera Focus, Color Visualization, Detections Combine, Dot Visualization, Image Slicer, Polygon Visualization, Object Detection Model, Anthropic Claude, Line Counter Visualization, Keypoint Detection Model, Byte Tracker, Distance Measurement, Identify Changes, Detections Classes Replacement, SIFT Comparison, Dominant Color, Time in Zone, Velocity, Background Subtraction, Image Slicer, Circle Visualization, SIFT Comparison, Identify Outliers, Halo Visualization, Florence-2 Model, Blur Visualization, Florence-2 Model, Label Visualization, Twilio SMS/MMS Notification, Email Notification, Ellipse Visualization, Byte Tracker, Image Preprocessing, Model Monitoring Inference Aggregator, Detections List Roll-Up, Model Comparison Visualization, Background Color Visualization, Image Threshold, Size Measurement, Motion Detection, Time in Zone, Line Counter, Keypoint Detection Model, Absolute Static Crop, Roboflow Custom Metadata, Stitch OCR Detections, Perspective Correction, Anthropic Claude, Pixelate Visualization, Reference Path Visualization, Keypoint Visualization, Twilio SMS Notification, Polygon Visualization, Bounding Box Visualization, Detection Event Log, Overlap Filter, Icon Visualization, Crop Visualization, Time in Zone, Stitch OCR Detections, Pixel Color Count, Detections Transformation, Roboflow Dataset Upload

Input and Output Bindings

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

Bindings

• input

  • image (image): Large image in which to search for the template pattern. The template will be searched across this entire image at all possible positions. The image is converted to grayscale internally for template matching. Template matching works best when the image and template have similar lighting conditions and the template appears at similar scale and orientation in the image..
  • template (image): Small template image pattern to search for within the input image. The template should be smaller than the input image. The template is converted to grayscale internally for matching. Template matching finds exact or near-exact matches of this template at any location in the input image. Works best when the template appears in the image at the same scale, rotation, and lighting conditions. The template's dimensions determine the size of the detection bounding boxes..
  • matching_threshold (float): Minimum similarity threshold (0.0 to 1.0) required for a template match. Higher values (closer to 1.0) require very close matches and find fewer but more precise matches. Lower values (closer to 0.0) allow more lenient matches and find more potential matches including partial matches. Default is 0.8, which requires fairly close matches. Use lower thresholds (0.6-0.7) to find more matches or handle slight variations. Use higher thresholds (0.85-0.95) for exact matches only. The threshold compares normalized cross-correlation coefficients from template matching..
  • apply_nms (boolean): Whether to apply Non-Maximum Suppression (NMS) to filter overlapping detections. Template matching often produces many overlapping detections at the same location. NMS removes overlapping detections, keeping only the best match in each area. Default is True (recommended for most cases). Set to False if: (1) the number of matches is extremely large (NMS may become computationally expensive), (2) you want to see all raw matches without filtering, or (3) matches are intentionally close together and should all be kept. When disabled, you may see many duplicate detections for the same match location..
  • nms_threshold (float_zero_to_one): Intersection over Union (IoU) threshold for Non-Maximum Suppression. Only relevant when apply_nms is True. Detections with IoU overlap greater than this threshold are considered duplicates, and only the detection with highest confidence is kept. Lower values (0.3-0.4) are more aggressive at removing overlaps, removing detections that are only slightly overlapping. Higher values (0.6-0.7) are more lenient, only removing heavily overlapping detections. Default is 0.5, which provides balanced overlap filtering. Adjust based on how much overlap you expect between template matches and how close together valid matches can be..

• output

  • predictions (object_detection_prediction): Prediction with detected bounding boxes in form of sv.Detections(...) object.
  • number_of_matches (integer): Integer value.

Example JSON definition of step Template Matching in version v1

{
    "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"
}