UVC autofocus control in OpenCV: what the converter board decides

You call cap.set(cv2.CAP_PROP_AUTOFOCUS, 1) on a USB camera module and nothing moves. The lens was never able to move: autofocus over UVC is built into the module's converter board, in its motor driver and firmware, and advertised in its USB descriptors. OpenCV can only switch and aim a focus that already exists. This guide explains where the capability lives, how to test a module in minutes on Linux and Windows, why fitting a different sensor board cannot add it, and how to decide between a firmware-autofocus module and a locked-lens machine-vision camera. Run the tests before you order, not after.

What autofocus over UVC is made of

Four pieces, and all four sit in hardware or firmware before the USB plug:

1. The actuator — a voice coil motor (VCM) around the lens barrel that moves the optics a fraction of a millimetre.
2. The driver — a digital-to-analogue current driver on the converter board that powers the coil.
3. The firmware — an autofocus loop on the converter's processor that scores each frame and steps the coil until contrast or phase data peaks.
4. The descriptors — the UVC descriptors the module sends at enumeration, listing which camera-terminal controls it implements, including focus absolute, focus relative and focus auto.

Remove any one of the four and the camera is fixed-focus for good. None of them can be added from the host side: the operating system, an SDK or OpenCV can only operate controls the firmware has built and advertised.

Where the host sees the focus control

The camera terminal of a UVC module carries a bitmap of the terminal controls its firmware implements, and the focus controls occupy three bits of that bitmap. If those bits are clear, no host software of any kind offers focus, because Windows, Linux and every library above them read the same descriptors.

Windows maps the standard controls into DirectShow and Media Foundation, and its UVC 1.5 extension scheme lets host software drive additional focus settings on cameras that implement the extension units. On Linux, the kernel's uvcvideo driver exposes the same controls plus any vendor extension units the module declares.

OpenCV sits above this plumbing. CAP_PROP_AUTOFOCUS and CAP_PROP_FOCUS are pass-through names: the DirectShow, MSMF and V4L2 backends forward them to the controls above, and OpenCV adds no focus logic of its own. The same plumbing is why exposure or focus properties vanish on cameras whose backend cannot map them (Camera exposure property not found: check the source object). If the stream is not up yet, start with getting a UVC camera streaming over USB without a config file and come back to focus.

Test a module before you write any code

On Linux

Ask the driver to list what the camera declares:

v4l2-ctl -d /dev/video0 --list-ctrls

A module whose firmware implements autofocus prints focus rows with a real range, in this shape (illustrative values):

focus_absolute 0x009a090a (int)  : min=0 max=250 step=1 default=0 value=100
focus_auto     0x009a090c (bool) : default=1 value=1

A fixed-focus module prints no focus rows at all. That absence is the answer: nothing downstream can create the rows.

On Windows

Probe in OpenCV and read every property back after you set it:

import cv2

device = 0                                            # camera index (illustrative)
cap = cv2.VideoCapture(device, cv2.CAP_DSHOW)

cap.set(cv2.CAP_PROP_AUTOFOCUS, 1)                    # ask the firmware to focus
print('autofocus:', cap.get(cv2.CAP_PROP_AUTOFOCUS))  # 1.0 when the module has AF
cap.set(cv2.CAP_PROP_AUTOFOCUS, 0)
cap.set(cv2.CAP_PROP_FOCUS, 200)                      # aim the lens; mm on Windows
print('focus:    ', cap.get(cv2.CAP_PROP_FOCUS))      # tracks 200 when honoured

The test that proves the result: put a printed target in front of the lens and move it between about 150 mm and 400 mm. On a module with firmware autofocus, the image re-sharpens within about a second and the autofocus readback holds 1.0. With autofocus off, a manual focus value you send is one the barrel actually reaches. On a fixed-focus module, both readbacks stay at their defaults, usually 0.0, and no setting changes the image.

With your eyes

Power the module and watch the barrel. A module with a voice coil motor hunts briefly on power-up or on focus auto. A fixed lens, glued or clamped, never moves. No movement plus no focus rows in the control list settles the question.

Why a sensor-board swap cannot add autofocus

The two-board construction — sensor board and USB converter board joined by a ribbon — looks modular, but only in one direction. The converter board is the USB device: it holds the enumeration, the descriptors, the autofocus firmware and the coil driver. The sensor board supplies image data and, when the sensor has phase-detect pixels, defocus measurements that help the firmware decide where to move. Phase-detect pixels do not move a lens; the converter's driver circuit and firmware must, and on a fixed-focus converter neither exists.

An autofocus sensor board fitted to a fixed-focus converter streams pictures and never focuses. Board pairing, ribbon pinout and firmware are set by whoever built the module. If you need autofocus, order the autofocus version as built: one converter, one sensor board, one firmware, tested as a unit. Mixing boards is the expensive path (camera module interface compatibility: what to verify).

One-shot, manual and continuous: who runs the loop

Three behaviours hide behind the word autofocus:

• Continuous. With focus auto enabled, the module's firmware scores every frame and re-focuses as the scene changes. Modules sold as continuous-autofocus UVC cameras do this by default, with no host command at all.
• One-shot. The firmware runs a single focus cycle when asked and holds the result — again a firmware feature.
• Manual. You disable focus auto and send a focus position; the firmware drives the coil there and holds it.

In all three, the loop runs inside the module. OpenCV over UVC can enable, disable and aim — it cannot run its own focusing algorithm through the standard controls. To own the loop yourself, the camera must at minimum expose a manual focus control, which is exactly what the tests above check.

The depth-of-field test: when locked focus beats autofocus

For an inspection station the real question is usually not how to get autofocus but whether you need it. Fixed optics give the same sharpness on every frame and keep calibration valid; autofocus gives you a moving system. Depth of field decides.

m is magnification, N the f-number and c the circle of confusion you accept — two pixels is the usual machine-vision choice. This is the geometric estimate, good for magnifications well below 1.

Worked example: a sensor 4.6 mm wide with 3.2 μm pixels, a field of view 100 mm across, an f/2.8 lens, and c = 2 pixels = 6.4 μm = 0.0064 mm.

• m = 4.6 mm / 100 mm = 0.046
• DoF ≈ 2 × 2.8 × 0.0064 mm / 0.046² = 0.03584 mm / 0.002116 ≈ 17 mm

That is about ±8.5 mm around best focus. Part heights within ±3 mm of the mid-plane sit inside it with margin: lock the focus and skip autofocus entirely. A distance that swings ±15 mm covers 30 mm of travel, nearly twice the whole band, so the system needs refocusing between conditions: firmware autofocus, a programmed sweep, or a focus stage.

Focus also walks as the camera and bracket warm up, which shrinks the usable band further on the day shift (camera focus drift with temperature: diagnose daytime blur).

The machine-vision path: pick the mount, focus once, lock it

Machine-vision board cameras carry no lens motor at all, and that is the feature. Focus is a lens decision: choose M12, CS-mount or C-mount optics, set the working distance on the bench and lock it. C-mount and CS-mount lenses focus on the barrel ring and hold with a lock screw or a drop of thread adhesive; M12 lenses use the focus lock ring on the barrel. Back focus — the sensor-to-lens distance behind the mount — is the other half of the setup and the usual source of drift (lens focal length vs back focus in board cameras).

Three mounts, three ways to lock focus:

The LS-BCM-0003 takes any C-mount lens over USB3 at up to 120 fps. The LS-BCM-0020 moves the idea to CS-mount on GigE at 18 fps. The MV-CB016-10GM-M-W pairs a 1.6 MP IMX296 sensor with an M12 mount on GigE, the classic embedded build where the lens locks with its own ring. On all three, focus is set once and held mechanically. The camera finder filters these by mount and resolution, and the configurator starts the build at the camera step.

Pixel size sets the depth-of-field band, and smaller pixels narrow it:

The LS-BCM-0056 records 12 MP through a C-mount with 1.6 μm × 1.6 μm pixels. Against the 3.2 μm worked example above, the same two-pixel criterion is 3.2 μm instead of 6.4 μm, so the same f-number buys roughly half the depth-of-field band: focus carefully, lock hard. For the wider selection process, the board level camera selection guide for embedded vision machines walks resolution, interface and mount together, and an area scan camera follows the same rule — no autofocus motor, focus a property of the lens.

If you must focus from your code: the sweep loop

With a manual focus control exposed, the host can run the loop: set a focus position, discard a frame or two while the coil settles, score the next frame's sharpness, step. The standard score is the variance of the Laplacian of a grayscale frame — cv2.Laplacian(img, cv2.CV_64F).var() peaks at best focus. Sweep coarse to fine: step across the range, then refine around the peak.

Budget the time. A sweep of 40 focus steps with 2 settling frames each is 80 frames; at 30 fps that is 80 / 30 ≈ 2.7 s per focus pass. On a bench that samples whenever you ask, fine. On a line running 600 parts per hour — one part every 6 s — a 2.7 s sweep spends nearly half of every cycle focusing. Past that rate, software autofocus loses to mechanics: mount the camera on a focus stage driven to the known distance, or split the task across two fixed stations.

The decision, per case

• Fixed station, part height inside the depth-of-field band — the ±8.5 mm example above: a board camera with a locked C-mount, CS-mount or M12 lens. No autofocus anywhere, firmware or software. Shortlist at board-level cameras, set focus on the bench, lock the ring.
• Bench or R&D rig, USB mandatory, distance genuinely changes — a UVC module sold with continuous autofocus: the firmware runs the loop, CAP_PROP_AUTOFOCUS enables it and CAP_PROP_FOCUS aims it. Run the control-list test before ordering, not after.
• Production line, distance changes, cycle time under a few seconds — neither flavour of autofocus is fast enough. Lock focus per station, or move the camera on a stage between distances.

The cameras topic page collects more camera-side guides, including the 4K resolution-mode explainer for UVC formats. When mount and lock are settled, the configurator is where the rest of the build comes together, and free expert support comes with every order — use it to sanity-check the lens and lock choice before anything is glued.