# WhiteBalance

Available for color In-Sight 3800 series vision systems only, the WhiteBalance function Functions are tools that are available in Spreadsheet for processing and analyzing acquisitions or other results. You can add functions to your Spreadsheet job to create tool chains and produce results for specific applications. is used to equalize the RGB colors of the acquired image for each subsequent acquisition Acquisition is the process or result of the vision system acquiring a new image. 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 Spreadsheet Toolbox. To open the WhiteBalance Property Sheet and configure it, type WhiteBalance() into a Spreadsheet cell.
Inputs

The WhiteBalance function has the following syntax:

WhiteBalance(Image, X, Y, Theta, X, Y, Width, Height, Angle, White Balance White balance refers to the color temperature at which white objects on the image actually look white. Event, Show)

See the table for a description of the available parameters.

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 A fixture is a coordinate location on the image that keeps the tool in the place determined by the 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 A point cloud is a 3D structure that consists of the data points collected by a 3D vision system during acquisition. as a Fixture, convert the real world units to pixel values using the TransWorldToPixel function. Note: Angles must be multiplied by -1, due to image space differences. 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.

Outputs

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

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.
- SetWhiteBalanceGains: Sets the specified white balance gain value of the specified color channel.