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