# 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 you deselect 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 function. This parameter can also reference other Image data structures, such as those returned by the Vision Tool Image Functions Image Functions or Coordinate Transforms Functions.
Fixture | Defines the Region of Interest (ROI) relative to a Fixture input or the output of the image coordinate system for the Vision Tools function. Setting the ROI relative to a Fixture ensures that if the Fixture is rotated or translated, the ROI is rotated or translated in relation to the Fixture. Note: 2D projections use real world units but fixturing with 2D tools requires input in pixel values. When using a 2D projection from a 3D point cloud as a Fixture, convert the real world units to pixel values using the TransWorldToPixel function. 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. Double-click on the Region parameter to create an Interactive Graphics Mode that you can transform and rotate. Select this parameter and press the Maximize Region button on the Job Edit toolbar of the property sheet to automatically stretch the region 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 X-axis of the region.
Height | The dimension along the Y-axis of the region.
Angle | The orientation, in fixture coordinates.
Note: The Fixture and Region parameters must be defined within the bounds of the image. Otherwise, the function returns #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 you select (or "train") 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 you are 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 are hidden, except when the cell containing the CompareImage function is highlighted in the spreadsheet.
1 = result graphics only | The processed image is displayed at all times.
2 = input graphics only | The graphics items associated with the input image region are displayed at all times.
3 = show all: input graphics and template image | The graphics items associated with the input image region are displayed at all times. However, while in the CompareImage property sheet, the template image is also 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.

1. After inserting CompareImage into the spreadsheet, define 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. Move or resize the box using the cursor, and click the OK button on the Job Edit toolbar (or presses the Enter key) to confirm the selection and return to the property sheet.

2. Fixture the tool to another data structure. In fixturing, identifiy a distinctive feature that appears on all instances of the object and designate 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.

3. To fixture the function, click the word "Fixture" in the property sheet and click either the Absolute Reference or Relative Reference button on the toolbar of the property sheet.

4. The property sheet disappears, revealing the In-Sight spreadsheet. Move 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. Click the OK button on the Job Edit toolbar (or presses the Enter key) to confirm the selection and return to the property sheet.

5. Ensure 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, you can skip setting up the image and manually triggering the acquisition.) Once a template is selected, deselect the checkbox to prevent overwriting the template.

6. Accept the default settings of the other parameters and click OK in the property sheet to complete the configuration for this example and apply 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.