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.