Optics and defocus
Depth of field, defocus blur, the sharpness curve — and why camera focus calibration works the way it does.
Depth of field is a parameter here, not a derivation
On real hardware depth of field follows from aperture, magnification and the circle of confusion. The virtual machine does not go that route — depth of field is written directly into the machine file:
{ "name": "cam0", "depthOfFieldMm": 0.17 }Why: the aperture-and-magnification layer adds nothing to learning focus calibration, whereas treating depth of field as a tunable experiment variable adds a lot. Change it from 0.17 mm to 1.0 mm and the sharpness curve immediately flattens — "large depth of field means focus is hard to find" becomes visible instead of theoretical.
Defocus blur
sigma (in sensor pixels) = |dz| / depth-of-field x 2.2
dz is the defocus after subtracting stage height. The stage has tilt (slopes on the order
of 1e-5) and 1.5 µm of flatness ripple, so the same Z gives different defocus at different
places on the stage.
Objects on the stage have thickness (PCBs, dies, glue dots). When a field of view holds several heights at once, defocus is applied per height layer — see Workpieces · height and layered defocus.
The blur is a Gaussian approximation, not a diffraction-limited solution. That is good enough because a sharpness function only cares about gradient energy falling off monotonically with defocus, and the Gaussian matches measurements well on that point. If you need a strict PSF (super-resolution, phase retrieval) this model does not apply.
When downsampling, divide sigma by the scale factor, otherwise the preview is permanently blurrier than the full frame and focus never looks right.
The sharpness function
Chain (7) grabs a frame at each of a series of Z positions, computes sharpness, and finds the peak.
The vision layer provides Tenengrad (Sobel gradient energy, sum(Gx^2 + Gy^2)) — one
function, not selectable. The reasons: a sharp enough peak, insensitivity to brightness changes,
and an implementation simple enough that a student can write it themselves.
Pitfall: the absolute sharpness value means nothing. Only the position of the peak means anything. Change the exposure or the target and the whole curve shifts up or down while the peak stays put. The interface comment says so explicitly: it is comparable only under "same camera, same field of view, only Z changed", and it is not an image quality metric. People have used the absolute value as a pass criterion and had it collapse the day the illumination changed.
Peak fitting
Do not simply take the maximum sample — that caps accuracy at the step size. Fit a parabola through the peak and its two neighbours:
peak at i, with y1 = S(z_{i-1}), y2 = S(z_i), y3 = S(z_{i+1})
delta = 0.5 * (y1 - y3) / (y1 - 2*y2 + y3)
z_focus = z_i + delta * z_step
This takes focus accuracy from "one step" to roughly "a tenth of a step".
It assumes the curve really is near-parabolic around the peak. Dragging far-defocused points into the fit makes it worse, so use the peak and one sample either side, nothing more.
Choosing the scan range
demo-xy-galvo has a 0.17 mm depth of field and a true focus Z of 112.347. The default scan is
centred on the nominal focus Z with an odd number of steps (odd so that the nominal value
itself is sampled).
Two rules of thumb:
- The range must be several times the depth of field, or the curve is monotonic and there is no peak to fit;
- It must not be too large either: far from focus the real gradient is small and noise dominates, so those samples only pull the fit around.
The tolerance for chain (7) is 0.05 mm, one notch looser than the 0.02 mm of chain (6): a sharpness peak is inherently blunter than a spot diameter. That is not implementation laziness.
How noise affects focus
Sharpness is a sum of squared gradients and noise has gradients too, so noise lifts the whole curve's baseline — and lifts it more far from focus, where the real gradient is small and noise dominates.
The result: with heavy noise the sharpness curve flattens, the peak becomes indistinct, and
the fitted focus wanders. Raise noise.imageSigma in the machine file from 3.0 to 15, run chain
(7) again, and watch focus repeatability degrade — one of the most worthwhile experiments to
run by hand.