Runtime camera parameter control: exposure and white balance live

You tune exposure and white balance from code, the first change applies, and every change after that is ignored — or the stream dies mid-run. The mechanism behind it is the same on GigE Vision and USB3 Vision cameras and on smart cameras: a control change is a complete message or a register write, and it fights any auto mode that is still running. This guide shows you how to send parameter changes while frames flow, how to compute the exposure your line speed allows, how to lock white balance to a measured value, and how to prove each change with readback and frame metadata.

Why do exposure and white balance changes only stick once?

Because the change that reached the camera was a command built from defaults rather than from the camera's current state: every field you leave empty is applied as its default, so the second message undoes the first change or kills the stream.

Two control designs exist, and the bug looks identical on both. Command-message stacks — most smart cameras and embedded camera nodes work this way — treat every control message as a complete instruction: build a fresh message and fill in only white balance, and the message carries the default exposure, often zero, alongside it. The camera applies what it receives, so the earlier change is undone or the sensor trips mid-stream. Register-feature stacks — the GenICam model behind GigE Vision and USB3 Vision cameras — remember each write, so one white balance write cannot erase your exposure. There the culprit is an auto mode: continuous auto exposure or auto white balance overwrites your manual values within a frame or two.

The discipline that fixes both is identical: read the current state, change one field, send the complete result, then read back.

Which camera settings can you change while the stream is running?

Exposure time, gain, white balance mode and balance ratios are per-frame settings that take effect from the next frame boundary, while resolution, pixel format and ROI are readout geometry that nearly every camera makes you stop acquisition to change.

Exposure, gain and white balance are applied per frame in the sensor and the image processor, so the camera swaps them in at a frame boundary without dropping the stream. Resolution, pixel format and ROI change the readout geometry itself, so the driver refuses the write or corrupts frames until you stop acquisition, apply, and restart. For what each setting does to the image, see exposure, gain and balance settings on industrial cameras; for gain on its own, changing camera gain at runtime without stopping the pipeline walks a live gain sweep.

Area scan cameras and smart cameras in the shop span the same interfaces as this table — GigE, USB3 and Fast Ethernet — so one of the cards below matches the stream you are debugging.

How do you send a change while frames are flowing?

Read the camera's current values first, switch the conflicting auto modes off, write your new values, then read every value back — the sequence below keeps the stream alive and proves each change took.

1. Start acquisition the normal way. The control path — a GenICam session on GigE or USB3, or the smart camera's control input queue — stays open beside the image stream.
2. Read the current state into typed variables of your own: exposure in µs, gain in dB, white balance mode, and the balance ratio per channel. This snapshot is what makes every later message complete.
3. Disable what would overwrite you: auto exposure and auto gain to Off, white balance to Off, before any manual value.
4. Write the new exposure and gain.
5. Write white balance as per-channel ratios: select the red channel, write its ratio, select blue, write its ratio. Green is usually the reference channel and stays fixed.
6. Apply one change at a time and give the camera one frame boundary to absorb it before the next.
7. Read every value back, compare against what you sent, then confirm in frame metadata — the checks are in the verification section below.

# Illustrative pseudocode. Quoted names are GenICam standard feature names;
# camera.read() / camera.write() stand in for your SDK's calls.
exposure_us: float = camera.read("ExposureTime")   # current state, e.g. 5000.0 µs
camera.write("ExposureAuto", "Off")                # stop auto from overwriting
camera.write("ExposureTime", 500.0)                # new value in µs
applied: float = camera.read("ExposureTime")       # readback
assert abs(applied - 500.0) <= 1.0                 # test: the register really moved

On a register-stack camera the whole sequence runs over the normal GenICam session: setting exposure time through a GenICam API in Python shows the read-write-read pattern against a live camera, and applying camera settings while streaming without stalling capture covers the queueing side so the operator interface never blocks the pipeline. Where the stack sits at driver level, runtime camera exposure control without reloading the driver is the equivalent pattern.

A 2.5 MP colour GigE camera with a global shutter and a C-mount is the smallest build that runs this exact sequence end to end.

How much exposure time does your line speed allow?

For a 200 mm field of view on a 5 MP sensor with parts moving at 150 mm/s, motion blur stays under one pixel only while exposure is at most 545 µs, so 500 µs is the value to write.

Compute the ceiling before you touch the camera. A 5 MP sensor resolves 2448 pixels across the travel direction, so a 200 mm field of view puts 200 / 2448 = 0.0817 mm of part under each pixel. At 150 mm/s the part covers that distance in 0.0817 / 150 = 0.000545 s, and that is the longest exposure that keeps motion blur within one pixel.

Write 500 µs and keep about 8% margin. Dropping a running line from 1000 µs to 500 µs costs one stop of light; buy it back with gain — 20 × log10(1000 / 500) = 20 × log10(2) = 6.0 dB — or with the iris, where one stop from f/2.8 to f/2.0 doubles the photons because each f-number step is a factor of √2 ≈ 1.41 in aperture diameter.

The ceiling moves with speed and footprint. Double the belt to 300 mm/s and it halves: 0.0817 / 300 = 273 µs. Widen the field to 400 mm at 150 mm/s and it rises: 400 / 2448 = 0.163 mm per pixel, so 0.163 / 150 = 1.09 ms.

How do you lock white balance to a fixed value?

Run one-shot auto white balance on a grey patch under the production light, then switch white balance to Off so the measured ratios become the fixed state — that locks colour at a known value instead of letting continuous auto drift frame to frame.

Auto white balance has three states — Off, Once and Continuous — and only the first two help a fixed set-up. Continuous re-balances every frame, which is exactly what hides real colour drift while a lamp ages or a filter smudges. The lock procedure takes one grey patch and about a minute:

1. Place a matte grey or white patch where the part sits, under the production light at the production distance.
2. Run white balance Once; the camera measures and writes the channel ratios.
3. Switch white balance to Off so those ratios become the standing state.
4. Read each ratio back per channel and store the set under the light's name.
5. Remove the patch and check a real part: greys neutral, colours where the inspection expects them.

GenICam cameras expose white balance as per-channel ratios, not Kelvin. Smart camera and embedded stacks often take a Kelvin target instead — halogen sits near 3000 K, cool-white LED and daylight near 6500 K — and convert it internally, so lock the Kelvin value through that input the same way. For the same Once-then-Off sequence written up for another camera family, see white balance configuration steps for one camera family.

How do you verify the change actually took effect?

Two checks close the loop: read each feature back over the control channel within a tight tolerance, and confirm the exposure time stamped in the metadata of frames you actually receive — the register can say one thing while the frames prove another.

Readback catches a refused write; metadata catches a write the camera accepted but did not apply. Run both:

• Read each feature back and compare against what you sent: ±1 µs on exposure, ±0.05 dB on gain and ±0.01 on a balance ratio are tight enough to catch a stale register.
• Check the exposure time stamped into frame metadata for the next ten frames. Reading exposure time from frame metadata under auto exposure shows where the value lives, and per-frame exposure and gain: verifying camera metadata extends the check to gain.
• Watch a histogram on a fixed grey target. Halve the exposure with gain untouched and the mean grey level halves, 120 to 60. Halve the exposure and add 6 dB and the histogram should stay put, because 0.5 × 10^(6/20) = 0.5 × 2.0 = 1.0.

What breaks when you change settings live?

The three failures to expect are an auto mode overwriting your write within a frame or two, a longer exposure silently cutting the frame rate once it exceeds the current frame period, and a partial command message resetting values you meant to keep.

Each failure has a fast test:

• Auto mode still engaged. The write applies for one frame, then auto overwrites it. Test: read the value back twice, one second apart; if the second read differs from what you wrote, an auto mode is alive.
• Exposure now exceeds the frame period. At a 100 fps target the frame period is 10 ms; write 12 ms and the camera cannot sustain 100 fps, because the ceiling becomes 1000 / 12 = 83 fps. Why a GigE camera frame rate drops at longer exposure times measures this effect; test it on your side from frame timestamps.
• A partial command message. The second change resets the first, as in the first section; rebuild every message from the snapshot of current state.
• A rejected write on a colour stream usually means a mode conflict; colour stream exposure control: diagnose rejected settings lists the checks in order.

When should parameters stay fixed instead of changing live?

In production, tune at runtime and then freeze: write the proven values at startup in a fixed order before streaming begins, because a camera whose exposure and colour wander frame to frame turns every downstream threshold into a moving target.

Runtime control earns its keep in three places: commissioning, reaction to a light change, and closed-loop regulation such as holding brightness while the line slows. Everywhere else, freeze the values. Store the proven exposure, gain and ratios in configuration and apply them at startup in a fixed order before streaming begins — setting manual exposure before streaming: initialization order shows why the order matters — then verify with a readback against the stored numbers, the check camera startup frame rate: verify saved settings and readback builds. Multi-camera lines add one rule: test multi-camera white balance consistency before trusting any colour match across stations. The systems topic page indexes the neighbouring integration guides.

Start at the camera step in the configurator above, or shortlist hardware in the camera finder. Free expert support comes with every order, so if a control sequence misbehaves on a specific model, describe the readback results through the contact page and we will help you pin the cause.