> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/function-blocks/blocks-reference/detections-shapes/detectors/detect-reference.md). # 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.