You call arv_camera_set_region() with a width, a height and a position, then read the region back with arv_camera_get_region() — and the offsets come back 0, 0 on every attempt. A second symptom often rides along: the new width and height take effect, but the image arrives sheared sideways, each row slid a little further than the row above. This guide is for anyone writing cropped-buffer acquisition against a GenICam camera, in C, in Python or through arv-viewer. You will be able to prove, from the camera's own feature list, whether ROI position control exists, why the shear happens, and which cropping strategy to commit to when the answer is no.
The symptom: the camera keeps offsets at zero
Set x and y to anything other than zero, read the region back, and you get 0, 0. Repeat the test in a generic viewer such as arv-viewer, with your code out of the picture. If the viewer ignores region position too, the cause sits in the camera, not in your application.
The reason is structural. Under GenICam, a setting exists only when the camera's XML feature description defines a node for it. Host software — Aravis, a vendor SDK, any viewer — can only read and write nodes the device itself describes. A readback of 0, 0 is the camera reporting the only region position it has.
First test: dump the feature list
Run:
arv-tool-0.6 features | grep -i offset
Empty output is your answer, and arv-tool-0.6 genicam confirms it by printing the camera's raw XML. On one camera that shows this behavior, the ImageFormat category lists exactly five features: SensorWidth, SensorHeight, Width, Height and PixelFormat. There is no OffsetX and no OffsetY node anywhere in the tree.
That is the decision point. A camera without offset nodes cannot position a region of interest, and no library, SDK or cabling changes that. Its entire cropping capability is Width and Height. If the grep does return OffsetX and OffsetY, skip to the last section — the nodes exist and something in your write order is defeating them.
If you work in Python rather than C, the same check needs no extra tooling: browsing the feature tree with generic GenICam code lists the nodes any camera actually carries.
Why the image shears: increments and stride
Width and Height are integer nodes, and integer nodes carry a minimum, a maximum and an increment — the legal step between values, commonly 1, 4, 8 or 16 pixels. Request a width that is not on the step and the camera rounds it, usually upward, or refuses it. Your code keeps striding the buffer at the number you asked for. Every row then begins a few pixels early or late, and the error accumulates line by line into a diagonal shear.
Row padding produces the same symptom at a perfectly legal width: some cameras pad each row in the payload, so the bytes per row exceed width × bytes per pixel.
The fix has three parts. Round your request to the node's increment before writing it. Read Width and Height back after setting them, and use the returned values everywhere downstream. Build the display stride from the image dimensions the buffer reports, never from the request. Bytes per pixel follows from the pixel format, so list the camera's supported formats before changing it rather than assuming.
If the stride arithmetic checks out and rows still corrupt, clear the link variable before digging deeper: reseat the connector and swap in a known-good camera data cable such as the LS-CBL-0199, a 3 m high-flex GigE cable with screw locks.
Worked example: 1280 × 960 at 30 fps
Take a Mono8 sensor of 1280 × 960 pixels streaming 30 frames per second, at 1 byte per pixel.
- Full frame: 1280 × 960 × 1 B = 1,228,800 bytes ≈ 1.23 MB per frame. At 30 fps: 1,228,800 × 30 = 36,864,000 B/s ≈ 36.9 MB/s, about 295 Mbit/s.
- The centered 640 × 480 window you would have placed at OffsetX = (1280 − 640) ÷ 2 = 320 and OffsetY = (960 − 480) ÷ 2 = 240 instead carries 640 × 480 × 1 B = 307,200 bytes ≈ 0.31 MB, or 9.2 MB/s at 30 fps.
- The shear arithmetic: request Width = 500 on a camera whose increment is 16 and it programs 512. Striding at 500 bytes against a true 512 gives 12 pixels of slip per row; by row 42 the start position is 42 × 12 = 504 pixels adrift, most of the row. The payload betrays it too: 512 × 480 = 245,760 bytes against the 240,000 your code assumed, a 5,760-byte gap of pure rounding.
Three ways to crop when offsets do not exist
| Approach | Crop happens | Wire load in the example | Window position |
|---|---|---|---|
| Width and Height only | In the camera | 9.2 MB/s | Fixed by firmware, usually centered |
| Full frame, crop on the host | In your software | 36.9 MB/s | Anywhere, after transfer |
| Camera replacement | In the camera | 9.2 MB/s | Anywhere on the sensor |
Commit as follows. If the centered window is good enough, use size-only cropping and confirm placement once with an exposure of a target marked in one corner — that single frame tells you whether this camera centers the window or anchors it, and after that the position is a constant. If the position must move, crop on the host and budget the full-frame wire load. That figure sits comfortably inside the roughly 100 MB/s a 1 Gbps link delivers; large sensors do not. 25 MP at 8 bits is about 25 MB per frame, so 30 fps wants about 750 MB/s.
If the position must move and the bandwidth must fall, the camera is the wrong part. Choose the replacement by interface headroom and by the feature dump: any current area scan cameras can be screened the same way, and a 25 MP 10GigE model such as the MV-CH250-25TC-F-NF keeps the host-crop path open on large sensors.
- Sensor format
- APS-H
- Lens mount
- F-mount
- Interface
- 10GigE
- Resolution
- Over 25 MP
For the sizing itself, cropping at the source to cut bandwidth before the host works through the camera-side numbers, and the camera finder or the system configurator starts a replacement search at the right step.
The configurator matches a camera, lens, light, light controller and cables to each other, step by step, and lists only parts that fit what you already picked.
When offsets exist but still read zero
Three ordinary traps produce the same 0, 0 readback on cameras that do have the nodes:
- Write order. Many cameras reset OffsetX and OffsetY to zero whenever Width or Height changes, so setting the position first and the size second silently erases it. Set width and height first, then the offsets, and re-read to confirm.
- A stale offset clips WidthMax. A nonzero OffsetX left over from an earlier session shrinks the maximum width you can request; zero the offsets and requery WidthMax before concluding the camera refuses your size.
- Wrapper persistence. Values written while acquisition is running may not stick; the write-and-read-back discipline in setting an ROI in Python covers size, offsets and persistence.
On a 3D camera the question changes shape: depth streams carry their own ROI controls, and where to set the ROI on a 2D versus a 3D camera is worth reading before porting 2D habits.
Checklist before you commit cropping code
- Dump the feature list; confirm OffsetX and OffsetY are actually nodes.
- Round width and height to each node's increment, and read back after every write.
- Take the row stride from the delivered image dimensions, never from the request.
- Compare payload bytes with width × height × bytes per pixel before blaming the camera.
- Fix the window placement with one exposure of a corner-marked target.
- Budget the wire load for the strategy you chose, not the one you wished for.
- For the next purchase, make the feature dump part of acceptance.
If a model needs checking against an ROI requirement before you order, ask through the contact page. The cameras topic collects the related guides for the next step.
Questions
Does GigE Vision or USB3 Vision compliance guarantee OffsetX and OffsetY support?
No. Compliance covers transport and the GenICam control mechanism, not which features the camera's XML implements. The standard feature names come from the GenICam naming convention, but the implemented subset is each maker's choice. Treat the feature dump as the contract: a node that is not listed does not exist, whatever the interface badge says.
Can a different SDK or firmware add ROI offsets to this camera?
Not from the host side. Every SDK, viewer and library writes the same nodes the camera's XML describes; none can add a node the device does not carry. Firmware could, in principle, if the vendor ships an XML that includes those nodes. Design against the feature list you can dump today, not against a possible future release.
Where does the smaller window sit when offset nodes are missing?
Where the firmware puts it. On most area scan sensors the reduced window is the centered sub-rectangle, but some readout modes anchor it at a corner. One exposure of a target with a mark in one corner settles it in seconds; once measured, treat the position as fixed for that combination of width, height and pixel format.
What width values are safe to request from a GenICam camera?
Multiples of the Width node's increment — commonly 1, 4, 8 or 16 pixels — within the node's minimum and maximum. Read the value back after writing: the number the camera kept is the number your stride arithmetic must use. The same rule applies to Height and, when the nodes exist, to OffsetX and OffsetY.
Should I crop in the camera or on the host when offsets are missing?
Crop in the camera if the centered window is good enough: in the 1280 × 960 example the wire load falls from 36.9 to 9.2 MB/s. Crop on the host when the position must move, and budget the full-frame bandwidth. When both constraints apply at once, the fix is a different camera — one whose feature dump lists OffsetX and OffsetY.