Calibration and restoration

Quantitative fluorescence workflows often need several calibrations, but each calibration answers a different question. Camera maps describe detector response, a PSF describes spatial blur, and spectral controls describe channel mixing. Run each prepared example independently before connecting them to real data. Compatibility of acquisitions, units and noise models remains explicit.

flowchart TB
  D["Repeated dark and flat images"] --> C["Camera maps and signed correction"]
  B["Isolated bead image"] --> P["Measured and fitted PSFs"]
  P --> R["RL or SHB reconstruction"]
  S["Nonnegative sample image"] --> R
  U["Blank and pure controls"] --> N["Spectral matrix and NNLS images"]
Figure 1: Calibration outputs parameterize later image computations; the separate branches do not imply that their noise assumptions are interchangeable.

Camera maps from repeated frames

The camera example uses dark repeats and at least three illuminated levels. For each sensor pixel, RepeatMomentsKernel updates a mean, unbiased sample variance and count using stable repeated-frame statistics. It processes a bounded batch of frames and retains three disk-backed statistics maps between batches. Memory therefore does not grow with the total number of repeats.

CameraCalibrationKernel fits variance in ADU squared against dark-subtracted mean in ADU. The slope is inverse gain when gain is expressed as electrons per ADU. The regression has a free intercept; the measured dark variance is retained separately rather than silently forcing the fit through an assumed read-noise term. Invalid or saturated measurements reduce the usable sample count.

ApplyCameraKernel computes (sample - offset) * gain and preserves negative noise fluctuations. The output is a signed measurement, not a nonnegative estimate produced by clipping. Inspect gain, fit-quality and validity maps before using the corrected image. Dark variance includes dark-current shot noise and other temporal effects unless those are negligible; the example does not separate them automatically or estimate an illumination flat field.

cargo run --release -p blockflow-camera-calibration -- \
  prepare --out /tmp/camera-demo
cargo run --release -p blockflow-camera-calibration -- \
  run --config /tmp/camera-demo/config.json --out /tmp/camera-demo/calibrated

The prepared fixture has controlled moments and a known invalid pixel. It tests the software route; its exact recovery is not a claim about experimental precision with only a few acquired frames. Keep exposure, temperature and camera settings matched while changing illumination between calibration levels.

Fit a PSF from beads

The PSF example first builds a LoG response image and then uses BeadFitOp to fit raw source windows around isolated response maxima. Detection and fitting use different images: fitting a sharpened response would not measure the acquisition’s PSF. Each anchor is owned by one output core, while fitting and crowding tests read explicit neighborhoods across seams.

Accepted fits contribute equally after background subtraction, subpixel alignment and flux normalization. PsfAccumulator pools both measured patches and fitted Gaussian models into small summaries. The measured PSF can preserve asymmetry; the model PSF is smoother but assumes independent axis-aligned Gaussian widths. Both are finite crops, so inspect tail support and the reported model mass inside the output crop before normalizing away truncation evidence.

cargo run --release -p blockflow-psf-fit-ome-zarr -- \
  prepare --out /tmp/psf-demo
cargo run --release -p blockflow-psf-fit-ome-zarr -- \
  run --input /tmp/psf-demo/beads --out /tmp/psf-demo/fitted \
  --saturation 4095 --workers 2 --memory-mb 512

Inspect beads.csv and summary.json, not only the final PSF. A low detection threshold can add noise peaks that make good beads appear crowded. Finite bead diameter, saturated cores, insufficient windows and spatially varying optics all limit the interpretation. This is an observed bead response under a Poisson-only fit, not finite-bead correction or a camera read-noise likelihood.

Reconstruct with a finite PSF

The deconvolution example accepts either exported PSF array. Match the PSF’s sampling grid to the image; a kernel measured at a different voxel spacing does not become compatible just because it has unit sum.

The region Source and StateStore interfaces let the RL/SHB solver exchange halos for each convolution pass. With ZarrState, four scratch images retain state on disk; iteration count does not multiply a single giant input halo. This is separate from the current generic iterative executor’s resident state buffers. Boundary normalization, initialization and stopping rules are part of the reconstruction definition and are recorded by the example.

Camera-corrected negative values cannot be passed unchanged to its nonnegative observation model. Clipping is a statistical change, not an innocent storage conversion. Check the example’s input contract before joining calibration steps. For speed, compare both iteration throughput and time to a common reconstruction quality in the saved original-C benchmark.

Calibrate spectral unmixing

The unmixing example estimates a constant background per detector from blank images, then estimates unit-sum spectra from pure-component controls. NnlsModel solves a weighted, nonnegative abundance problem; NnlsKernel shares that solve across component, residual and convergence diagnostic outputs.

Detector channels must be registered within each acquisition. Different control fields can have different sizes and origins because the fitted spectrum is a small global calibration. Joint pixel selection across detectors prevents each channel’s mean from describing a different foreground population. Signed blank values remain eligible rather than biasing the offset by discarding negatives.

Inspect the matrix, clipped negative control channels, QR-factor conditioning, residual and validity outputs. Abundances are total detected signal in the supplied channel normalization, not absolute fluorophore concentration. A numerically converged fit can still have a large residual when controls are not representative or the linear mixing model is wrong.