Skip to content
PreciSim
concepts

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.

Last updated: Sep 23, 2026
Was this page helpful?