Programmatic camera white balance control: verify settings

A successful settings call does not prove that white balance changed. Your capture library may expose a property that the active backend ignores, or the camera may deliver raw data that receives its color correction later. For an inspection application, you need to identify which layer owns the adjustment and verify its effect on acquired frames.

This procedure covers feature discovery, automatic and manual operation, readback, and restart testing. It separates control availability from color tuning. For the broader adjustment sequence, use the guide to industrial camera image quality settings.

1. Identify which layer controls white balance

1. Record the device identifier, capture backend, driver version, pixel format, and processing path before changing settings.

White balance can belong to the camera, its driver, a device SDK, or host-side image processing. A generic capture property reaches the device only when the active backend implements that mapping. The same application can therefore behave differently after a backend change.

Start with the distinction below:

Raw Bayer acquisition needs particular attention. A camera can provide color-filtered sensor data without applying white balance before transmission. In that arrangement, changing a host processing stage may be the correct solution; searching for camera-side gains may not be.

The discovery and readback pattern resembles setting exposure through a GenICam API, but white balance can add channel selectors and processing-stage dependencies.

2. Discover controls instead of guessing property names

2. Enumerate controls through the interface actually used by your application. Record their names, types, valid values, and current access state.

For a V4L2 capture path, these diagnostic commands list devices and enumerate controls. The device path is an example; select the endpoint identified for your camera:

v4l2-ctl --list-devices
v4l2-ctl --device=/dev/video0 --list-ctrls-menus

Run diagnostics with acquisition stopped unless the driver documents concurrent access. Another process opening the device can introduce contention or change the state being investigated.

At API level, V4L2 control discovery can use VIDIOC_QUERY_EXT_CTRL, with VIDIOC_QUERYMENU for menu entries. Depending on the driver, relevant identifiers can include V4L2_CID_AUTO_WHITE_BALANCE, V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, V4L2_CID_RED_BALANCE, and V4L2_CID_BLUE_BALANCE. Their existence in the interface definition does not mean a particular device implements them.

For a GenICam interface, inspect available features such as BalanceWhiteAuto, BalanceRatioSelector, and BalanceRatio. Query supported entries and access permissions rather than assuming every feature exists.

Distinguish these outcomes:

• Absent: the current interface does not expose the control.
• Read-only: you can inspect the value but cannot currently change it.
• Inactive or unavailable: another mode or acquisition state may control access.
• Writable: the interface currently permits an attempted change.

A missing generic property is not proof that the camera lacks the underlying function.

3. Choose automatic, preset, or manual operation

3. Select the operating mode before writing channel gains. Then read the mode back through the same interface.

Automatic operation, illumination presets, and manual gains are different controls. A preset may select a predefined correction without running a continuous estimator. A one-shot automatic operation may calculate a correction and stop, while continuous operation can revise it as the scene changes.

Do not assume a menu index has a universal meaning. Enumerate the device's menu and use its documented entry or value. Likewise, only request Off, Once, or Continuous when the feature reports those entries.

If an automatic calculation is asynchronous, wait for its documented completion condition. An immediate readback may show an intermediate result. A fixed delay alone is a weak substitute for completion status and stable frames.

4. Apply manual values through the owning API

4. Disable automatic white balance, confirm the mode, and write each supported manual parameter within its reported range.

For V4L2, use the documented control-writing operation, such as VIDIOC_S_CTRL for an applicable scalar control, and retrieve the accepted value with VIDIOC_G_CTRL. Some controls use the extended-control interface. Preserve the returned error information rather than reducing every failure to a generic settings error.

For a selector-based feature interface, select a supported channel, write its ratio, and read that ratio back before selecting another channel. A ratio read without checking its selector can belong to a different channel than expected.

This is the transaction order, not a universal SDK syntax:

discover supported features and current access
select manual white-balance operation
read back the operating mode
select a supported color channel
query that channel's range and increment
write a valid correction value
read back the selected channel and accepted value
repeat for the remaining supported channels

A color-temperature setting is not interchangeable with independent channel gains. Its mapping depends on the device or processing implementation. Do not convert a desired gain ratio into a temperature value without a documented mapping.

If writes require stopped acquisition, apply them during initialization. The guide to manual settings before streaming explains the same ordering issue for exposure. If runtime updates are supported, coordinate them with acquisition as described in applying camera settings while streaming.

5. Verify readback and image response separately

5. Test both the control transaction and the resulting image. Neither test replaces the other.

Use a stationary neutral target with stable illumination. Keep exposure, analog gain, pixel format, and host processing fixed during the comparison. Avoid clipped highlights and signals close to the noise floor.

Measure the same target region before and after a change. Channel medians provide a simple diagnostic that is less sensitive to isolated bright pixels than a single-pixel reading:

Suppose the target medians are R = 80, G = 100, and B = 125 in arbitrary image units. The diagnostic ratios are:

• Red relative to green: 80 / 100 = 0.80.
• Blue relative to green: 125 / 100 = 1.25.
• Illustrative relative corrections: 100 / 80 = 1.25 for red and 100 / 125 = 0.80 for blue.

These calculations describe an idealized independent-channel correction. They are not universal API values. Device gain scales, minimum gains, color matrices, and nonlinear processing can change the required settings.

Capture a baseline batch of 30 frames, make a controlled change, wait for the documented settling behavior, and capture another batch. Compare both the median response and its variation. Account for buffered frames captured before the setting changed.

If the task later expands to several cameras, use multi-camera white balance consistency testing rather than treating matching numerical gains as matching color.

6. Test persistence at each restart boundary

6. Treat persistence as a measured property of the complete capture stack, not a promise implied by a successful write.

Settings may live in application memory, driver state, volatile device registers, or a documented nonvolatile user set. Closing a capture object does not necessarily reset them. Conversely, reopening the device may run initialization code that overwrites them.

Use this test matrix:

Perform disruptive tests on a maintenance setup, not during production acquisition. Keep the illumination and target unchanged so configuration changes are not confused with scene changes.

For repeatable operation, implement an explicit startup transaction: identify the device, select the processing path, apply the mode and values, read them back, then validate frames. A saved-settings workflow is useful only when the manufacturer documents what it stores and when it loads.

The same separation between saved values and active values appears in startup frame-rate verification. Avoid saving nonvolatile settings in every frame loop; follow the documented save procedure and storage limits.

7. Choose hardware without assuming control support

Use area scan cameras when evaluating a conventional machine-vision camera package. Consider board-level cameras when integration requires a camera module. Neither category, interface, nor color designation establishes white-balance API support.

The MV-CU020-90GC is a color GigE area scan camera. Treat its catalog identity as a starting point, then verify the required controls through its documented interface.

The LS-BCM-0047 is a color USB3 board camera module. Check the exact control path and output processing before selecting it for this workflow.

Use the camera finder to narrow the physical and interface requirements. Before ordering, confirm:

• The exact output format you will acquire.
• Where demosaicing and white balance occur.
• Whether automatic, preset, or manual operation is exposed.
• Whether writes are permitted during acquisition.
• Whether channel values can be read back independently.
• What survives reconnects and power cycles.
• Which SDK, driver, and backend versions support the intended operating system.

8. Make startup verification part of acceptance

7. Turn the successful bench sequence into a repeatable startup check, with a defined failure response.

Log the requested and accepted values, active mode, selected channels, device identity, and software versions. Retain a target image or channel statistics when startup validation fails. Do not silently substitute automatic operation when manual control is required for inspection.

A practical acceptance checklist is:

• Discovery reports the required controls and access permissions.
• Every write produces an interpretable success or failure result.
• Readback matches the accepted setting within the documented representation.
• Acquired frames respond to deliberate correction changes.
• Automatic behavior remains disabled when manual operation is required.
• Restart tests either preserve settings or trigger verified reapplication.
• Buffered startup frames cannot enter the inspection as validated images.

When the camera does not expose the needed control, the legitimate alternatives are a documented lower-level interface, a controlled host-processing stage, or different hardware. Repeatedly writing an unsupported capture property will not add the feature.

Start with the camera configurator, or send the required modes, processing path, and restart behavior through application support before choosing hardware.