Detect Reference

This function block searches a reference image inside a larger image and returns visual and numeric match results. It is useful when you want to automatically find where a known object appears in a scene, even if it is rotated, resized, or mirrored.

📥 Inputs

Image The input image in which the reference will be searched (main scene). This is an input socket.

Reference The reference object image to find inside the main image. This is an input socket.

Mask Optional mask to limit the search area or ignore parts of the reference. This is an input socket.

📤 Outputs

Image Any An output image with visual annotations showing detected matches (if drawing is enabled). This is an output socket.

Object Positions Center coordinates of each detected instance. This is an output socket.

Object Count Total number of detected instances. This is an output socket.

Rectangle Coordinates Bounding rectangle coordinates for each detection. This is an output socket.

Match Percentage Per-detection confidence or match score(s). This is an output socket.

🕹️ Controls

Match Threshold % Slider to eliminate low-confidence matches. Higher values reduce false positives.

Down-size Slider to reduce image size for faster processing. Smaller images run faster but may lose fine details.

Rotations Slider to set how many angle slices are tested (more slices increase robustness to rotation but increase runtime).

Sweep Angle Range selector that sets the rotation sweep (start and end angles) to explore during matching.

Include Flipped Checkbox to include a horizontally flipped version of the reference in the search (useful for mirrored objects).

Method Dropdown to choose the matching estimation method; options provide trade-offs in accuracy and behavior.

Color Mode Dropdown to switch between grayscale and full color comparison (BGR). BGR mode is usually more accurate for textured/colorful references.

🎨 Features

• Rotation-tolerant matching: searches across a sweep of rotation angles to find rotated instances.

• Scale/performance control: Down-size lets you trade accuracy for speed.

• Optional flipped-search: find mirrored appearances by enabling Include Flipped.

• Mask support: feed a Mask to ignore parts of the reference or the scene.

• Color-aware mode: choose between grayscale and BGR matching to improve results on color-rich references.

• Visual and numeric outputs: annotated image, center points, bounding rectangles, counts, and match confidences.

⚙️ How it runs

• The block optionally reduces image sizes when Down-size is set to speed up processing.

• The reference is tested across multiple rotation slices defined by Rotations and Sweep Angle.

• If Include Flipped is enabled, the flipped reference is also tested.

• The selected Method and Color Mode determine how each candidate match is scored.

• Matches that meet or exceed Match Threshold % are reported and optionally drawn on the output image.

• Results are returned as an annotated image, a list of center coordinates, a count, rectangle coordinates, and match percentage(s).

📝 Usage Instructions

1. Provide the scene image to Image and the reference sample to Reference. Optionally provide a Mask to restrict matching areas.

2. Start with moderate settings: set Match Threshold % around 50–70 and keep Rotations and Down-size low.

3. Inspect results using the annotated Image Any and the Object Positions / Object Count outputs.

4. Adjust controls: increase Rotations for heavily rotated objects, lower Down-size for better accuracy, or switch to Color Mode BGR for color-sensitive matches.

5. Use the mask to reduce false positives when the reference has background or repetitive patterns.

💡 Tips and Tricks

• If your input images are very large, add Image Resize or Image Resizer before this block to speed up processing while preserving needed detail.

• Crop to the area of interest with Image ROI Select to reduce search area and false matches.

• Preprocess the input with Blur, Denoising, or Contrast Optimization to reduce sensor noise and improve match stability.

• Use Image Threshold or Background Removal (RMBG-1.4) when the reference has a clear foreground/background separation to simplify matching.

• Preview and inspect detections with Show Image to open a larger image viewer.

• Overlay detection rectangles or labels using Draw Detections if you want a tailored visualization for reports or downstream processing.

• Log examples of detected results with Image Logger for dataset curation or debugging.

(hint: combining these blocks can speed up matching and reduce false positives — for example, crop with Image ROI Select, enhance contrast with Contrast Optimization, then run this block.)

🛠️ Troubleshooting

• No matches found: try lowering Match Threshold %, increase Rotations if the object may be rotated, or switch Color Mode to BGR.

• Too many false positives: increase Match Threshold %, provide a tighter Mask, or crop input with Image ROI Select.

• Slow performance: reduce Rotations or increase Down-size. Only enable Include Flipped when necessary.

• Partial or inconsistent matches: use a higher-quality reference (clear, high contrast), preprocess with Blur or Contrast Optimization, or try the BGR Color Mode.

If issues persist, try combining small preprocessing steps (resize → denoise → crop) to make the reference stand out from the background.