Stereo calibration board coverage: fix the stall at the end

You captured your frames, the console printed a reprojection error for each camera, and then nothing happened: no file in the resources folder, no confirmation, a small window that ignores every click. Re-run it three times, get slightly different numbers, same silence. This end-of-run stall is common in stereo camera calibration tools, and it is almost never a broken sensor. It applies whether you recalibrate after a knock, a lens swap or a settings reset. The two real faults are an end-of-run dialog hiding behind your other windows, and a calibration board that never covered the edges of the frame. Work through the causes below in order of how often they turn out to be the problem, run the recovery list, and finish with the checks that tell you the written calibration is good.

The symptom: the solve finishes, the run does not

The signature is specific. Capture works: frames save into per-camera folders under the dataset directory, and the console reports each save. Then an intrinsics block prints per camera — color first, then the two mono sensors — with reprojection errors in the 0.5 to 0.8 px range. A second window shows scattered dots over a picture of the frame.

After that the console goes quiet, the dots window ignores clicks, and the resources folder the guide promised stays empty. Read that as two separate facts. The solve finished, because the errors printed. The run is not over, because the write step never executed. The dots window ignoring clicks is normal: it is a static plot, not a live view. Most stalls stop at cause 1 below; the rest are coverage problems that cause 2 and 3 pick up.

Cause 1 (most likely): the completion dialog is behind your windows

When the solve finishes, the script draws a small completion window — green, with a calibration-complete message in the tool family this signature comes from — and it opens underneath whatever you had in front. The write to the device and the resources folder happens only after that dialog is closed, so a run that looks hung is a finished run waiting for one click.

Test it: press show-desktop or walk the taskbar and look for a small extra window. Preview windows in these scripts close on a single key press — Q in this script family — while the completion dialog takes a click on its close control, or the same key once it has focus.

Fix: close the dialog. The console comes back, the write lands, and the resources folder shows a file with a fresh timestamp.

Prevention: run the capture from a terminal you do not switch away from — an IDE's integrated terminal keeps the window stack predictable — and stay put once the console reports it is processing images. The dialog appears right after the last reprojection line.

Cause 2: the dots window is a coverage map, and yours has holes

That second window is not an error log. Each dot marks where a detected board corner landed, across every frame you captured, plotted over the sensor's image area — one map per calibrated camera. It is the most useful quality report the tool gives you.

Read it as a 3 x 3 grid: nine zones, all nine needing dots, including the border strips and the corners. Lens distortion is strongest at the frame edges, so corners sampled only near the center leave the distortion model free exactly where rectification depends on it. The colored polygons in some guide screenshots were only ever decoration; the dots are the evidence.

The fix is a sweep, not more of the same: center, each edge, each corner, tilted 10-30° either way, at two distances. Keep the whole board visible in both cameras in every frame — all black squares unoccluded — because a clipped board corrupts corner ordering. If holes remain after the guide's default 39 frames, raise the count to 60-80 with the capture-count option (-it in this script family). Past roughly 100 frames the gain flattens.

How much margin a target needs over a given frame is its own estimate: see calibration target field of view and lens coverage margins.

Cause 3: every sensor needs its own full coverage

The console calibrates each camera on its own before the stereo step — the stereo solve only places two already-calibrated cameras in one frame — so each sensor needs its own map filled. A board position that fills the mono pair's frame can sit partly outside the color sensor's narrower view, and the depth output covers less of the scene than the color image does.

That is why one dots window can look full while another is sparse: check the map for color, left and right separately, and fill whichever has holes. The color-versus-depth coverage gap is its own subject: why stereo depth coverage is smaller than the color image's.

The numbers you already have are a passing grade

The errors sitting in the quiet console are good news once you know the acceptance band: under 1 px reprojection is usable for depth, under 0.5 px is tight. The run in question printed 0.53 px on the color camera, 0.76 px left, 0.79 px right — inside the band for every camera. The 0.26 px spread between best and worst camera comes from sampling and lighting, not from a damaged sensor, and it shifts a few hundredths of a pixel between runs.

Keep one boundary in mind: reprojection error measures fit to the captured corners, not depth accuracy in the field, which is why calibration accuracy beyond reprojection error is judged with separate tests — the wall checks at the end of this page are exactly that. For per-camera residual targets, see average and maximum calibration residual values.

Worked example: how close the board must sit to cover the edges

Take a compact stereo module with mono sensors of 70° horizontal field of view — a typical value for the class; substitute your own — and a 0.35 m wide board.

At a capture distance D = 0.50 m: W = 2 x 0.50 m x tan(35°) = 0.700 m, so the board covers 0.35 / 0.700 = 0.50 of the frame width, and the outer 25 % strip on each side never sees a corner. At D = 0.30 m: W = 2 x 0.30 m x 0.700 = 0.420 m, and coverage rises to 0.35 / 0.420 = 0.83 — close enough that the board's edge can nearly touch the border, which is where the dots need to land.

The same numbers say why coverage is worth the fuss. With a frame 1,280 px wide, f_px = 1280 / (2 x 0.700) = 914 px. For a module with a 75 mm baseline, a plane at Z = 2.0 m, and a typical disparity scatter of 0.2 px after a passing calibration: depth error = (2.0^2 x 0.2) / (914 x 0.075) = 0.80 / 68.6 = 0.012 m. About 12 mm of depth wobble from sampling alone — and a board held at 0.50 m instead of 0.30 m leaves the distortion terms free to add more on top.

A board that reads too small at your working distance is a failure of its own: checkerboard calibration fails at distance. For a scene with a metre-wide field you may need to build a bigger grid: a large calibration grid for a 1 m field of view.

Recovery, in order

1. Bring the pending run home: show the desktop, find the completion dialog, close it. The resources folder should gain a file with a fresh timestamp — that is the write.
2. Point the module at a plain wall at 0.5 m and at 2.0 m and read the reported depth from the viewer or a short capture script.
3. If depth is off, open the coverage maps from the run you just kept. Sparse border zones confirm the diagnosis.
4. Recapture with the nine-zone sweep at 0.30 m and 0.50 m, 60-80 frames, using the capture-count option (-it here).
5. Close the completion dialog again, then repeat the wall test and compare the two runs' numbers.

Prevention: hold the camera still and the board flat

Fix the camera and move only the board. A slide-table stand holds the sensor at a set height and distance while you sweep the target, and it removes the hand shake that blurs corners. The LS-MNT-0040 slide-table stand gives a 700 mm column and a 400 x 450 mm base for exactly that set-up.

Glue the printed board to glass or flat aluminum; paper curl moves corners by millimeters, and a wrong square pitch is a silent error of its own — see checkerboard calibration error: fix the grid pitch. Matte paper under even light beats a glossy board under a point source; glare and hard shadows kill corner detection, which the chessboard-not-detected fixes cover in detail. If the color sensor autofocuses, lock the focus before the first frame: lock the focus before you calibrate. Set the capture distance once, deliberately — the 3D camera working distance and positioning guide covers that geometry.

Checks before you trust the written calibration

• Coverage: dots in all nine zones of each calibrated sensor's map, borders included.
• Residuals: every camera under 1 px; a best camera near 0.5 px is typical for a clean sweep.
• Rectification: a feature on the left edge of the left image sits on the same pixel row in the right image. Rows that drift up or down between the two mean the stereo pair is still misaligned.
• Depth: with the example's parameters, the wall at 0.5 m reads within about ±1 mm and the wall at 2.0 m within about ±12 mm. A reading off by more than 3 % at either distance says redo the capture, not the math.
• Stability: repeat the wall test after an hour of warm-up. A mount that moves with temperature shows up as drift between the two runs.

Where the usual advice is wrong

• More images is not the fix; coverage is. A hundred centered frames leave the same holes as twenty.
• The missing colored polygons were never a pass condition. The dots map is the pass condition.
• A console that goes quiet at the end is usually the tool waiting on you, not a crashed script.
• A knocked module is not dead. Recalibration measures the geometry as it sits now, provided the sweep is full and the mount is rigid. What it cannot absorb is a lens that shifts after you re-tighten it, or a cracked window — re-seat those first, then calibrate.
• The calibration the vendor tool writes is the one the depth pipeline trusts. You can carry it into your own code: importing stereo calibration parameters across software formats.

Set the next capture up from scratch

If a stall ate your afternoon, make the next run boring: pick the module from the 3D camera finder or the 3D sensors category, mount it on one of the camera stands — the stand step of the configurator and the camera stand finder narrow the choice — and follow the paired-capture workflow in stereo camera calibration from paired checkerboard images. The 3D vision topic page collects the rest of the calibration and capture guides.