Sparse reference point calibration: minimum points per model

Sparse reference point calibration should be the easy case: no grid to print, no target to place, just matched pairs of pixel and real-world coordinates. Yet the call fails with a cryptic negative error code whose message blames the calibration routine itself, even when you passed more points than the minimum the help text quotes. The routine is almost never at fault. Two causes cover nearly every occurrence: the point count sits below the floor for the calibration model you selected, or some pixel coordinates are not pixel indices at all. This guide gives the working minimums for each model — four, five and nine — shows the coordinate trap behind the rest of the failures, and works a full diagnosis so you can fix your own call in minutes.

Symptom: the error blames the calibration, not your points

The call is point-pair template calibration: you supply matched pixel and real-world coordinate pairs, choose a calibration model, and the library solves the mapping. Instead of a solution you get a negative error code such as -1074396116, and its text points at the calibration step itself. Supplying more than four points does not clear it, and neither does rebuilding the call from an empty template.

Three patterns account for practically every occurrence:

• The count is adequate for the simplest setting but below the floor of the perspective or nonlinear distortion setting actually selected.
• Some pixel coordinates were taken from an image display handler and fall outside the image; one coordinate past the edge is enough.
• The set worked on an older build and fails after an upgrade, because validation that used to be silent now rejects marginal input.

All three are caught at input validation, before any fitting starts. That is why the message misleads: the solver never ran, so the error describes the call, not the mathematics.

The minimums: four, five and nine points

The floors follow from counting equations. Each pair contributes two: pixel (u, v) must land on real-world (X, Y). A perspective plane-to-plane model carries eight independent coefficients, so four pairs are the mathematical minimum — with nothing spare to catch a bad point. Implementations in this family therefore enforce five. The nonlinear model adds distortion coefficients on top of the eight, and its implementations enforce nine. The simple setting assumes a square-on camera, which collapses the mapping to scale and offset per axis — four unknowns — so four pairs over-determine it comfortably.

The widely copied help sentence — four points for any setting — describes only the simple setting. The perspective and nonlinear floors are higher, and that gap between help text and behavior is a known documentation defect in this family of routines.

Cause 1: point count below the model floor

Test: print the pair count and read it against the table for the model actually selected, not the one you assumed. Six pairs pass a simple calibration and fail a perspective one; the same six pass perspective and fail nonlinear distortion.

Fix: add points or drop the model. If the camera views the plane square-on and lens distortion is small, the simple setting with four to six pairs is correct and fastest. If the plane is tilted, add a fifth point near the corner that currently has none. If you need distortion correction, plan nine pairs from the start — a three-by-three arrangement reaching the image corners — because retrofitting points rarely leaves room where distortion is largest.

Cause 2: coordinates that are not pixels

The second cause hides better because every number looks plausible. A mouse handler on an image display often returns positions on the display widget, not indices into the image. Zoom, scroll bars and borders shift the two relative to each other, so widget values drift outside the image. The routine validates the pixel side as image indices — zero or positive, smaller than the image dimension — so a widget coordinate one pixel past the edge rejects the whole set, and a negative value does the same.

Fix at the source: read the image control's Last Mouse Position rather than the panel's Coords value. The first is a pixel index; the second is a widget location. Or skip the mouse and read coordinates straight from the image data.

Modern sensors widen the bounds without changing the rule:

A 4000 × 3000 image accepts x from 0 to 3999 and y from 0 to 2999. The same logic scales to any sensor: take the minimum and maximum of your coordinate lists and compare with width - 1 and height - 1 before the call.

One more rejection worth knowing: the pixel side must be an image index. Teams reusing the routine as a general two-dimensional transformer — mapping instrument readings to stage positions, say — feed negative or oversized values and trip the same validation. Calibration templates are not generic coordinate mappers; fit your own polynomial for that. The wider catalogue of broken inputs lives in Camera calibration input errors: matrices and point arrays.

Worked example: a perspective call that fails on a 640 × 480 image

Inputs, from a setup of exactly this kind:

• Image: 640 × 480 pixels, 8-bit grayscale.
• Model selected: perspective — the camera views the plane at an angle — floor of 5 pairs.
• Pairs supplied: 6, above the floor, so the count passes.
• Point source: a mouse-move handler on the image indicator, with no conversion to image indices.
• Illustrative suspect values: (652, 310) and (23, -8).

Rule: every pixel coordinate must satisfy 0 ≤ u ≤ 639 and 0 ≤ v ≤ 479.

Arithmetic:

• u = 652: 652 - 639 = 13 pixels past the right edge. Invalid.
• v = -8: 0 - (-8) = 8 pixels above the top edge. Invalid.
• Valid pairs: 6 supplied - 2 invalid = 4. Four sits below the perspective floor of 5, so the call rejects the set even though six clean pairs would have passed.

Result: rejection at validation, before fitting, with the misleading message.

Decision: convert or re-pick the two bad points until all six land inside 0 to 639 by 0 to 479; the perspective fit then accepts the set. If only four clean pairs exist, add a fifth near an empty corner, or drop to the simple setting when the view is square-on. Threshold to keep: any coordinate outside 0 to width - 1 by 0 to height - 1 invalidates the whole set, and four valid pairs never pass a perspective model.

Cause 3: bunched, collinear or duplicated points

Count and bounds are necessary but not sufficient. Nine points clustered in one quadrant constrain only that quadrant, and the fit extrapolates everywhere else. Three points on one straight line add barely two equations of independent constraint, and a duplicated pair adds none.

Working rules, from the calibration documentation and the bench:

• Keep at least six pixels between the edges of detected dots; the perspective and nonlinear documentation sets that as the minimum spacing.
• Spread points over the four corners plus the center: perspective error and distortion both grow with distance from the image center.
• Before blaming the library, check that no three points lie on one line.

If your points come from dot targets, Uniform pixel grid overlay for dot-target calibration shows how to keep the detected grid uniform so the coordinates you feed the fit are honest.

If you create reference points by projecting a laser spot onto the plane, keep the emitter at Class 2 power (under 1 mW) and fixed so the beam cannot sweep to eye height.

Which model, and how many points

Choose the model from geometry, not habit:

Read the lens distortion figure before reaching for the nonlinear model. The LS-FFL-0567 is a 16 mm, 1.1", 20 MP C-mount lens rated at <0.3% distortion.

At the corner of a 1.1-inch image, roughly 9 mm from the center, 0.3% distortion is about 27 µm of radial error (0.003 × 9 mm) — near eight pixels at a 3.45 µm pitch. For a positioning tolerance of tenths of a millimetre, that residual needs no distortion model, and a four-point simple calibration is the right call. Repeat the estimate for your own lens: multiply its distortion fraction by half the image diagonal.

A perspective model is a homography; Homography pixel coordinates: map points into a warped image works the pixel mapping arithmetic end to end. To judge residuals in millimetres, convert with your object-space pixel size — Calculate object space pixel size from magnification gives the conversion.

Fix it in order

Run the checks in sequence; the failing one usually surfaces by step 3:

1. Count the pairs and read the count against the floor for the selected model: 4 simple, 5 perspective, 9 nonlinear distortion.
2. Take the minimum and maximum of the pixel u and v lists and compare with 0 and width - 1, height - 1.
3. Trace the coordinate source. Widget values become image indices through the control's Last Mouse Position, or re-read the points from the image data.
4. Reject negative pixel values. If your inputs are instrument readings rather than pixels, move the mapping into your own least-squares fit.
5. Check spread: corners and center covered, at least six pixels between feature edges, no three points collinear.
6. Re-run the call, then validate on a held-out point: apply the calibration to a pixel coordinate you did not fit and compare against a stage or gauge reading.

Step 6 is the prevention step. A calibration that reproduces a held-out point within tolerance survives library upgrades; one that was never validated is the set that mysteriously stops working later.

When sparse points are the wrong tool

If you can place a target in the plane, grid calibration beats point pairs on every measure: a printed checkerboard hands the fit hundreds of points in one image, the solve is better conditioned, and residual reporting comes with it. Checkerboard camera calibration error: fix the grid pitch covers the grid route and its classic failure, and Single camera calibration when your device has no stereo pair is the companion when one camera carries the whole rig.

Keep sparse pairs for planes you cannot touch: sealed enclosures, large stages, or planes defined by features already on the part. There, the four-five-nine table and the bounds check are your entire defense.

Parts that keep a calibration honest

Calibration quality starts with the geometry you feed it, and that starts with the camera and lens. Browse the area scan cameras and the machine vision lenses; a lens with a printed distortion figure turns the model choice into a calculation. The camera finder filters by resolution and interface, the camera configurator pairs sensor and mount in one pass, and the systems guides hub collects the calibration articles around this one.

If a build still fails after the six checks, bring the coordinate list and the selected model to the contact page — a failing reference set is usually diagnosable from the numbers alone.