The camera tool on your bench shows a fast, live picture, but the viewer started from your launch file runs about a second behind the scene. The viewer is almost never the fault. A user set loaded at startup — a startup_user_set such as UserSet2 — re-applies the exposure and frame rate saved inside it, and those saved values can override what your driver node writes. This article shows how to name the saved value that wins, read it back after startup, and fix the order so the camera runs at your configured rate from the first frame. It is written for anyone wiring a GigE or USB3 area scan camera into a driver node whose parameters come from a launch file or YAML.
The symptom: fast in the tool, a second behind in the viewer
The pattern is specific: same camera, same cable, same viewer. Loading CurrentSetting gives fast video; loading a saved set such as UserSet2 gives a picture roughly one second old. Switch the startup_user_set parameter in your launch file back to CurrentSetting and restart the node. If the lag disappears, the set carries a value your driver does not write again after startup — almost always the exposure time, sometimes the saved frame rate or a saved trigger mode.
The viewer only displays the newest frame it has received, so it cannot run faster than the camera delivers. At 1 fps a fresh image lands every 1,000 ms and the picture trails the scene by about a second, which is exactly the delay you are seeing. Fast in the tool and slow in the node means the tool session and the startup load are running different settings.
What a startup user set re-applies
A user set is a snapshot of every writable camera feature taken when it was saved: exposure time, gain, pixel format, trigger configuration and acquisition frame rate travel together. When the driver opens the camera and the set loads, every feature your program does not write again keeps its saved value. That is the override: your launch file asks for frame_rate: 100, the set was saved with other values, and the last write to each feature wins.
Drivers differ in when they write: some put their parameters in before the load, some after, and some write only the subset they manage. Do not assume the order — the readback below settles it in a minute. The durable fixes do not rely on it at all: re-apply your values after the load, or save your values into the set. The same silent write-back, with one node instead of a whole set, is what happens when the frame rate drops to half after a node changes settings.
Cause one: saved exposure caps the frame rate
A frame cannot complete before its exposure ends plus the sensor's readout time, so exposure sets a hard ceiling on rate no matter what the driver requests:
Most sets are saved after hand-tuning or auto exposure in a dim room, so they carry a long ExposureTime. Requesting 100 fps against a saved exposure of 999 ms does not produce an error you will notice: the camera simply cannot deliver the rate, and the write clamps to what is achievable.
Worked example, with the arithmetic:
- Saved ExposureTime: 999,000 µs = 0.999 s; readout about 10 ms for a mid-size sensor (an estimate).
- fps_max = 1 / (0.999 s + 0.010 s) = 1 / 1.009 s ≈ 0.99 fps.
- The driver requests frame_rate: 100, so delivered ≈ min(100, 0.99, interface) ≈ 1 fps. A new image lands about every 1.0 s — the one-second lag, reproduced from one saved number.
- With ExposureTime set to 10,000 µs instead: fps_max = 1 / (0.010 s + 0.010 s) = 50 fps, and per-frame lag falls to about 20 ms.
The exposure term dominates whenever it is tens of times the readout, so for slow exposures fps_max ≈ 1 / t_exposure is close enough for a first check.
Cause two: the set's own frame rate or trigger mode
If the readback later shows a short exposure but the video still crawls, the next two suspects live in the same set. First, a saved AcquisitionFrameRate below your frame_rate parameter: a driver that writes its parameters before the load lets the set's saved rate land last, and the camera runs at the saved value. A set saved at 5 fps delivers 5 fps even with 100 in your YAML.
Second, a saved trigger configuration. A set saved with the trigger mode on leaves the camera waiting for triggers after startup, so free-running frames stop entirely — the viewer freezes rather than lags.
Both causes fail the same readback test below and take the same two fixes.
Read the values back and name the winning value
Start the node with the set loaded, exactly as it fails, then read four values before changing anything:
- ExposureTime — a reading near 1,000,000 µs explains a one-second lag on its own. A small difference between the value you set and the reported one is normal firmware behavior, covered in why reported exposure differs from the set exposure; a factor of a hundred is not.
- AcquisitionFrameRate — compare it with your frame_rate parameter. A mismatch means the set's write landed after the driver's.
- The achievable-rate readback, where the camera provides one (often exposed as ResultingFrameRate): it already accounts for the current exposure and shows the ceiling before you debug anything else.
- Trigger mode — on means the set re-applied trigger settings too, and the stream stalls for a reason other than rate.
If exposure and frame rate both read your requested values but delivery is still slow, the set is innocent and the interface checks below are next. One readback pass names the value that wins; guessing at it costs an afternoon.
Fix one: load the set, then write exposure and rate after it
Keep the startup_user_set parameter and add a re-apply step in the same startup routine that opens the camera:
- Open the camera and let the user set load.
- Write ExposureTime first, because it moves the ceiling the frame-rate write will be clamped to.
- Write AcquisitionFrameRate, with the frame-rate enable switch on where the camera provides one.
- Read both values back, and read the achievable rate; confirm it is at or above your requested rate.
- Only then start acquisition, so no frames are produced at the old settings.
For the calls and units — ExposureTime in microseconds, AcquisitionFrameRate in hertz — the guide on setting camera exposure time through a GenICam API in Python shows the pattern end to end.
Fix two: save your working values into the set
Set the camera up once on the bench — exposure, frame rate, pixel format, trigger off, gain where you want it — and save that state into the same set your launch file references. Save it from the camera tool you already use, or with the user-set save call in a setup script. From then on the set and the driver agree from the first frame, startup is the same on every machine you deploy, and anyone who loads the set in a tool reproduces your configuration exactly.
Two details decide whether this works: save over the set that startup_user_set actually names, and confirm the write with a readback after the next boot — verifying saved settings and readback at startup is the routine for that. The guide on saving camera parameters as a user set that loads on startup covers the save path, and keeping camera settings across power cycles covers why a plain tool session is not enough.
When the set is not the cause: the interface ceiling
If the readback shows your requested exposure and rate but delivery still lags, check the link itself. A GigE connection carries roughly 110 MB/s of usable image payload; a 6 MP mono8 frame is about 6.3 MB, so the ceiling sits near 17 fps:
110,000,000 B/s ÷ 6,300,000 B per frame ≈ 17.5 fps
Asking frame_rate: 100 of that link clamps to the ceiling no matter what the user set holds. The fixes are a smaller region of interest, a lower requested rate, or a faster interface. The same sensor class on USB3.0 has roughly 380-440 MB/s of payload headroom — enough for about 60-70 full-resolution fps — so moving the interface line moves the ceiling more cheaply than changing optics. The pair below is that comparison: a 6 MP GigE model and its USB3.0 twin, both C-mount.
- Sensor format
- 1/1.8"
- Lens mount
- C-mount
- Sensor format
- 1/1.8"
- Lens mount
- C-mount
Two more lags look identical from the viewer side. One is the one-frame delay from setting exposure every frame, a driver-side mechanism with the same symptom, walked through in the one-frame delay from setting exposure every frame. The second is a subscriber queue holding stale frames after a perfectly fast camera: measure the rate as reading the frame rate reliably from OpenCV shows rather than trusting a viewer, and on Linux rule out the USB3 kernel memory fix for low frame rate and latency before blaming the camera.
Checks before you call it fixed
Work through this list and the cause is closed, not guessed:
- ExposureTime read back after startup equals your configured value, not the tool session where the set was saved.
- AcquisitionFrameRate read back equals frame_rate from your launch file.
- The achievable-rate readback sits at or above your requested rate, so nothing clamps.
- Trigger mode reads off, and the stream runs without any trigger.
- Measured time between received frames matches 1 / delivered rate — about 20 ms at 50 fps, about 1,000 ms at 1 fps.
- A hand waved in front of the lens shows no visible trail at your configured rate.
If you are sizing a camera rather than repairing one, filter the GigE and USB3 area scan cameras by interface and resolution, narrow further in the camera finder, or step through the camera configurator from sensor to cable. More startup-order repairs — saved settings, readbacks, and the values that quietly win — are collected on the systems topic page, and we can read back the values on a specific model with you through the contact page.
Questions
Does a loaded user set also override exposure, gain and trigger mode?
Yes. A user set is a snapshot of every writable camera feature, not just the rate: exposure time, gain, white balance, pixel format, trigger configuration and acquisition frame rate all travel with it. Anything your program does not write again after the set loads stays at the saved value, so a set saved during a dim-room tuning session can quietly change an inspection that used to pass.
How do I check the frame rate the camera will actually deliver?
Read it from the camera after every setting is applied. Many cameras expose a resulting or achievable frame-rate readback next to the rate node; its value already accounts for the current exposure and the interface in use. Without one, compute 1 divided by exposure plus readout, then take the lower of that, your requested rate and the link's payload ceiling.
Can I keep my startup user set and still get the full frame rate?
Yes, and it is the cleaner long-term answer. Configure the camera once — exposure, rate, pixel format, trigger off — and save those values into the same set your launch file references at startup. Set and driver then agree from the first frame, startup behaves the same on every unit you deploy, and a colleague loading the set in a camera tool reproduces your configuration exactly.
Why does a one-second lag point to roughly one fps?
A viewer shows the newest frame it has received, so the perceived delay tracks the time between arrivals plus transport. At 1 fps images land 1,000 ms apart and the picture trails the scene by close to a second; at 10 fps the trail is about 100 ms, which still reads as live video. The interval between arrivals is what your eye judges, not the rate printed anywhere.
Is CurrentSetting a safe permanent startup choice?
It works, but it is not deterministic: the camera loads whatever values were live in its last session, so behavior can change after a power cycle, a tool session or a swap with another unit. Use it to prove the set is the cause, then either re-apply your values after the load or save them into the user set your startup_user_set parameter names.

