Change camera ROI on the fly: what GenICam allows and what breaks

Your line runs continuously and the part size changes between batches, so you want to grow or shrink the camera's region of interest without stopping acquisition. The question behind the plan is narrow and answerable: do Width and Height accept writes while the sensor streams, and does everything downstream follow? GenICam answers per camera, not in general, and Camera Link adds a second register set to update on the grabber. This guide gives you the standard's position, a five-minute test that settles it for your camera, the grabber step that keeps Camera Link frames intact, and the arithmetic that shows what an unmatched grabber does to your image stream.

The short answer

A camera may change ROI on the fly when — and only when — its own GenICam feature description marks Width and Height writable while acquisition is active. The standard family defines the feature names and the access-mode mechanism; each camera decides how its registers behave. Read-write while streaming means the change is a pair of register writes and nothing more. Read-only while streaming means the write is refused, and the production answer is stop, change, restart. If a write fails even though the camera should allow it, the access state is the usual culprit; the refusal guides linked below cover the debugging.

On Camera Link there is a second condition that GenICam never sees. The frame grabber keeps its own image-size registers, and nothing updates them when the camera's AOI changes. Change the camera, then change the grabber, or the delivered frames stop making sense.

What GenICam specifies and what it leaves to the camera

The SFNC — the Standard Features Naming Convention inside the GenICam family — fixes the names and types of common camera features: Width, Height, OffsetX, OffsetY, and the acquisition controls around them. Runtime behavior is a separate matter. Every feature in a camera's GenICam XML description carries an access mode, such as read-only or read-write, and cameras may compute that mode from the acquisition state. Many report Width as locked while the sensor scans and writable while idle; others leave it writable throughout. Both are conforming.

The standard is soft even above the ROI registers. SFNC v2.7.1 classifies Acquisition Mode as Recommended rather than Mandatory, so a document at that level cannot force a camera to accept ROI writes mid-stream either. Your camera's feature description is the only authority.

TLParamsLocked, which comes up in every discussion of this question, belongs to the GenTL transport-layer standard, not to the camera's feature tree. While a stream is open, the producer locks the transport layer as a whole so a second client cannot reconfigure the device under you. It is a layer-level lock, not a per-register announcement. It does not tell you whether Width accepts a write mid-stream, and its presence tells you nothing about your ROI plans.

A five-minute test for your camera

Run the test under production conditions: same pixel format, same trigger mode, same packet size. Access modes can depend on the state the camera is in, so a bench test in free-run at 8-bit proves less than it seems to.

1. Start acquisition exactly as the production program will.
2. Open the feature browser that ships with your GenICam library and read the access state of Width and Height while streaming. Most libraries show writable or read-only per feature without requiring a write.
3. Attempt the change anyway: write the smaller value to Width and read it back. A refusal with an access error means the camera locks AOI during acquisition, and the answer is stop, change, restart. The same refusal appears in code as a not-writable error, which GenICam attribute not writable: set the feature mode first and GenICam node not writable: check camera access state help you debug.
4. If the write is accepted, time its effect: check the delivered buffer dimensions frame by frame and count how many transition frames your program must discard.
5. Read the offsets back after the change. Some cameras reset them to zero whenever Width or Height is written; Camera ROI offsets reset to zero: set width and height first shows the fix, and Set camera ROI in Python: size, offsets and persistence walks the write order in code.

Camera Link: the grabber must be resized with the camera

On Camera Link the camera change is half the job. The camera sends pixels and framing codes; the frame grabber assembles frames from its own image-size registers, which its configuration tool exposes as the acquisition window or maximum image size. Nothing updates those registers when the camera's AOI changes, so a live camera-side edit without a grabber-side edit breaks the stream in one of three ways: truncated images, images padded with black bands, or single images assembled from several camera frames.

Fix it with a fixed sequence rather than a guess. Send the camera the serial command for the new width and height, call the grabber library's own set-image-size function with the same values, then flush or re-allocate the buffers before the next frame arrives. Confirm the result by reading the dimensions reported with each delivered buffer, not by trusting the settings screens.

Some grabbers work the other way and help: they extract a smaller window from a full-frame stream on their own, leaving the camera untouched. That avoids camera-side risk but saves no bandwidth, because every pixel still crosses the cable.

The grabber side of the pairing looks like this:

For the pairing rules, see Camera Link camera and frame grabber compatibility: what must match; for how buffers get assembled, see Frame grabber image acquisition for Camera Link and CoaXPress.

Worked example: 2000 × 1500 ROI delivered into a grabber still sized for 4000 × 3000

Inputs, each with its source:

• Full-frame baseline: 4000 × 3000 at 30 fps, the printed output of the LS-CMR-0166 below and a typical 12 MP output class. The example camera itself is a Camera Link model in this class, because the mismatch only arises where a grabber assembles the frames.
• Your set point: Width 2000, Height 1500, a quarter of the pixels.
• Pixel format: 8-bit mono, so 1 byte per pixel. This is illustrative; the merge count below does not change with bytes per pixel, because it cancels in the ratio.
• Grabber: still configured for 4000 × 3000, the mismatch case.
• Assumption for the arithmetic: the camera transmits 30 ROI frames per second after the change.

The rule: a grabber delivers an image when it has collected its configured number of bytes, so the merge count is grabber bytes divided by ROI bytes.

The grabber waits for 12,000,000 bytes; the camera sends 3,000,000 at a time. Four camera frames fill one buffer, so you receive 7.5 images per second, and 9,000,000 of each image's 12,000,000 bytes — three quarters — is stale data from the previous three frames.

Decision and threshold: divide grabber bytes by ROI bytes. An exact integer gives clean-looking but merged images at 1/N of the camera rate. A non-integer gives torn rows, because the buffer boundary lands mid-frame. Set the grabber to 2000 × 1500 and every delivered image is exactly the ROI, one per camera frame, at the camera's true ROI rate.

GigE Vision, USB3 and CoaXPress: one writer, no grabber to resize

On GigE Vision, USB3 and CoaXPress there is no second register set. The host driver and SDK size their buffers from the frame geometry the camera announces, so a supported mid-run change behaves simply: write Width and Height, discard the transition frames, let the SDK handle the buffers. The traps sit in the surrounding machinery, not in the ROI write:

• Linked attributes: pixel format, binning and packet size interact with frame rate and bandwidth. A format change alone can halve the stream, as Changing pixel format halves your frame rate: check linked attributes explains.
• Packet size locks once streaming starts on GigE, so set it before you start and leave it: Set GigE camera packet size before starting acquisition.
• Buffer handling around the change is where quiet failures live: Requeue an already queued camera buffer: why it breaks acquisition.
• Exposure is a separate register class and is usually writable mid-run; the timing traps are in Reduce exposure time mid-acquisition without an overtrigger error.

The five-minute test applies to any camera in the area scan cameras range, including these two:

When the usual answer is wrong

Four assumptions cause most of the trouble here.

• Reading TLParamsLocked as the oracle. It locks the transport layer, not your registers; the access modes in the camera's feature description answer the question.
• Assuming the standard forbids live changes. GenICam defers to each camera, and many accept Width and Height writes mid-stream, which is why a test, not an assumption, decides.
• Assuming the frame rate scales with the pixels you remove. Row-sequential CMOS readout gains roughly in proportion to the rows removed; CCD does not scale the same way, and link bandwidth caps the gain. The breakdown is in Camera ROI and frame rate: width cuts help CMOS, not CCD.
• Assuming the Camera Link grabber follows on its own. It has no path to learn the camera's new geometry; the three-step sequence above is on you every time the ROI moves.

Checklist before you put live ROI into production

• Confirm Width and Height write while streaming, at the production pixel format and trigger mode.
• Count the transition frames after a write and build the discard window into the program.
• Dimension-check every delivered buffer so a mismatch faults visibly, not silently.
• On Camera Link, script camera serial command, grabber resize and buffer flush as one sequence, in that order.
• Check the frame rate at the new size against your cycle time, using the camera's own ROI numbers rather than scaled full-frame values.
• Enforce the geometry rule in code: offsets plus sizes within the sensor's active area, offsets written after sizes.
• Test growth as well as shrinkage; growing is where the offset rule bites.

Cameras and grabbers that behave

Three behaviors separate parts that behave from parts that fight you. On the camera: AOI registers that stay writable while acquiring, confirmed with the five-minute test before you commit a model to the line. On the grabber: programmable image size and camera serial control from the SDK, as in the frame grabbers range. On the host: an SDK that re-announces buffers when geometry changes instead of pinning the first size it saw.

To size the whole chain together, the camera configurator walks camera, lens, light and grabber in order, and the systems topic page gathers the rest of the acquisition guides. For a straight answer on a specific camera and grabber pairing, contact the applications team.