> 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/image-transformations/transformation-filters/alignment.md).

# Alignment

Ce bloc fonctionnel aligne une image de scène en utilisant un ensemble ordonné de modèles de référence (ROIs) et leurs boîtes englobantes correspondantes. Utilisez ce bloc pour corriger les décalages (translation) et les rotations afin que l'image de scène corresponde à une mise en page de référence connue.

## 📥 Inputs

`Scene Image`\
L'image à aligner. Fournissez une seule image (non vide).

`Reference ROIs`\
Un ou plusieurs modèles (ROIs) ordonnés utilisés pour la correspondance (fournir sous forme de liste). L'ordre définit la correspondance avec les boîtes englobantes.

`Reference BBoxes`\
Une ou plusieurs boîtes englobantes ordonnées qui correspondent aux Reference ROIs (fournir sous forme de liste). L'ordre doit correspondre aux ROIs.

## 📤 Outputs

`Aligned Image`\
L'image de scène après application de la correction d'alignement calculée.

`Translation`\
La correction de translation appliquée, sous la forme d'une paire (x, y).

`Angle`\
La correction de rotation appliquée, en degrés.

## 🕹️ Controls

`Mode`\
Choisissez entre l'alignement utilisant uniquement la translation (déplacement du centroïde) ou translation + angle (rotation + translation). Utilisez `Translation` si seul un décalage est nécessaire, et `Translation + Angle` si une correction de rotation est requise.

`Match Threshold %`\
Définissez le score minimum de correspondance requis pour chaque ROI de référence. Des valeurs plus élevées exigent des correspondances plus fortes.

`Include Flipped`\
Activez pour autoriser les versions horizontales (miroir) des modèles ROI lors de la recherche (utile si des objets peuvent apparaître inversés).

`Method`\
Choisissez la méthode de template matching. Certaines méthodes peuvent être plus rapides ou offrir de meilleurs résultats selon la texture et le contraste des références.

`Color Mode`\
Choisissez entre `Gray` (plus rapide) et `BGR` (peut améliorer la précision pour des modèles en couleur).

`Tolerance (+/- px)`\
Définissez une tolérance en pixels pour le résidu accepté après l'alignement. Une valeur plus grande accepte un ajustement plus lâche ; une valeur plus petite impose une plus grande précision.

## 🎨 Features

* Correspondance de références ordonnées : l'ordre des `Reference ROIs` et des `Reference BBoxes` détermine la correspondance utilisée pour calculer l'alignement.
* Deux modes d'opération : uniquement translation ou translation + angle pour corriger la rotation.
* Appariement optionnel avec modèles retournés horizontalement (`Include Flipped`) pour gérer les apparences en miroir.
* Plusieurs méthodes de matching et modes couleur pour équilibrer vitesse et précision.
* Contrôles numériques avec validation immédiate pour éviter les erreurs de configuration.

## 📊 How it runs

* Le bloc nécessite une `Scene Image` valide et des listes correspondantes pour `Reference ROIs` et `Reference BBoxes`.
* Chaque ROI est apparié à la scène dans l'ordre fourni ; la bbox correspondante donne l'emplacement attendu.
* Si les correspondances atteignent le `Match Threshold %`, le bloc calcule la translation nécessaire (et l'angle si sélectionné) pour aligner la scène.
* Le bloc renvoie l'`Aligned Image` corrigée ainsi que la `Translation` et l'`Angle` appliqués.
* Si des entrées manquent, sont vides ou si le nombre de ROIs et de BBoxes ne correspond pas, le bloc affichera un message d'erreur et s'arrêtera jusqu'à correction.

## 📝 Usage Instructions

1. Préparez un ensemble de références claires : créez de petits ROIs modèles qui identifient de façon unique des repères fixes dans la scène.
2. Fournissez les définitions de bbox correspondantes dans le même ordre que les ROIs.
3. Choisissez le `Mode` en fonction de la nécessité d'une correction de rotation.
4. Réglez le `Match Threshold %` pour accepter les vraies correspondances tout en rejetant les similarités accidentelles.
5. Activez éventuellement `Include Flipped` si des versions en miroir peuvent apparaître.
6. Lancez le bloc et inspectez l'`Aligned Image` et les sorties numériques pour vérifier les résultats.

## 💡 Tips and Tricks

* Utilisez `Image ROI` ou `Image ROI Select` pour créer des modèles de référence précis à partir d'une image d'exemple avant de les fournir dans `Reference ROIs`.
* Pour définir plusieurs régions de manière interactive, utilisez `Image ROI Polygon Multi` pour sauvegarder plusieurs ROIs de référence.
* Pour vérifier visuellement le résultat d'alignement, connectez la sortie `Aligned Image` à `Show Image`.
* Pour des correspondances robustes sur des scènes texturées, essayez `Color Mode = BGR` et testez différentes valeurs de `Method`.
* Si l'extraction automatique de modèles est nécessaire, utilisez `Find Object` pour localiser des instances, puis dérivez des ROIs à partir des coordonnées retournées.
* Sauvegardez les images alignées avec `Image Logger` ou `Image Write` si vous souhaitez conserver un historique des images corrigées.

## 🛠️ Troubleshooting

* Mismatch entre ROIs et BBoxes\
  Assurez-vous que le nombre et l'ordre des `Reference ROIs` et des `Reference BBoxes` sont identiques. Le bloc s'appuie sur l'ordre pour définir les correspondances.
* Pas assez de références pour le mode rotation\
  Si vous sélectionnez `Translation + Angle`, fournissez au moins deux références distinctes ; sinon la rotation ne peut pas être résolue de manière fiable.
* Faible nombre de correspondances ou échecs\
  Augmentez légèrement le `Match Threshold %` si vous avez des faux positifs, ou diminuez-le si des références valides sont manquées. Essayez aussi de changer la `Method` ou le `Color Mode` pour améliorer les résultats.
* Résidu inattendu après alignement\
  Augmentez `Tolerance (+/- px)` si de petites erreurs de position sont acceptables, ou affinez vos ROIs de référence pour obtenir une meilleure précision.
* Vérification visuelle\
  Si l'alignement semble incorrect, prévisualisez les modèles intermédiaires et l'`Aligned Image` via `Show Image` pour diagnostiquer quelle référence n'a pas été appariée.