Camera property shows only on or off in the capture API

You select the video source, list its device-specific properties, and one of them, backlight compensation on a UVC webcam, offers only 'on' and 'off', while the vendor's own application sets the same property with numbers. Writing either state drops the register to zero and the image goes nearly black indoors. This is a capture-API mapping problem, not a broken camera, and it is common to DirectShow-based adaptors such as WINVIDEO. This guide covers the symptom, three causes in order of likelihood, a test for each, the exposure arithmetic that tells you whether to bridge the driver or replace the interface, and the checks to run before you order a camera that behaves.

Symptom: a two-state enum, a zeroed register and a black image

The video source object lists the device-specific properties in one block. On the failing camera, brightness reads 255, contrast 127 and exposure 511, all numbers, while backlight compensation reports itself as a string enum constrained to two values, 'on' and 'off', and read-only while the stream runs. The vendor's own application, and any image editor that imports through TWAIN, shows the same property as a numeric setting.

Write 'on', or write 'off': the vendor application then reports the property as 0, and indoor frames come out close to black. Only very bright scenes stay usable. Two observations locate the fault above the sensor. The property still accepts numbers through the other interface, and the value that sticks is the bottom of the numeric scale rather than either state you asked for.

Cause 1: the capture API defines the property as two-state

DirectShow, the capture layer behind many Windows video adaptors (WINVIDEO is one), exposes the camera image-quality properties, including backlight compensation, brightness, contrast and gain, through a single video-processing interface. Every property carries the range its driver declares. When the declared range for backlight compensation holds exactly two positions, the toolbox on top maps the property to a string enum and offers you 'on'/'off'. TWAIN negotiates capabilities through a different mechanism, and the same driver can publish a numeric range there. That split is what you are seeing.

The zero has the same root. Your write passes a two-state code, the register holds a numeric scale, and what survives the translation is the bottom of that scale.

Cause 2: an auto mode owns the register

The listing showed ExposureMode, BrightnessMode and WhiteBalanceMode all set to auto. A property under automatic control is rewritten by the camera's own loop within a few frames, and enabling auto exposure passes no number at all, because the mode is the entire setting. Anything you write underneath it gets overwritten or ignored. For how those loops choose their targets, see auto exposure and auto gain on color cameras: which pixels count.

Cause 3: the property is locked while running

The property metadata also said read-only while running. Writes issued while the preview streams fail outright or land nowhere, so the register keeps whatever the last successful write left, which after the enum experiment was zero. A refused write looks identical to a lost one from the capture side.

Test each cause in order

Work through these before spending money; each takes minutes.

1. Read the declared range. Query the property's constraint metadata the way propinfo does. Two values means the API mapping is the limit, and the numeric range in the vendor tool proves the driver holds more. The same probing discipline applies to gain: how to find and validate a UVC camera gain range walks it.
2. Take every mode out of auto. Set exposure, brightness and white-balance modes to manual, write your value, re-read it, and check it survives three frames.
3. Stop the stream first. Write with acquisition halted, restart, and compare.
4. Confirm in the vendor tool. After each scripted write, open the vendor application and read the number there. That reading is the ground truth the capture API cannot argue with.

If the range query really returns two values, and manual, stopped writes still zero the register, the API pairing is the fault. No amount of retrying from capture code will fix it.

Worked example: the exposure ceiling on a 15.15 fps stream

Inputs, all read from the failing camera: frame rate 15.1500 fps from the source object; auto-exposure index 511, a unitless number; indoor frames near black after the enum write.

The rule in words: one frame admits at most one exposure, so the longest possible exposure sits at the frame period.

The arithmetic:

1 ÷ 15.1500 fps = 0.0660 s per frame = 66.0 ms = 66,000 µs.

So the sensor had up to 66.0 ms of integration time available per frame, ample for indoor lighting. The black frames came from the value written into the register, not from any hardware ceiling. On a replacement camera running at 30 fps the ceiling becomes 1 ÷ 30 = 0.0333 s, about 33,333 µs, and every value up to it is typed directly in microseconds.

Decision: a task that needs a stated exposure time, whether for strobe sync, a blur budget or day-to-day repeatability, cannot get it from an index with no unit, so replace the interface. A task that only needs to be bright enough indoors can stay on the webcam once the register is written correctly through TWAIN.

The fix that holds: exposure as a number in microseconds

Machine-vision cameras built on GenICam expose exposure as a numeric feature in microseconds, with a declared minimum and maximum, over USB3 Vision and GigE Vision. You write a number, the camera applies that number, and reading the feature back returns it. There is no enum in the way and no second application to bridge. Setting camera exposure time through a GenICam API in Python shows the calls, and what GigE Vision guarantees for camera compatibility explains why feature names and types come from the standard instead of from each driver.

Write a value outside the declared range and the camera refuses it, so check the range before the write; checking symbolics before you set a GenICam enumeration shows the same discipline for enum features.

USB3 Vision covers most bench distances.

The LS-CMR-0166 is a 12 MP USB3 area scan camera that runs at 30 fps. At that rate the exposure ceiling is about 33,333 µs, and every value below it is a number you type, not an index you interpret. The second card is a 6 MP USB3 camera with a 1/1.8" sensor on a C-mount, in mono.

Set all three candidates side by side.

Values as printed in each product's data sheet; open a part for its drawing and full specifications.

The MV-CH120-11UC adds a 1.1" sensor and a global shutter, the right pick when the part moves during exposure. For long cable runs and camera racks, the area scan cameras range holds the same class of sensors on GigE, and smart cameras and vision sensors take exposure commands in microseconds through their own interfaces as well.

More light is the other route to indoor brightness, and often the cheaper one.

USB3 gives you nothing without a cable that survives the machine.

The LS-CBL-0219 is a 3 m USB3.0 camera cable rated for drag-chain use; the cables category covers other lengths and connector styles.

If the camera must stay: write the number through TWAIN

The register lives in the camera, not in either API, so a value set through one path stays put for the other. The project is a small shim that talks to the TWAIN data source the vendor ships; a generic DLL call, a MEX file or a COM interface all work. Run it once at set-up:

1. Open the camera's TWAIN data source and read the capability's current value and its range.
2. Set every auto mode to manual, then write the numeric value you want.
3. Close the data source and confirm the number in the vendor application.
4. Acquire through your usual DirectShow pipeline, and never write that property from capture code again.

The shim costs set-up time, not frame time. Capability negotiation happens once, and capture never touches the property.

When the on/off enum is the honest answer

Backlight compensation on many sensors genuinely is a two-state algorithm, and the vendor's numeric slider often scales the same internal term the two states switch between, so a wider knob is not always a finer control. Notice what the failing camera was really telling you: the image went black because exposure collapsed, and exposure is the property worth chasing. If your task measures anything, put the effort into a numeric exposure path rather than into a wider backlight-compensation range.

Checks before you order a replacement

• Feature list first. Exposure must appear as a numeric feature in microseconds with a stated minimum and maximum.
• Frame rate against ceiling. Divide one by your frame rate and confirm the ceiling covers your longest needed exposure, with headroom for readout.
• Interface by distance. USB3 for the bench and short runs; GigE for long runs and multi-camera racks.
• Mount to sensor. C-mount covers the compact formats; larger sensors need larger mounts, and the lens must cover the format.
• Cable for the motion it will live in. Drag-chain rated if anything moves.

The camera finder filters by interface, mount and resolution, and the configurator walks camera, lens and light in one pass. More integration debugging sits on the systems topic page, and the contact page puts an applications engineer on a camera matched to your part and cycle time.

Prevention checklist

• Choose USB3 Vision or GigE Vision whenever the image is measured rather than watched.
• Query each property's type and range before the first write; never assume the vendor tool's scale matches the capture API's.
• Move all auto modes to manual before scripting values.
• Stop acquisition before writing anything marked read-only while running.
• After a scripted change, read the value back in the vendor application once; that number, not your API's reply, is the state of the camera.