World and imaging
How the virtual camera turns a stage into an image — six steps, every formula spelled out.
This page is how we honour "public formulas, closed implementation": the engine code is not delivered, but every step it computes is written down here. You can check our numbers, or reimplement the model yourself.
The world is not a bitmap
The stage is sampled analytically: give it a world coordinate (x, y) and a sampling
footprint (how much stage this pixel covers) and it returns a grey value. The dot grid, the
background texture and the laser marks are computed from formulas, not blitted from images.
Which objects can sit on the stage, how they are shaded and how tall they are is covered in
Workpieces on the stage.
The benefit is that zooming in stays sharp: the same stage seen by a 1.7 µm/px camera and by the 0.8 µm/px world resolution shows real detail, never interpolation mush.
The demo-xy-galvo world: 600 × 400 mm, base grey 96 with amplitude 18, grey 22 outside.
The six steps of a grab (order is fixed)
1. Optical centre in world coordinates = camera anchor - stage axis position
2. Field of view in mm = sensor resolution x pixel size <- independent of output resolution
3. Per output pixel: radial distortion -> mounting rotation -> stage coordinate -> sample the world
4. Gaussian blur by defocus
5. Brightness from exposure x gain x illumination
6. Add Gaussian noise
2. Field of view and output resolution are different things
FOV width (mm) = sensor width (px) x pixel size (mm/px)
mm covered per output px = pixel size x (sensor width / output width)
A downsampled preview must keep the same field of view; only the mm-per-output-pixel changes. Multiplying pixel size by the output width is the common mistake, and it leaves the preview showing a small crop of the centre — a bug you can equally hit on real hardware.
3. Distortion and mounting angle
rn^2 = (u^2 + v^2) / (half diagonal)^2 normalised to the half diagonal, not to a focal length
f = 1 + k1*rn^2 + k2*rn^4 radial only, no tangential terms
(dx, dy) = (u*f, v*f)
wx = cx + ( dx*cosθ + dy*sinθ) * mmPerPx
wy = cy + (-dx*sinθ + dy*cosθ) * mmPerPx the mounting angle uses R(-theta)
R(-theta) is not arbitrary. Write R(+theta) and the calibration chain returns a mounting
angle with the opposite sign — with a perfectly small residual. That is exactly why the
coordinate conventions belong in the comments.
4. Defocus
sigma (in sensor pixels) = |dz| / depth-of-field x 2.2
when downsampling, divide sigma by the scale factor, or the preview is always blurrier than the full frame
dz is the defocus after subtracting the stage height: the stage has tilt and flatness
ripple, so moving to another corner changes sharpness even with Z untouched. That is
deliberate — it turns "where exactly should focus Z be measured" into a real question.
5 and 6. Brightness and noise
Brightness is a single factor combining exposure, gain and illumination. Noise is zero-mean
Gaussian with a sigma from the machine file (3.0 grey levels on demo-xy-galvo).
The same seed must produce a bit-identical image: each row derives its own random source from
the frame seed rather than sharing one Random, otherwise results depend on thread scheduling
and regression testing becomes impossible.
Imaging parameters of demo-xy-galvo
| Parameter | Value | Note |
|---|---|---|
| Sensor | 4096 × 3000 | |
| Pixel size | 1.7236 µm/px | truth value; this is what chain (1) measures |
| Mounting angle | −0.80° | truth value; the sign flips easily |
| Distortion k1 / k2 | 0 / 0 | this machine has none; use test-distortion to practise chain (3) |
| Working distance + mount offset | 110 + 2.347 mm | focus Z = 112.347 |
| Depth of field | 0.17 mm | sets how fast defocus blurs |
| Exposure / gain | 8000 µs / 2.0 dB | |
| Image noise sigma | 3.0 grey levels |
The field of view is 4096 × 1.7236 µm ≈ 7.06 mm wide and about 5.17 mm high. The dot pitch on the calibration target is 2.0 mm, so one frame sees roughly 3 × 2 dots — which directly decides how large the sampling grid for chain (1) can be.
What this model does not have
No pinhole fx / fy / cx / cy, no tangential distortion, no diffraction-limited PSF, no quantum
efficiency or full-well capacity.
Not because they are hard, but because they do not help you learn a calibration chain. The numerical fidelity of a 2D precision machine comes from the coordinate chain, the error terms and the sampling — not from richer optics. If you need super-resolution or phase retrieval, this model is the wrong tool.