> 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/analysis/structural-similarity.md).

# Structural Similarity

This function block compares two images and returns a similarity score (percentage) that reflects how structurally similar they are. It is designed for quick visual comparison tasks such as change detection, quality check, or validation of image processing steps.

## 📥 Inputs (sockets) <a href="#inputs" id="inputs"></a>

`Image Any` First image to compare.\
`Image Any` Second image to compare.

Note: Both input images must have the same resolution and channels for a valid comparison.

## 📤 Outputs (sockets) <a href="#outputs" id="outputs"></a>

`Similarity Percentage` Numeric value between 0 and 100 representing the structural similarity of the two inputs.

## 🕹️ Controls <a href="#controls" id="controls"></a>

This function block has no interactive controls. It runs when inputs are available.

## 🎯 Features <a href="#features" id="features"></a>

* Provides a single numeric similarity score that is easy to use for thresholds and decision logic.
* Works directly with color or grayscale images (requires same dimensions).
* Simple integration into inspection flows for automated pass/fail checks.

## ⚙️ Running mechanism <a href="#running-mechanism" id="running-mechanism"></a>

* When both image inputs are present and match in size, the block computes a structural similarity score and outputs it as a percentage.
* If the images differ in size, the block reports an error and does not produce a valid score.
* Designed to be used as a lightweight comparison step inside continuous image-processing pipelines.

## 📝 Usage <a href="#usage" id="usage"></a>

1. Provide two images to the input sockets.
2. Ensure both images have identical dimensions and channel count.
3. Read the `Similarity Percentage` output and use it for logging, decision making, or downstream logic.

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

* To ensure images match in size, use `Image Resize` or `Image Resizer` before this block.
* If images might be rotated or shifted, add `Auto Alignment` to align them first for more meaningful comparison.
* To focus comparison on a specific area, crop with `Image ROI Select` and feed the cropped images to this block.
* Normalize intensity or contrast differences with `Normalize Image` or `Contrast-Brightness-Gamma` to reduce false differences caused by lighting.
* Use `Image AutoRotator` if input orientation may differ between sources.
* Visualize inputs with `Show Image` to inspect what is being compared.
* Log or save comparison images and results with `Image Logger` or `Image Write` for traceability.
* Use `Mean Value of Image` or `Image Resolution and Channel Value` to quickly check brightness and size before comparison.

## 🛠️ Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

* If you see an error about image size, confirm both inputs have the same width, height, and channel count. Consider using `Image Resize`.
* Unexpectedly low similarity despite visually similar images may indicate misalignment, color-range differences, or different crop regions — try `Auto Alignment`, `Normalize Image`, or cropping with `Image ROI Select`.
* If no output appears, check that both input sockets are connected and not sending `None`. Use `Show Image` or debugging blocks to verify incoming data.