Add uiPSF calibration plugin for learning PSF models

[jries]

Summary

Adds Localize/uiPSF calibration, a plugin that uses uiPSF (Liu et al. 2024) to learn a PSF model. It learns from bead z-stacks or from the blinking molecules of an acquisition (in situ), in one channel or two (split camera). The result is saved as an ordinary smappy calibration file, which Spline 3D and Spline 3D 2C read unchanged; uiPSF's own result is saved beside it.

uiPSF is optional and not installed by smappy. It runs in a Python environment of its own; the plugin's page explains how to set one up.

Merge ries-lab/uiPSF#17 first. The page's install instructions clone uiPSF's main, and only with #17 merged does main install on Python 3.12 / current TensorFlow (numpy 2, macOS). An existing environment made from uiPSF's main before #17 also works.

Changes

• smappy.uipsf

  • prepare: reads the data and converts it to photons. Cuts a split camera into its channels, recording exactly how. Subtracts each bead stack's median, because uiPSF's bead threshold includes the background. Measures the channel shift by cross-correlation, because uiPSF's own guess pairs neighbours on a regular bead grid.
  • microscopes: YAML microscope profiles (NA, refractive indices, wavelength, splitter, starting pupil, any uiPSF parameter). They are read from $SMAPPY_MICROSCOPES, <config dir>/microscopes, then the shipped example.
  • uipsf_parameters: the profile and the settings as uiPSF's configuration.
  • runner + worker.py: uiPSF runs as a subprocess under its own interpreter. The worker imports nothing of smappy's. They talk through a job folder and tagged stdout, and the progress bars are passed on. The worker also sets the measured channel shift on uiPSF's class, so uiPSF needs no new parameter.
  • convert: uiPSF's voxel model is clipped, normalised and splined as smappy's bead calibration does it. Two channels are normalised jointly. uiPSF's T is refitted as smappy's secondary → main projective map in chip pixels. In situ models are reversed and zeroed at the nominal focal plane.
  • plots: uiPSF's notebook diagnostics as result tabs: data vs model, localization bias, pupil, a Zernike bar chart, beads/emitters used, and the channel transformation's residuals.

• Plugin (plugins/uipsf.py) and its page, which includes installing uiPSF.

• tests/test_uipsf.py: conventions checked on hand-written uiPSF files:

  • z sign and zero for bead and in situ models;
  • the split geometry for all four layouts;
  • T → transformation;
  • joint normalisation;
  • the channel shift on a bead grid;
  • every result tab drawn as the window draws it;
  • the runner protocol.

  With SMAPPY_UIPSF_PYTHON set, one test also runs uiPSF itself and fits the result back with Spline 3D.

• test_workspace lists the new Localize plugin. CLAUDE.md gains a plugin-shape row and two test notes. NOTES.md has a "uiPSF calibrations" section with the decisions and measurements. The example profile ships in data/microscopes.

Results on simulated data (4 CPU cores, TensorFlow 2.21)

	time	result
beads, one channel	~3 min	Spline 3D fit: z slope 1.03, intercept 2 nm
beads, two channels	~10 min	transformation within 0.02 px of the true one; photon split 0.499/0.501 (true 0.5); Spline 3D 2C: z slope 1.015, colour ratio exact
blinking, one channel	~12 min	right z sign and zero, but z scale 0.76 and photons +10%; sensitive to the starting pupil

On the old stack (TensorFlow 2.9.1, numpy 1.23.5), the worker drove uiPSF's main before #17 through all three kinds of job, with results bit-identical to #17's branch.

In situ is not validated. The page says to check an in situ model against a bead calibration of the same microscope. Not tried end to end: a mirrored splitter with uiPSF (the geometry is unit-tested), two-channel in situ, real data, Windows, and macOS.

--slow -n auto: 1346 passed, 4 skipped (with SMAPPY_UIPSF_PYTHON set, so the uiPSF test ran). The last commit changes only the page's install line and NOTES.md; the page and uiPSF tests pass on it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GiNdULxyiqQEqWHGKTbVzV