From a23e9557a9a1bdcac81eaf587c01f9ce3869a7d2 Mon Sep 17 00:00:00 2001 From: x01dc Date: Mon, 13 Jul 2026 21:58:00 +0200 Subject: [PATCH] docs(flomni): clarify hook re-registration and the two acquisition methods Two additions to the at_each_angle hook writeup: registering a hook stores the function object at that moment, not a live link to its name, so editing the function later requires calling register_at_each_angle_hook() again -- redefining it alone does nothing. And tomo_scan_projection()/tomo_acquire_at_angle() are not interchangeable (Fermat vs single-point); the example hook now calls tomo_scan_projection() plainly (no more confusing _internal=True in user-facing code) with a clear note on when to use the other one instead, matching the new CLI/GUI warnings. Co-Authored-By: Claude Sonnet 5 --- docs/user/ptychography/flomni.md | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/user/ptychography/flomni.md b/docs/user/ptychography/flomni.md index 37bae2d..fd3d8da 100644 --- a/docs/user/ptychography/flomni.md +++ b/docs/user/ptychography/flomni.md @@ -416,12 +416,16 @@ selected per tomo-queue job, so the whole modulated tomogram runs unattended alo with any other queued jobs. A hook is a function `func(flomni, angle)`, called once per projection angle instead -of the normal acquisition: +of the normal acquisition. Acquire the actual projection(s) inside it the same way +`tomo_scan()` would on its own — `tomo_scan_projection(angle)` for a normal +(Fermat-scan) measurement, or `tomo_acquire_at_angle(angle)` if `tomo_parameters()` +has single-point mode enabled for this job (see the warning below for why it matters +which one you call): ```python def polarizer_modulation(flomni, angle): - flomni.tomo_scan_projection(angle, _internal=True) + flomni.tomo_scan_projection(angle) umv(dev.polarizer, "in") - flomni.tomo_scan_projection(angle, _internal=True) + flomni.tomo_scan_projection(angle) umv(dev.polarizer, "out") ``` @@ -459,6 +463,22 @@ clear error rather than silently running a plain scan; re-run `register_at_each_angle_hook()` for that hook, then call `tomo_queue_execute()` again to resume. +**Editing a hook after registering it:** `register_at_each_angle_hook()` stores +whichever function object you pass it at that moment — it is not a live link to the +function's name. If you edit the function's source and re-run the `def` in your +session but do **not** call `register_at_each_angle_hook()` again, the *old* version +keeps running. Always re-register after an edit. + +**`tomo_scan_projection()` vs `tomo_acquire_at_angle()`:** these are not +interchangeable. `tomo_scan_projection(angle)` always runs a full Fermat-scan +projection; `tomo_acquire_at_angle(angle)` always runs a single-point acquisition. +Use whichever matches how `tomo_parameters()` has this job configured +(`single_point_instead_of_fermat_scan`) — calling the wrong one for the job's mode +produces the wrong kind of data, and calling `tomo_scan_projection()` directly while +single-point mode is on prints a warning and asks for confirmation, which will hang +an unattended queue run. Both `flomni.tomo_parameters()` (CLI) and the params panel +(GUI) show a reminder of which one to use whenever single-point mode is enabled. + **GUI:** the tomo parameters panel has an "At-each-angle hook" dropdown, listing whatever is currently registered from the CLI (`register_at_each_angle_hook()`) — the GUI process can't register hooks itself, only select one by name for the job