> 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/image-transformations/transformation-filters/alignment.md). # Alignment This function block aligns a scene image using an ordered set of reference templates (ROIs) and their corresponding bounding boxes. Use this block to correct translation and rotation errors so the scene image matches a known reference layout. ## đŸ“Ĩ Inputs `Scene Image` The image to be aligned. Provide a single image (non-empty). `Reference ROIs` One or more ordered template images used for matching (provide as a list). The order defines correspondence with the bounding boxes. `Reference BBoxes` One or more ordered bounding boxes that pair with the reference ROIs (provide as a list). The order must match the ROIs. ## 📤 Outputs `Aligned Image` The scene image after the computed alignment correction is applied. `Translation` The applied translation correction as an (x, y) pair. `Angle` The applied rotation correction in degrees. ## 🕹ī¸ Controls `Mode` Choose between alignment using only translation (centroid shift) or translation plus angle (rotation + translation). Use `Translation` when only shifting is needed and `Translation + Angle` when rotation correction is required. `Match Threshold %` Set the minimum match score required for each reference ROI. Higher values require stronger matches. `Include Flipped` Toggle to allow horizontally flipped versions of the ROI templates during matching (helpful when objects may appear mirrored). `Method` Choose the template matching method. Different methods can be faster or provide better results depending on the texture and contrast of your references. `Color Mode` Choose between `Gray` (faster) and `BGR` (may improve accuracy for colored templates). `Tolerance (+/- px)` Set a pixel tolerance for the allowed residual after alignment. Use larger values to accept looser fits, smaller values to require more precise alignment. ## 🎨 Features * Ordered reference matching: ROI and bbox order determines correspondence used to compute the alignment. * Two operation modes: translation-only or translation + angle for rotation correction. * Optional flipped-template matching to handle mirrored appearances. * Multiple matching methods and color modes to balance speed and accuracy. * Numeric controls with immediate validation to help avoid configuration mistakes. ## 📊 How it runs * The block requires a valid `Scene Image` and matching lists for `Reference ROIs` and `Reference BBoxes`. * Each ROI is matched to the scene in the order provided; the corresponding bbox gives the expected location. * If matches meet the `Match Threshold %` the block computes the necessary translation (and angle when selected) to align the scene. * The block returns the corrected `Aligned Image` plus the applied `Translation` and `Angle`. * If inputs are missing, empty, or the counts of ROIs and BBoxes do not match, the block will present an error message and stop until corrected. ## 📝 Usage Instructions 1. Prepare a clear reference set: create small template ROIs that uniquely identify fixed landmarks in the scene. 2. Provide matching bbox definitions in the same order as the ROIs. 3. Choose `Mode` depending on whether rotation correction is needed. 4. Set `Match Threshold %` to a value that accepts true matches while rejecting accidental similarities. 5. Optionally enable `Include Flipped` if mirrored versions may appear. 6. Run the block and inspect the `Aligned Image` and numeric outputs to verify results. ## 💡 Tips and Tricks * Use `Image ROI` or `Image ROI Select` to create precise reference templates from an example image before feeding them into `Reference ROIs`. * When you need to define multiple regions interactively, use `Image ROI Polygon Multi` to save several reference ROIs. * If you want to visually verify alignment results, connect the `Aligned Image` output to `Show Image` to preview corrections. * For robust matching on textured scenes, try switching `Color Mode` to `BGR` and experiment with different `Method` selections. * If automatic template extraction is needed, use `Find Object` to locate instances and then derive ROIs from the reported coordinates. * Save aligned outputs using `Image Logger` or `Image Write` when you want to keep records of corrected frames. ## 🛠ī¸ Troubleshooting * Mismatch between ROIs and BBoxes\ Make sure the number and order of `Reference ROIs` and `Reference BBoxes` are identical. The block relies on ordering to define correspondence. * Not enough references for rotation mode\ If you select `Translation + Angle` ensure you provide at least two distinct references; otherwise rotation cannot be solved reliably. * Low match counts or failed matches\ Increase the `Match Threshold %` if you get false positives, or lower it slightly if genuine references are missed. Try switching `Method` or `Color Mode` for improved results. * Unexpected residual after alignment\ Increase `Tolerance (+/- px)` if small positioning errors are acceptable, or refine your reference ROIs to be more distinctive for higher precision. * Visual verification\ If alignment looks incorrect, preview the intermediate templates and the `Aligned Image` using `Show Image` to diagnose which reference failed to match.