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

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