Change camera gain at runtime without stopping the pipeline

You have a GStreamer-style pipeline running a machine-vision camera, and you want to move gain or exposure from a launch-time constant to something your application controls while frames flow. The example you copied shows a child object on the source element being used to set features, but when you try the same call you get None and the program crashes on the next line. This walkthrough explains why that happens, in order of likelihood, and gives the working pattern: build the pipeline inside your own process, bring it up, then write the camera's GenICam nodes directly.

The cameras this applies to are ordinary GigE and USB3 area scan cameras with a GenICam feature layer — for example the LS-CMR-0053 — plus a vision controller to run the pipeline if the station has no dedicated PC.

Symptom: the camera child object is None

The failing line looks like this:

cam = source.get_child_by_name("cam")
# cam is None here

Everything after it — reading DeviceModelName, setting ExposureTime or Gain — cannot work, because you are calling methods on None. The None itself is the symptom; the causes are below, most likely first.

Cause 1: the pipeline runs in another process

If you start the pipeline with a shell script that runs a command-line launcher, the pipeline object lives in that process. Your Python code, running elsewhere, has no Gst.Pipeline to call get_by_name() on, and no amount of replaying the example inside your script changes that. This is the single most common misunderstanding: the example works because everything — pipeline construction, state change, feature access — happens in one process.

The fix is to move the launch string into your program:

pipe = Gst.parse_launch(
    "yoursrc name=src device-serial-number=25080729 ! fakesink"
)

You keep the exact pipeline description from your script; only the host process changes.

Cause 2: the child does not exist yet

A source element typically creates its camera handle and publishes the feature child only after it has opened the device — which normally happens during the transition to PLAYING. If you query the child immediately after parse_launch(), before any state change, None is the correct answer, not an error.

Set the state first, wait for the change to complete, then look for the child:

1. Build the pipeline with Gst.parse_launch(), giving the source element a name.
2. Call pipe.set_state(Gst.State.PLAYING) and wait for the state change to return.
3. Fetch the source element with pipe.get_by_name("src").
4. Fetch the camera child with get_child_by_name() using the name your element actually publishes.
5. Read a harmless property such as DeviceModelName to prove the handle is live before writing Gain.

Cause 3: wrong child or feature name

The child's name and the property names are not universal constants — they come from the element and from the camera's own GenICam XML. Before writing code, list what is really there:

• Inspect the source element on the command line to see every property and child it publishes.
• Cross-check the feature names against the camera's feature tree: Gain may be exposed as GainRaw, GainAbs or an enumeration, and the exposure node may be ExposureTimeRaw rather than ExposureTime.
• Confirm the exact serial-number property name too; a camera that never opens produces the same None downstream.

This is the same discipline our GenICam enumeration invalid value: check symbolics before you set article covers for enumerations, and it applies to gain just as much: read the node's minimum, maximum and increment before you write a value, because gain steps are often quantized and a rejected write tells you the camera disagreed with your number.

The write itself: safe while streaming

Once you hold a valid handle, changing gain or exposure does not require stopping the pipeline. On most cameras both nodes are writable during acquisition, and the new value applies to subsequent frames. Two practical caveats:

• A long current exposure can delay when the change lands; the camera applies many settings at the next frame or exposure boundary.
• Verify, don't assume. Re-read the value after writing, and if your camera tags frames with per-frame exposure and gain metadata, check when the change actually took effect — the approach in Per-frame exposure and gain: verifying camera metadata.

That rounding to the node's increment is what a raw write of 14.95698 often silently becomes; compute it yourself and the re-read will hold no surprises.

For the broader question of which settings can be touched mid-stream and how to sequence them so capture never stalls, see Apply camera settings while streaming without stalling capture. If you are driving the camera from a capture loop rather than a media pipeline, the get/set pattern in Camera parameter set and get in a capture loop safely is the closer match.

Worked example

Assume a 6 MP GigE camera on a vision controller, gain currently at the camera's minimum.

1. Parse the launch string with the source named "src".
2. set_state(PLAYING), wait for the return; the camera opens here.
3. src = pipe.get_by_name("src"); cam = src.get_child_by_name("cam").
4. Print DeviceModelName. If it prints, the handle is real; if cam is still None, run the inspection step above before going further.
5. Read the gain node's min, max and increment — suppose the increment is finer than your target and the target is in range.
6. Write the target gain, then read it back and expect the increment-rounded value, not your exact float.
7. Read exposure the same way before touching it; the timing logic is the subject of Setting camera exposure time through a GenICam API in Python.

Checks before you wire this into production

• One process owns the camera. Two applications both writing features will fight; the loser's writes vanish.
• Log every rejected write. A feature-access failure that is silently ignored is a station that runs with the wrong gain for a week; the debugging pattern in Camera feature access memory leak troubleshooting also shows why handles you keep across reconnects should be re-obtained, not cached.
• Fix auto-exposure and auto-gain off before writing manual values, or the camera's control loop will overwrite you within a frame or two — the interactions are covered in Automatic iris, exposure and gain control in machine vision.
• Confirm the value range at the node, not from a datasheet you remember; units are their own topic in Camera exposure and gain units: interpreting raw values.

A compact vision controller is enough to host the pipeline and your control code:

When the usual answer is wrong

• Your element publishes a property interface instead of a child object. Some sources expose features as GObject properties directly on the element, or through a per-camera sub-element created per device. The inspection step, not the example, decides which call you make.
• You need changes synchronized to a trigger. A plain write lands at the next opportunity, not at a chosen frame. If gain must change on a specific trigger cycle, check whether your camera supports per-configuration sets you can switch atomically instead.
• The camera is shared with another tool. If a vendor tool or a second pipeline holds the device, your handle may open read-only or not at all. Close everything else first; that is a device-access situation, not a code bug.

Checklist

• Pipeline built inside your process with parse_launch(), source element named.
• State changed to PLAYING and waited for before any feature lookup.
• Child or property names confirmed by inspecting the element and the camera's feature tree.
• Node min, max and increment read; target value clamped and increment-rounded.
• Auto-gain and auto-exposure disabled before manual writes.
• Value re-read after the write; per-frame metadata checked once in acceptance testing.

For help matching a specific camera and controller to this pattern, the area scan cameras finder covers the sensors, and you can ask our applications team about feature-access behavior on a particular model.