> 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/french/function-blocks/blocks-reference/detections-shapes/detectors/detect-reference.md).

# Detect Reference

Cette fonction recherche une image de référence à l'intérieur d'une image plus grande et renvoie des résultats de correspondance visuels et numériques. Elle est utile lorsque vous souhaitez trouver automatiquement où un objet connu apparaît dans une scène, même s'il est pivoté, redimensionné ou miroiré.

## 📥 Entrées <a href="#inputs" id="inputs"></a>

`Image` L'image d'entrée dans laquelle la référence sera recherchée (scène principale). C'est une prise d'entrée.

`Reference` L'image de l'objet de référence à trouver dans l'image principale. C'est une prise d'entrée.

`Mask` Masque optionnel pour limiter la zone de recherche ou ignorer des parties de la référence. C'est une prise d'entrée.

## 📤 Sorties <a href="#outputs" id="outputs"></a>

`Image Any` Une image de sortie avec annotations visuelles montrant les correspondances détectées (si le dessin est activé). C'est une prise de sortie.

`Object Positions` Coordonnées centrales de chaque instance détectée. C'est une prise de sortie.

`Object Count` Nombre total d'instances détectées. C'est une prise de sortie.

`Rectangle Coordinates` Coordonnées des rectangles de délimitation pour chaque détection. C'est une prise de sortie.

`Match Percentage` Confiance par détection ou(s) score(s) de correspondance. C'est une prise de sortie.

## 🕹️ Contrôles <a href="#controls" id="controls"></a>

`Match Threshold %` Curseur pour éliminer les correspondances à faible confiance. Des valeurs plus élevées réduisent les faux positifs.

`Down-size` Curseur pour réduire la taille de l'image et accélérer le traitement. Des images plus petites sont plus rapides mais peuvent perdre des détails fins.

`Rotations` Curseur pour définir le nombre de tranches d'angle testées (plus de tranches augmentent la robustesse à la rotation mais allongent le temps d'exécution).

`Sweep Angle` Sélecteur de plage qui définit l'étendue de rotation (angle de départ et d'arrivée) à explorer pendant la recherche.

`Include Flipped` Case à cocher pour inclure une version horizontalement retournée de la référence dans la recherche (utile pour les objets miroirés).

`Method` Menu déroulant pour choisir la méthode d'estimation de correspondance ; les options proposent des compromis entre précision et comportement.

`Color Mode` Menu déroulant pour basculer entre comparaison en niveaux de gris et en couleur complète (BGR). Le mode BGR est généralement plus précis pour les références texturées/colorées.

## 🎨 Fonctionnalités <a href="#features" id="features"></a>

* Recherche tolérante à la rotation : parcourt une plage d'angles de rotation pour trouver les instances pivotées.
* Contrôle échelle/performance : `Down-size` vous permet d'échanger précision et rapidité.
* Recherche optionnelle inversée : trouvez les apparences miroirées en activant `Include Flipped`.
* Support du masque : fournissez un `Mask` pour ignorer des parties de la référence ou de la scène.
* Mode sensible à la couleur : choisissez entre la correspondance en niveaux de gris et en BGR pour améliorer les résultats sur des références riches en couleur.
* Sorties visuelles et numériques : image annotée, points centraux, rectangles de délimitation, comptages et confidences de correspondance.

## ⚙️ Fonctionnement <a href="#how-it-works" id="how-it-works"></a>

* Le bloc peut réduire facultativement la taille des images si `Down-size` est configuré pour accélérer le traitement.
* La référence est testée sur plusieurs tranches de rotation définies par `Rotations` et `Sweep Angle`.
* Si `Include Flipped` est activé, la référence retournée est également testée.
* La `Method` et le `Color Mode` sélectionnés déterminent la façon dont chaque correspondance candidate est notée.
* Les correspondances qui atteignent ou dépassent le `Match Threshold %` sont signalées et éventuellement dessinées sur l'image de sortie.
* Les résultats sont renvoyés sous forme d'image annotée, liste de coordonnées centrales, nombre total, coordonnées de rectangles et(s) pourcentage(s) de correspondance.

## 📝 Instructions d'utilisation <a href="#usage" id="usage"></a>

1. Fournissez l'image de la scène à `Image` et l'échantillon de référence à `Reference`. Facultativement, fournissez un `Mask` pour restreindre les zones de correspondance.
2. Commencez avec des paramètres modérés : réglez `Match Threshold %` autour de 50–70 et gardez `Rotations` et `Down-size` faibles.
3. Inspectez les résultats en utilisant `Image Any` annotée et les sorties `Object Positions` / `Object Count`.
4. Ajustez les contrôles : augmentez `Rotations` pour des objets fortement pivotés, réduisez `Down-size` pour une meilleure précision, ou passez en `Color Mode` BGR pour des correspondances sensibles à la couleur.
5. Utilisez le masque pour réduire les faux positifs lorsque la référence contient un arrière-plan ou des motifs répétitifs.

## 💡 Astuces <a href="#tips-and-tricks" id="tips-and-tricks"></a>

* Si vos images d'entrée sont très grandes, ajoutez `Image Resize` ou `Image Resizer` avant ce bloc pour accélérer le traitement tout en préservant les détails nécessaires.
* Recadrez vers la zone d'intérêt avec `Image ROI Select` pour réduire la zone de recherche et les correspondances erronées.
* Prétraitez l'entrée avec `Blur`, `Denoising` ou `Contrast Optimization` pour réduire le bruit capteur et améliorer la stabilité des correspondances.
* Utilisez `Image Threshold` ou `Background Removal (RMBG-1.4)` lorsque la référence présente une séparation nette avant/arrière-plan pour simplifier la correspondance.
* Prévisualisez et vérifiez les détections avec `Show Image` pour ouvrir un visionneur d'image plus grand.
* Superposez des rectangles de détection ou des étiquettes avec `Draw Detections` si vous souhaitez une visualisation adaptée pour des rapports ou un traitement en aval.
* Enregistrez des exemples de résultats détectés avec `Image Logger` pour la constitution de jeux de données ou le débogage.

(indice : combiner ces blocs peut accélérer la correspondance et réduire les faux positifs — par exemple, recadrez avec `Image ROI Select`, améliorez le contraste avec `Contrast Optimization`, puis exécutez ce bloc.)

## 🛠️ Dépannage <a href="#troubleshooting" id="troubleshooting"></a>

* Aucune correspondance trouvée : essayez d'abaisser le `Match Threshold %`, augmentez `Rotations` si l'objet peut être pivoté, ou passez le `Color Mode` en BGR.
* Trop de faux positifs : augmentez le `Match Threshold %`, fournissez un `Mask` plus précis ou recadrez l'entrée avec `Image ROI Select`.
* Performance lente : réduisez `Rotations` ou augmentez `Down-size`. N'activez `Include Flipped` que si nécessaire.
* Correspondances partielles ou incohérentes : utilisez une référence de meilleure qualité (claire, fort contraste), prétraitez avec `Blur` ou `Contrast Optimization`, ou essayez le mode couleur BGR.

Si les problèmes persistent, essayez de combiner de petits prétraitements (resize → denoise → crop) pour faire ressortir la référence par rapport à l'arrière-plan.