Lock auto white balance to a fixed value for repeatable color

Auto white balance gives you correct-looking color on commissioning day and drifting color by Friday. The camera re-neutralizes whatever is in front of it, so moving parts, a change from bare boards to packed boards, or an operator's glove in the corner of the field all pull the balance. Color matching, print inspection and any threshold set on hue need the opposite behavior: one balance, fixed, identical on every run and after every restart. This guide gives the sequence that works on depth cameras with an integrated color module and on GenICam color cameras — converge the auto controller on your real lighting, capture the converged value from the one channel that reports it, write it back as a manual value, and make it survive reconnection. It also explains the trap that stalls most of these projects: reading the white-balance option after switching auto off and getting a number that was never the converged one.

How auto balance works, and why it will not hold a standard

White balance is a set of gains: the red and blue channels are scaled against green so that a neutral gray under the room's light renders neutral. In auto mode, a controller in the image processor re-estimates the scene's illumination every frame, mostly from the average image. Change the scene and the estimate moves, so the gains move and every color value you measure moves with them.

Under fixed industrial lighting the converged gains have no reason to move. An LED fixture at a fixed drive current emits a constant spectrum, so a lock costs nothing on a stable line. Two things still decide what neutral means here: the fixture itself — the white LED color temperature you specify sets which gains a neutral balance needs — and which pixels feed the controller's average, which auto exposure and auto gain on color cameras covers in detail.

The trap: the manual register never sees the auto value

On the integrated color modules that depth cameras carry, auto and manual white balance are separate mechanisms: a controller running in the image processor, and a register holding a manually written value. Enabling auto starts the controller. The register keeps whatever was last written to it, usually the factory default. Disable auto and the controller stops; read the register and it hands back the number you started with, so the image jumps straight back to the old balance.

Every other channel fails the same way. The white-balance key in frame metadata exists on some modules and is absent on others; query the sensor for support and treat a false answer as an absent channel, not as zero. A settings file exported before and after an auto run is identical, because the export reads the same stale register. So the rule is simple: never read the value back. Capture it while auto runs, then write it. Exposure behaves the same way — reading the exposure time under auto exposure goes through frame metadata for exactly this reason — and option-ordering errors on these modules match the pattern in depth camera auto-exposure option errors.

What you need

• The depth camera with its color module, or a color area scan camera, mounted as it will run.
• The vendor SDK or viewer, with two controls reachable on the color sensor object: the auto-white-balance switch and the manual white-balance value — kelvin on UVC-class modules, per-channel gain ratios on GenICam cameras.
• Production lighting at production drive level, on for 10–15 minutes so the fixture reaches thermal steady state.
• A matte gray card or diffuse white reference in the field.
• A short script that streams continuously and reads mean channel values in the card region.
• Two places to persist the number: the device's saved settings or user set, and your own startup configuration.

The sequence: converge, capture, commit, persist

Four values your script holds while it works:

wb_auto    = True   # bool:  auto white balance switch, set on the color sensor
wb_value   = 0      # int:   manual white balance, kelvin on UVC-class modules
settle_s   = 10     # int:   seconds of live streaming before capture
ratio_gate = 0.02   # float: acceptance band on gray-card R/G and B/G drift

The names are illustrative; your SDK names the switch, the value and the metadata key its own way.

1. Stabilize the light. Same fixtures, same drive current, warmed up. Never balance under bench light and run under production light.
2. Place the reference. Gray card at production distance and angle, with a solid region of at least 100 × 100 pixels in view and out of shadow.
3. Converge. Enable auto white balance and stream continuously for 10 seconds — about 300 frames at 30 fps, card alone in view.
4. Capture the converged value. Read the white balance from the newest color frame's metadata, after confirming the sensor reports that key. If the key is unsupported, go to the sweep method in the next section; nothing on the device will hand you the number.
5. Commit it. Write the captured value as the manual white balance. On these modules the manual write clears the auto switch in the same operation, and that is what freezes the color. If your module leaves auto running after a manual write, flip the order: switch auto off first, then write the value.
6. Check the transfer. Grab a frame and measure the card. R/G and B/G within 1% of the last auto frame means the value arrived; a jump means you wrote to the wrong object or mixed up units.
7. Persist twice. Save the device's settings or user set now — the file carries your written value, so restoring it reproduces the lock — and record the number in your own startup configuration. A reconnect can reset every option to its default on this class of device, so the startup write is the layer you control.
8. Verify over time. Run 10 minutes of production with parts moving through and measure the card again. The ratios must stay within ±0.02 of the committed reference; the worked example below shows the arithmetic.

No metadata channel: sweep the value with a gray card

When the metadata key is unsupported, no register on the device reports the auto-converged number, so compute it yourself. A balanced image renders the neutral card neutral: equal red, green and blue means. Sweep the manual value across the module's span — UVC-class modules typically cover 2800–6500 K, and your device reports its own minimum and maximum — capture the card at each step and score each capture:

Commit the lowest-scoring value, then refine ±100 K on either side. A dozen captures, a few minutes of script. Under a 4000 K LED panel, steps of 400 K give:

The 3600 K row scores |0.94 − 1| + |1.06 − 1| = 0.12. The 4000 K row scores 0.02. Refining at 3900 K and 4100 K, the 4100 K capture reads R/G 1.00 and B/G 0.99 for a score of 0.01 — commit 4100 K. The direction in the table is the physics: a set value below the light's true temperature makes the camera add blue, so B/G runs high; above it, R/G runs high.

Worked example: lock a label line at 4100 K

Label inspection over a moving web, 4000 K LED bar lights at fixed current, gray card at the field edge with 300 × 300 pixels visible. This camera publishes no white-balance metadata, so the sweep above commits 4100 K. The manual write clears auto, and the number goes into both the saved device settings and the startup config.

Reference frame, card-region channel means: R = 118, G = 120, B = 119. R/G = 118/120 = 0.983. B/G = 119/120 = 0.992. Score = |0.983 − 1| + |0.992 − 1| = 0.017 + 0.008 = 0.025.

Ten minutes later, labels having run the whole time: R = 119, G = 120, B = 119. R/G = 0.992, B/G = 0.992, score 0.016. The ratio moved 0.983 → 0.992, that is +0.009 against the 1.0 target, inside the ±0.02 gate: the lock holds. Had R/G read 1.03, the +0.03 would fail the gate, and the checks run in order: fixture drive current, card surface condition, then exposure changes dragging the balance. A ±0.02 gate is a practical default for golden-sample color comparison; tighten to ±0.01 for pharmaceutical and print label color, widen to ±0.05 where color only sets contrast.

Any color camera with a manual balance runs this sequence. For a single-label station, a 2.5 MP color GigE model is the right scale:

Where the lock lives on each camera family

Depth cameras with an integrated color module

The color side is a UVC-class sensor with its own object: an auto-white-balance switch, a manual value in kelvin, and on many modules a per-frame metadata key carrying the live value while auto runs. Set the options on the color sensor object, not on the device or the depth object — writes aimed at the wrong object fail quietly. Persistence comes from the settings export plus the startup write from your own config, because a reconnect resets options on this class of device. Where auto exposure runs on the same module, set the master option first and keep that ordering fixed.

GenICam color cameras

A color area camera exposes balance as its standard feature set: an auto-white-balance enable flag, per-channel balance ratios with red and blue referenced to green (unitless gains), and on many cameras a one-shot balance command that computes the ratios from the current image. Switch auto off, write the ratios, save them to a user set in camera flash — the same user-set flash storage that holds calibration data — and the camera comes back from a power cycle with the lock intact. Ratios are the kelvin value's GenICam cousin: same lock, different units. Under a white LED fixture the red ratio usually runs higher than the blue one, because white LED spectra are rich in blue and comparatively weak at the red end.

Three camera families that take this lock directly:

Common mistakes

• Reading after switching auto off. The register returns the last manual write — often the factory default — and the project stalls on that one read.
• Trusting an export made while auto ran. The file echoes the same stale register. Export only after the manual write.
• Balancing under the wrong light. A value locked under bench lighting is wrong under production fixtures. Balance at production drive level, distance and angle.
• Measuring drift on parts. Product color variation is scene content, not balance drift. Measure the gray card.
• Writing to the wrong sensor object. On depth cameras the color side is its own object; the white-balance controls live there.
• Writing the value before disabling auto on a camera where the two controls are independent — the controller overwrites your number within a frame or two, the same ordering trap as gain settings that do not apply until auto gain is off.

When a locked value is the wrong tool

• The lighting itself changes. Daylight through a window, tunable-white fixtures on a dimmer: no fixed value tracks a moving illuminant. Enclose the station, fix the fixtures, or re-check the card at every shift start.
• You need measured color, not matched color. Kelvin balance neutralizes a scene average; it is not a colorimetric calibration. Measured color values need a spectrally characterized light and a certified reference chart in the field of view.
• Color carries no information. Then a mono camera ends the problem outright — no balance to drift, and more sensitivity in the same exposure.
• Several cameras feed one line. Lock each one, then test white-balance consistency across the set before trusting any cross-camera comparison.
• The fixture spectrum is the defect. A light with a missing band cannot be balanced into shape by ISP gains; a light-balancing filter or software white balance fixes the light itself.

Lock it in

Commit the value once, persist it in two places, and gate production on the gray-card ratios. To choose the camera itself, the camera finder filters by interface, resolution and shutter, and the camera configurator builds the matched camera, lens and light set; depth-guided cells start from the 3D sensors line. More depth-camera field fixes sit on the 3D vision topic page. If a station still will not hold color after this sequence, contact the applications team with the camera model, the lighting, and two gray-card captures ten minutes apart.