Calibration chains
The seven chains, their order, their dependencies, their pass criteria, and why "chain" is the right word.
Why "chain" and not "a pile of calibrations"
Because they have a dependency order, and when an earlier one is wrong the later ones do not fail — they quietly produce a plausible wrong number.
(7) camera_focus (1) pixel_size
camera focus Z pixel size + mounting angle <- neither has a prerequisite
(runs first: every later | |
chain focuses before v v
grabbing) (2) cam_actuator_offset (3) lens_distortion
camera-to-actuator radial distortion
| | |
v +---------+--------+
(6) laser_focus v v
laser focus Z (5) field_correction (4) hand_eye
galvo field nine-point
The seven chains
| id | Name | Solves for | Needs | Tolerance |
|---|---|---|---|---|
pixel_size |
(1) Pixel size | mm/px and camera mounting angle (a 2x2 Jacobian) | — | 0.002 µm/px; 0.02° |
cam_actuator_offset |
(2) Camera-actuator offset | XY offset from camera centre to galvo field centre | (1) | 0.01 mm |
lens_distortion |
(3) Lens distortion | radial k1, k2 | (1) | 0.3 px RMS residual |
hand_eye |
(4) Nine-point / hand-eye | pixel-to-stage affine relation | (1)(3) | 0.005 mm residual |
field_correction |
(5) Galvo field correction | in-field grid correction table | (1)(2)(3) | 0.010 mm de-translated residual |
laser_focus |
(6) Laser focus Z | Z where the spot is smallest | (1)(2) | 0.02 mm |
camera_focus |
(7) Camera focus Z | Z at the sharpness peak | — | 0.05 mm |
Every tolerance comes from CalibTolerance in core/src/PreciSim.Core/Constants.cs — not from magic
numbers scattered through the chains. The values correspond to the demo-xy-galvo virtual
machine; on real hardware you set them from your own error budget.
Why (7) runs first: the focus Z it produces is the precondition for every later chain ("focus before you grab"). It has no prerequisite of its own, so it does not rigidify the dependency graph — running another chain on its own with a nominal focus Z still works.
Every chain implements the same interface
Which is why the wizard UI, progress, logging, cancellation, archiving and re-runs are all shared:
public interface ICalibrationProcedure
{
string Id { get; } // e.g. "pixel_size"
string DisplayName { get; }
IReadOnlyList<CalibStep> Steps { get; } // wizard step bar
IReadOnlyList<string> Prerequisites { get; } // ids of the chains it needs
Task<CalibResult> RunAsync(
CalibContext ctx,
IProgress<CalibProgress> progress,
CancellationToken ct); // must cancel and reset safely mid-run
}CalibContext holds exactly four things: the device set, the vision service, the run options, and
a truth source (null on real hardware). A chain never moves the world by itself — to swap the
calibration target it calls ctx.RequestBoardAsync and lets the layer above decide how
(prompt the operator on real hardware; switch the preset on the virtual machine). A chain that
swaps the board itself turns into the engine validating itself: all tests green, everything wrong
on the floor.
How results travel between chains
CalibrationRegistry.Apply is the single coupling point: the measured values of one chain are
written into the next chain's CalibOptions.
case "pixel_size":
options.Jacobian = new Jacobian2x2(v["j00"], v["j01"], v["j10"], v["j11"]);
break;
case "cam_actuator_offset":
options.MeasuredOffsetMm = new Vec2(v["offsetXMm"], v["offsetYMm"]);
break;No chain ever asks the engine for a truth value. Truth is used for comparison afterwards, never in the solve — that rule is what makes the whole thing trustworthy.
What a result looks like
public sealed record CalibResult(
bool Success,
IReadOnlyDictionary<string, double> Values, // what was measured
IReadOnlyList<ResidualPoint> Residuals, // for the residual plot
string? FailReason,
IReadOnlyList<string> SavedFrames) // saved failure frames
{
public IReadOnlyList<TruthCompare> TruthCompares { get; init; } // virtual machine only
public ResidualStats Stats { get; init; } // three residual statistics
public IReadOnlyDictionary<string, double> TimingMs { get; init; }
}Two design points, both learned the hard way:
- Report three error figures, always: raw maximum, de-translated residual, leave-one-out. A single number cannot be interpreted — a constant translation can be compensated at the station, a random scatter cannot, and one RMS hides the difference.
- Failure frames must be saved: when vision cannot find the target, the frame and the parameters in force are written to disk. Without that, "it occasionally fails to calibrate" is never reproducible.
Truth scoring: only on the virtual machine
On real hardware you have residuals but no truth. The virtual machine knows the truth, so it can add one more line:
measured: pixel size = 1.7251 µm/px
truth: pixel size = 1.7236 µm/px
compare: error 0.0015 µm/px, tolerance 0.002 -> PASS
The point is not to make the numbers look good. It is to teach you how small a residual has to be before the result is actually accurate. Most people only understand calibration the first time they see a tiny residual next to a large error.
Where results are stored
The HMI writes every run into a local SQLite database (data/precisim.db, table
CalibrationRecord):
| Column | Content |
|---|---|
ProcedureId / DeviceId / Timestamp / Operator |
who ran what, on which machine, when |
Passed |
pass or fail |
ValuesJson / ResidualsJson / TruthCompareJson |
measured values, residual points, truth comparison |
Append only, never overwrite. You can query "every calibration on this machine for the last three months" and plot the trend — when something goes wrong, tracing back to which calibration started the drift is the whole point of the archive.