# 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.augelab.com/function-blocks/detections-shapes/detectors/detect-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.