> 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/operations/subtract-images.md).

# Subtract Images

This function block computes the pixel-wise difference between two images to highlight changes or defects. It is useful for comparison tasks such as detecting deviations from a reference, visual inspection, and motion/change analysis.

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

`Actual Image` Input socket — the image to be compared (source image).

`Reference Image` Input socket — the image to subtract from the actual image (baseline or reference).

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

`Difference Image` Output socket — resulting image showing the per-pixel difference between the inputs.

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

This block has no user-facing controls or widgets.

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

* Produces a visual difference image that emphasizes pixel-level changes between two equally sized images.
* Works with color or grayscale images (both inputs must share the same dimensions).
* Simple and fast operation suitable as a preprocessing step for downstream detection or logging.

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

When both input sockets provide images, the block produces a `Difference Image` by performing a per-pixel subtraction of the reference from the actual image. The block requires that both images have identical dimensions; if sizes differ, the block will report an error. The difference output can be fed into visualization, thresholding or counting blocks to interpret the result.

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

1. Connect a source image to the `Actual Image` input socket.
2. Connect a baseline or reference image to the `Reference Image` input socket.
3. Make sure both images have the same size. If not, insert the `Image Resize` block before this block.
4. Use the `Difference Image` output for visualization or further processing.

Examples of common workflows:

* Visual inspection: connect `Difference Image` to `Show Image` to preview changes.
* Binary detection: feed `Difference Image` into `Image Threshold` to create a mask of changed areas.
* Quantification: pass the thresholded mask to `Non-zero of Image` to count changed pixels.
* Logging: save results with `Image Logger` or `Image Write` for record keeping.

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

* Ensure image alignment and resolution match before subtraction. Use `Image Resize` or geometric alignment blocks if needed.
* To make subtle differences more visible, apply `Contrast Optimization` or `Normalize Image` to the `Difference Image` before visualization.
* Convert the difference to a binary mask using `Image Threshold` to isolate meaningful changes. Combine the mask with `Non-zero of Image` to get a numeric measure of change.
* For quick inspection during development, connect the output to `Show Image`. For automated runs, save results with `Image Logger` or `Image Write`.
* If you expect single-channel output, check input channel formats (grayscale vs RGB) upstream and convert consistently.

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

* Mismatched image sizes\
  Ensure both inputs share the same width and height. Use the `Image Resize` block to resample one of the images.
* Very low or no visible difference\
  Apply `Contrast Optimization` or `Normalize Image` to amplify small changes, or use `Image Threshold` to create a binary mask.
* Unexpected colors or channels\
  Confirm both inputs are in the same color space (both grayscale or both RGB) before connecting them.
* Need a numeric change measure\
  After thresholding the difference, send the mask to `Non-zero of Image` to obtain a count of changed pixels.