# CompareImage

CompareImage compares a region of interest with a template image and returns an Image with white pixels where the region does not match the template within a certain tolerance.

## CompareImage Overview

CompareImage is designed to extract a template from the current image when the ForceTrain checkbox in the property sheet is selected. After the user deselects the checkbox, CompareImage can map the pixels from the template to the input image for comparison and for producing the greyscale output image. Pixels that do not match the template image within a certain tolerance are displayed as bright or white pixels.

## CompareImage Inputs

Parameters | Description
Image | This parameter must use Cell References in a spreadsheet cell that contains an Image data structure; by default, this parameter references A0, the cell containing the Image data structure returned by AcquireImage function. This parameter can also reference other Image data structures, such as those returned by the Vision Tool Image Functions.
Fixture | Defines the Region of Interest (ROI) relative to a Fixture input or the output of a Vision Tools function's image coordinate system. Setting the ROI relative to a Fixture ensures that if the Fixture is rotated or translated, the ROI will be rotated or translated in relation to the Fixture. The default setting is (0,0,0), the top leftmost corner of the image.
X | The X offset, in image coordinates.
Y | The Y offset, in image coordinates.
Theta | The rotation from the image X axis, in the image coordinate system. (+/-360 degrees clockwise)
Region | Also known as the Region of Interest (ROI), specifies the region of the image that undergoes analysis; creates an Interactive Graphics Mode that can be transformed and rotated. With this parameter selected, by pressing the Maximize Region button on the property sheet's Job Edit toolbar, the region will automatically be stretched to cover the entire image.
X | The x-offset of the origin, in fixture coordinates.
Y | The y-offset of the origin, in fixture coordinates.
Width | The dimension along the region's x-axis.
Height | The dimension along the region's y-axis.
Angle | The orientation, in fixture coordinates.
Note: The Fixture and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.
ForceTrain | Specifies when the template is extracted from the current image: either when the ROI dimensions are modified, or when the ForceTrain parameter is selected.
0 = OFF (default) | The template is extracted from the current image only when the ROI dimensions are modified. Chosen once the user has selected (or "trained") a template image, this disables the "training" parameter and prevents the template from being overwritten.
1 = ON | The template is extracted from the current image. This is chosen if the user is still in the process of selecting (or "training") a template image.
Edge Range | Specifies the number of pixels (0–24; default = 3) around an edge that will be tolerated during the image comparison. The higher the number, the less rigorous the edge matching between the template and the input image (in other words, the less likely imperfectly matched edges will be depicted as differences in the output image).
Interpolation | Specifies the type of pixel comparison to perform when mapping the template to the input image to produce the output image of the differences.
0 = Nearest Neighbor (default) | Each pixel in the template is compared with its nearest pixel in the input image to calculate the normalized greyscale difference for each pixel. This is a faster, but less accurate, method.
1 = Bilinear | Each pixel in the template is compared with a weighted average (which represents the greyscale value of the four nearest pixels in the input image) to calculate the normalized greyscale difference for each pixel. This is a more accurate, but slower, method.
Show | Specifies which graphical overlays are displayed on top of the image.
0 = hide all (default) | The available graphics items will be hidden, except when the cell containing the CompareImage function is highlighted in the spreadsheet.
1 = result graphics only | The processed image will be displayed at all times.
2 = input graphics only | The graphics items associated with the input image region will be displayed at all times.
3 = show all: input graphics and template image | The graphics items associated with the input image region will be displayed at all times; however, while in the CompareImage property sheet, the template image will also be displayed.

## CompareImage Outputs

Returns | An Image data structure containing the processed image, or #ERR if any of the input parameters are invalid.

## CompareImage Example

In this example, the goal is to use CompareImage to compare the template image of a "good" gasket with input images of gaskets on a production line.

First, after inserting CompareImage into the spreadsheet, the user defines the ROI by double-clicking on the word "Region" in the property sheet, which disappears to reveal the red ROI box overlaid on the image. The user moves or resizes the box using the cursor, and clicks the OK button on the Job Edit toolbar (or presses the Enter key) to confirm the selection and return to the property sheet.

Next, the user fixtures the tool to another data structure. In fixturing, the user identifies a distinctive feature that appears on all instances of the object and designates it as a reference point for subsequent vision tools. This allows precise comparisons or inspections to be made, even if the object is slightly rotated or shifted on the production line.

To fixture the function, the user clicks the word "Fixture" in the property sheet and clicks either the Absolute Reference or Relative Reference button on the property sheet's toolbar.

The property sheet disappears, revealing the In-Sight spreadsheet. The user moves the cursor to select the Row, Column and Angle cells from another data structure in the spreadsheet (for example, FindPatterns) as the reference for the fixture, and clicks the OK button on the Job Edit toolbar (or presses the Enter key) to confirm the selection and return to the property sheet.

Then, the user ensures that the ForceTrain checkbox in the property sheet is selected, so that a template image (below) can be extracted automatically when an image acquisition is manually triggered. (However, simply selecting the ForceTrain checkbox triggers the image acquisition, so if the current image is acceptable, the user can skip setting up the image and manually triggering the acquisition.) Once a template is selected, the user deselects the checkbox to prevent overwriting the template.

Accepting the default settings of the other parameters and clicking OK in the property sheet completes the configuration for this example and applies the function to the input image.

During run time, the tool compares the template image with the input image. A "bad" input image might consist of a gasket marred by white marks (below).

Differences between the two are displayed as bright pixels in the greyscale output image (below).

Another tool (for example, DetectBlobs; see below) can reference the output image to make a decision about whether the gasket passes or fails inspection.