System designTroubleshooting

Auto exposure region of interest ignored: where it breaks

The auto exposure region of interest is set, the call succeeds, and exposure still tracks the full frame. Here are the causes and the read-back check.

LumaSpec Vision10 min read Share on LinkedIn

On this page 10 sections
  1. 01What a working AE region changes
  2. 02The black-cover test
  3. 03Cause 1: the coordinates are in the wrong space
  4. 04Cause 2: the set ran before the AE had a stream to act on
  5. 05Cause 3: a later write replaced it, or a zero weight emptied it
  6. 06The check: read the regions back while the stream runs
  7. 07Applied and proven, but the image still clips
  8. 08Cameras whose settings round-trip
  9. 09Prevention checklist
  10. 10Questions

Your auto exposure region of interest call returns success, and the camera ignores it. Exposure keeps tracking the whole frame: black out the corner you weighted and nothing ramps, brighten it and nothing pulls back. This is the standard way AE regions fail on embedded camera stacks and SDK integrations, and it rarely leaves an error behind. The set call validates its arguments and stores them; then the AE algorithm never sees them, or sees them in a coordinate space that misses the sensor. If you are wiring a camera SDK into a production line, this gives you the four ways a region gets silently dropped, a bench test for each, and the read-back check that settles it while the stream runs.

What a working AE region changes

Once a region set is active, the AE statistic stops being the frame average and becomes a weighted mean over the windows you listed. The algorithm compares that mean against its target — typically half of full scale; treat 120/255 as a common value — and moves exposure, usually together with gain, until the window mean lands on target. Pixels outside the listed regions get no vote. The statistics behind this are the same means and clipping metrics covered in histogram exposure metrics for auto exposure and contrast control, and the correction itself is the proportional law from build a software auto exposure algorithm: the control law.

weighted mean = Σ (weight_i × mean_i) / Σ weight_i multiplier = target mean / weighted mean new exposure = current exposure × multiplier

With one 200 × 200 window at weight 1.0 on a 4000 × 3000 sensor, the other 99.7% of the pixels are invisible to the AE. Everything you expect from a working region follows from that: cover the window and exposure ramps hard; cover anything outside it and nothing moves.

The black-cover test

Aim the camera at a steady, evenly lit mid-gray target and let exposure settle. Cover exactly the area you set as the region with something matte black, wait two seconds, and watch the exposure value your SDK reports. Then cover the diagonally opposite corner instead. A live region answers the first cover with a large exposure ramp and ignores the second; a full-frame AE does the opposite. The same cover-and-watch proof backs the recipe in set auto exposure ROI in C++ on a depth camera, and it costs about two minutes on any stack.

Three outcomes point down three different paths. Exposure ramps and the frame saturates: the region is live, and the problem is the ceiling, covered near the end. Exposure moves little or not at all on the first cover: the region was dropped, and the causes below are ordered by probability.

Cause 1: the coordinates are in the wrong space

Two coordinate conventions exist and both are common. Pixel interfaces take integers counted against the active pixel array; normalized interfaces take floats from 0 to 1 spanning the full frame. Cross-feed them and the call still succeeds: 200 on a normalized interface means 200 frame-widths and gets clamped into nothing, while 0.5 on a pixel interface rounds down to a region with no area, which many stacks answer by falling back to the full frame.

The second trap is the coordinate origin. AE statistics are tapped on the sensor side, so most stacks define region coordinates against the active pixel array of the sensor mode currently running, not against the image your code receives after binning, cropping or scaling. Run the arithmetic once: a 4000 × 3000 array holds 12,000,000 pixels, so a 200 × 200 corner window covers 40,000 pixels, or 0.33% of the frame. Now place a region at y = 2000 with height 300, comfortably inside 3000 rows, and switch the sensor to vertical 2× binning. The active array is 4000 × 1500; the region starts 500 rows below the bottom edge and is silently clamped or dropped.

The LS-CMR-0166 is a 12 MP USB3 camera whose data sheet prints that 4000 × 3000 array, with a 1/1.7-inch sensor behind it — a concrete array size to run the arithmetic against.

Area scan cameras12 MP USB3 area scan camera, IMX226, 1/1.7" rolling shutter, 30 fps, 4000 × 3000 resolution (LS-CMR-0166)LS-CMR-0166
Sensor format
1/1.7"
Interface
USB3
Resolution
12 MP
Shutter
Rolling
$560.00View partBuild a system with it

The fix is mechanical. Query the active width and height of the sensor mode at the moment you set regions, build the rectangles from those numbers, and run the same code on every mode change. Active-area geometry, including deriving the active area from pixel pitch, is covered in sensor active area from pixel size for camera calibration.

Cause 2: the set ran before the AE had a stream to act on

AE initialization reads its defaults when capture starts, and many stacks reset region configuration to a full-frame default at that moment. Anything applied earlier is discarded without a status. The second variant is structural: settings interfaces are often attached per request, and a region set written to a request that never gets submitted changes nothing while still returning success.

The test is timing. Read the region set back before the stream starts and again while frames flow: if the pre-stream read-back shows your rectangles and the mid-stream one shows the full-frame default, initialization wiped them. Apply regions after frames are flowing, on the settings object of the request you actually submit, and keep that order fixed in the startup sequence. The same ordering trap, for the exposure ceiling rather than the region, is covered in auto exposure upper limit not applied: check startup settings and, on depth cameras, in depth auto exposure not applied at startup: fix the setting order.

Cause 3: a later write replaced it, or a zero weight emptied it

Region configuration is last-write-wins. A preset loaded after your set, an ISP default re-applied on a parameter change, or a second code path writing a full-frame default all overwrite the region without a status. Weight is the quieter variant: a region with weight 0 contributes nothing to the weighted mean, and several stacks treat an all-zero weight set as no regions and fall back to the full frame. Give every region an explicit positive weight — a single region carries 1.0 — and make the region write the last step of configuration. To find the clobbering write, log the region set with a timestamp after every settings mutation; the log shows the exact frame where your rectangles turned back into the full frame.

The check: read the regions back while the stream runs

Treat the setter's return value as argument validation and nothing more. The decision test is the round-trip: once frames are flowing, read the applied region set back through the getter that pairs with the setter, and log the region count, every rectangle and every weight. Compare against what you sent. Matching rectangles with positive weights, plus a positive black-cover ramp, is end-to-end proof that the region sits in the AE path. Anything else points back at the causes above. A set call that succeeds while the stored value never changes is its own pattern; set call succeeds but nothing changes: readOnly parameters ignored walks that case.

// Type and method names as one embedded camera stack spells them; your SDK
// names the same settings its own way. The order of operations is what carries.
std::vector<AcRegion> regions;                    // empty vector, element type AcRegion
regions.push_back(AcRegion(0, 0, 200, 200, 1.0)); // x, y, width, height, weight
iAutoControlSettings->setAeRegions(regions);      // status reports argument validation only

// While frames are flowing, read the same settings interface back and log
// the region count, each rectangle and each weight the AE actually holds.

Cover the weighted area once more after the read-back matches. A matching round-trip and an exposure that ramps settle the question; everything short of that is a guess.

Applied and proven, but the image still clips

A capped AE is not an ignored AE. If read-back confirms the region and the cover test ramps exposure but the frame still saturates, the control law wants a longer exposure than the configured maximum allows and the AE parks at the ceiling. Query the exposure range from the interface before you tune; query a 3D camera exposure range from the API before you set it shows the query, and the unit trap behind such limits has its own write-up in auto exposure limit units in microseconds: query before you set. When a set limit itself refuses to apply, auto exposure limit not working: check SDK version and interpreter covers the version gate.

When the lens iris is also under automatic control, the correction splits between iris and exposure, and an exposure-only read can look like a dead region. Auto exposure vs iris control: which one the camera sets tells you how to see which one moved. If the ceiling is the binding constraint, the fix is optical, not software: more light on the weighted window.

Cameras whose settings round-trip

The routine above — set, read back, re-apply on mode change — is ordinary on standard machine-vision cameras, because GigE Vision and USB3 Vision cameras hold exposure, gain and their published AE controls in one feature interface that you query and read back over the same connection. Inspection that runs on the camera itself follows the same discipline with smart cameras; PC-based set-ups with area scan cameras. Both families are filterable in the camera finder.

The MV-CU020-90GC is a 2.5 MP color camera on GigE with a global shutter, a 1/1.7-inch sensor and a C-mount — a good starting point for exactly this round-trip check.

Area scan camerasHikrobot MV-CU020-90GC 2.5 MP Area Scan Camera, GigE, GMAX4002, ColorMV-CU020-90GC
Sensor format
1/1.7"
Lens mount
C-mount
Interface
GigE
Resolution
Up to 3 MP
$309.00View partBuild a system with it

For inspection on the device itself, the MV-SC5060XM-08M-WBN pairs a 6 MP mono sensor with an 8 mm M12 lens on GigE, and the MV-SC3050XC-16M-ATN-H is a 5 MP color vision sensor on Fast Ethernet with a 1/1.45-inch sensor and a global shutter.

Smart cameras & vision sensorsHikrobot MV-SC5060XM-08M-WBN SC5000X series Smart Camera, 6 MP, Mono, 8 mm focal length, M12-mountMV-SC5060XM-08M-WBN
Interface
GigE
Resolution
6-10 MP
$1,629.00View part
Smart cameras & vision sensorsHikrobot MV-SC3050XC-16M-ATN-H 5 MP color vision sensorMV-SC3050XC-16M-ATN-H
Interface
Fast Ethernet
Resolution
5 MP
$1,809.00View part

Prevention checklist

  • Derive every rectangle from the active width and height of the current sensor mode, queried at set time — never from the delivered image size. Binning and crop change the image, not the coordinate space.
  • Apply the region set after frames are flowing, on the settings object of the request you submit. Pre-stream writes are the ones initialization eats.
  • Give each region an explicit positive weight; a single region carries 1.0. All-zero weights fall back to the full frame on many stacks.
  • Make the region write the last configuration step, and log every settings write that follows it. Last write wins.
  • Read the applied set back mid-stream at commissioning and after every sensor mode change, and diff it against what you sent.
  • Run the black-cover test on the bench before the line runs. It is the only end-to-end proof, and it takes two minutes.

For a camera where this whole routine is one feature-map call instead of an SDK hunt, start at the camera configurator. More fixes in this family sit on the systems topic page, and if a set-up question survives the checklist, the contact page reaches the applications team.

Questions

Are AE region coordinates measured in pixels or in fractions of the frame?

Both conventions exist, and the mismatch is a top cause of a silently ignored region. Pixel-coordinate interfaces take integers against the active pixel array of the current sensor mode; normalized interfaces take floats between 0 and 1. Read the value back right after setting it: what returns tells you which convention the interface applied, and whether it clamped your rectangle into something empty.

How many AE regions should I use, and what weights?

One region is enough for most lines: put it where the defect or the gauge sits, weight 1.0, done. Add regions only when brightness varies across the part in a way the light cannot even out. Treat weights as shares, not percentages: two regions at 1.0 and 3.0 hand the second window three quarters of the vote, which suits one window watching the feature and one watching the background.

The region reads back correctly but the image still saturates — what now?

The region is working; the exposure has run out of headroom. The control law wants a longer exposure than the configured maximum allows, so the AE parks at the ceiling and the frame clips. Query the exposure range before tuning, check its units — most interfaces quote microseconds, so typing a millisecond value there overshoots by 1000× — and confirm whether auto gain or an auto iris shares the correction. More light on the region is the fix.

Does the AE region follow the ROI I crop the image to?

No. The measurement ROI lives in the delivered image, after sensor readout, binning and ISP scaling. The AE region is consumed earlier, inside the statistics the exposure decision runs on, and most stacks define it against the sensor mode's active pixel array. Crop the image and the measurement ROI moves with it; the AE region stays at the sensor coordinates it was set to. Set the two independently and re-derive both on a mode change.

Can I set the AE region once at startup and forget it?

Only if nothing changes the sensor mode afterwards. A mode switch — resolution, binning, flip — redefines the array the coordinates refer to, and several stacks re-initialize AE statistics with a full-frame default when the mode changes. Store the region set with the job, apply it after the stream delivers frames, and re-apply it in the same code path that switches modes. One read-back after each change keeps a silent full-frame fallback out of production.