# WhiteBalance

Available for color In-Sight 3800 series vision systems only, the WhiteBalance function is used to equalize the RGB colors of the acquired image for each subsequent acquisition to compensate for differing lighting conditions. As a result, items that are actually white in the device's acquisition area will appear white in the acquired images as well.

Acquired image before white balancing. | Acquired image after white balancing.

To perform white balancing successfully, ensure that the following image acquisition conditions are met:

- Lighting (either by external illumination or by the device's integrated illumination, if available) and Acquisition settings (such as Gain, Offset, Exposure, and so on) are properly adjusted.
- The image does not approach saturation in any of its red, green or blue color channels (that is, none of the channel values are greater or equal to 250).
- The image contains pixels that are uncolored, neutral, or gray and could serve as a reference for white balancing. To achieve this, the inspected part must have white areas, such as a sheet of paper inserted in the acquisition area.

Note: The WhiteBalance function is not listed in the Toolbox. To open its Property Sheet and configure it, type WhiteBalance() into a Spreadsheet cell.

## WhiteBalance Inputs

The WhiteBalance function has the following parameters listed in its Property Sheet.

Parameter | Description
--- | ---
Image | Specifies the color image reference. This argument must reference a valid Image data structure output of the function. By default, the cell referenced is A0, the cell containing the Image data structure returned by . Note: This parameter must reference a color image.
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 row offset, in image coordinates.
Y | The column offset, in image coordinates.
Theta | The angle of orientation, in the image coordinate system.
Region | Also known as the Region of Interest (ROI), this parameter specifies the region of the image that undergoes analysis for white-balancing. It creates a rectangular image region that can be transformed and rotated. With this parameter selected, by pressing the Maximize Region button on the property sheet's 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.
Tip: Use the Region parameter to select the area of the image that is considered white.
Note: In order for a pixel to be counted, it must be completely enclosed within the image region; partially enclosed pixels are not included. The Fixture and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.
White Balance Event | Performs white balancing when clicking the White Balance Event button. During the process, In-Sight acquires a new image and performs RGB color equalization based on the ROI specified with the Region parameter.
Show | Specifies the display mode for the function on top of the image.
Hide all = 0 (default) | All graphics will be hidden, except when the cell containing the WhiteBalance function is the active cell in the spreadsheet.
Input graphics only = 2 | The input image region will be displayed at all times.

### WhiteBalance Outputs

Parameter | Description
--- | ---
Returns | A ❒WhiteBalance structure, containing the white balancing settings of the tool's Property Sheet.

### WhiteBalance Vision Data Access functions

The WhiteBalance tool has no specific Vision Data Access functions. However, two additional white balance-specific functions are available:

- GetWhiteBalanceGain: Returns the current white balance gain value of the specified color channel.
- SetWhiteBalanceGain: Sets the specified white balance gain value of the specified color channel.