csaxs_bec/docs/developer/lamni_smear_architecture.md

(developer.lamni_smear_architecture)=

LamNI smear rotation-center aid: architecture notes

The experimental continuous-rotation "smear" calibration aid (see {ref}the user-facing description <user.ptychography.lamni>) touches all three layers of a typical BEC GUI feature — a device, an ipython-client plugin, and a GUI widget — running as three separate processes talking over BEC's Redis-backed message bus. It's a useful worked example for how those layers connect, and it surfaced a couple of non-obvious pitfalls worth documenting so the next person doesn't have to re-discover them.

The three tiers

Three separate processes, connected over BEC's Redis-backed message bus:

ipython client (XrayEyeAlign, LamNI)
    │
    ├── device RPC ──────► IDSCamera / SimIDSCamera  (device server process)
    │   dev.cam_xeye.push_smear_preview(...)                │
    │                                                       │ image / smear_preview
    │                                                       │ PreviewSignal (pub/sub)
    │                                                       ▼
    └── widget RPC ──────► XRayEye widget            (GUI server process)
        self.gui.set_live_view_signal(...)

• IDSCamera (csaxs_bec/devices/ids_cameras/ids_camera.py, simulated counterpart csaxs_bec/devices/sim/sim_cameras.py) runs in the device server process and owns the actual camera hardware (or its simulation).
• XrayEyeAlign / LamNI (csaxs_bec/bec_ipython_client/plugins/LamNI/) run in the operator's ipython client process and orchestrate the calibration procedure — rotating the sample, grabbing frames, driving the GUI.
• XRayEye (csaxs_bec/bec_widgets/widgets/xray_eye/x_ray_eye.py) is a Qt widget running in its own GUI server process, displaying the live image and collecting the operator's click.

Devices and widgets each expose a USER_ACCESS list of methods callable remotely; the ipython client reaches them as dev.cam_xeye.<method>(...) and self.gui.<method>(...) respectively. Image data itself flows over a separate publish/subscribe channel (PreviewSignal), not through those RPC calls.

Camera interface: two preview channels

IDSCamera exposes two PreviewSignal components:

• image — the live-acquisition channel. A background thread (_live_mode_loop) continuously grabs frames and put()s them here at ~5 Hz while live_mode_enabled is True. Configured per-device with num_rotation_90/transpose (e.g. num_rotation_90=3 for cam_xeye), applied automatically inside PreviewSignal.put().
• smear_preview — a second, independent channel, added for this feature, with no rotation/transpose configured. Nothing else writes to it, so publishing here never races with the live thread.

PreviewSignal (and every BECMessageSignal subclass) has rpc_access hardcoded off, so it is not reachable as a plain attribute from client code — dev.cam_xeye.image.put(...) raises AttributeError even though the signal exists on the real device. The supported pattern is a plain device method that does the .put() server-side, where the signal is a normal ophyd attribute:

• get_last_image() — read side; returns self.image.get().data, i.e. already display-oriented (rotation/transpose already applied by whichever .put() call stored it).
• push_preview_image(data) — write side for image. Since data built from get_last_image() frames has already been transformed once, this method undoes the transform first so self.image.put()'s own transform doesn't apply it a second time (compensation is reverse-order: transpose first, then rotate by -num_rotation_90).
• push_smear_preview(data) — write side for smear_preview. No compensation needed or applied, since that channel has no transform configured.

Why two channels, not one: the first working version pushed composites through push_preview_image (the image channel), which meant briefly setting live_mode_enabled = False around every push so the live thread couldn't immediately overwrite the composite, then setting it back to True afterward. That's instant in simulation, but on real hardware toggling live_mode_enabled starts/stops the actual acquisition thread and has real, non-trivial latency — repeated dozens of times over a sweep, this was the dominant cost and showed up as the GUI's "camera running" indicator visibly flapping. Giving the composite its own channel means live_mode_enabled is never toggled during a sweep at all — it's set to True once at the start (if not already), exactly like the production _live_sweep(), and left alone.

GUI interface: switching the displayed channel

XRayEye.set_live_view_signal(signal="image") switches which (device, signal) pair the widget's Image view is subscribed to (via the same image()/disconnect_monitor() calls on_live_view_enabled() already used, now parameterized instead of hardcoded to "image"). Every freshly constructed XRayEye defaults to "image", so opening the GUI or running any other alignment routine is unaffected unless something explicitly calls set_live_view_signal("smear_preview").

The smear sweep (XrayEyeAlign._smear_sweep) switches to "smear_preview" at the start and pushes composite updates there as the rotation progresses — but deliberately does not switch back to "image" itself on a successful return. The composite has to stay on screen until the operator's click has actually been collected (find_rotation_center_smear_experimental switches back right after _collect_click() returns); switching back inside _smear_sweep() would show the operator a live raw frame instead of the composite at exactly the moment they need to click on it. On KeyboardInterrupt mid-sweep there's nothing to click on, so that path switches back to "image" immediately — both inside _smear_sweep()'s own handler and, as a second safety net, in lamni.py's top-level except KeyboardInterrupt in case the interrupt lands after the sweep but before the click completes.

How the sweep itself works

_smear_sweep() rotates continuously and accumulates frames without stepping the motor:

1. scans.mv(dev.lsamrot, target) (the file's mv() wrapper, sibling of the existing blocking umv()) issues the rotation non-blocking — it returns a ScanReport immediately rather than waiting for the move to finish.
2. A plain loop polls report.status (exactly what ScanReport.wait() does internally) and, while it isn't "COMPLETED", grabs a frame via get_last_image() and folds it into a running np.maximum composite — all single-threaded, since the rotation is progressing concurrently on the server regardless of what the client does between polls.
3. Every display_update_interval_s, the current composite is pushed to smear_preview so the operator watches it grow; off-axis features trace arcs as the sample turns, and the common center of curvature of those arcs is the rotation axis.
4. Once the move completes, a final push leaves the finished composite displayed, the shutter is closed (unless keep_shutter_open), and the operator submits a click — reusing the exact same _collect_click() / _compute_shift_to_fzp() / _apply_rotation_center_shift() machinery and cumulative-shift accounting as the production ..._extended() path.

Pitfall: regenerate the RPC client stub after changing USER_ACCESS

:::{important} Whenever you add or rename a method in a plugin widget's USER_ACCESS list (e.g. XRayEye.USER_ACCESS in x_ray_eye.py), you must run:

bw-generate-cli --target csaxs_bec

and commit the resulting changes to csaxs_bec/bec_widgets/widgets/client.py (and designer_plugins.py). Skipping this step does not raise an error at import time or widget-construction time — it fails much later, and confusingly, as an AttributeError raised from deep inside bec_widgets's RPC plumbing, even after fully restarting both the ipython client and the GUI server process. :::

The reason: csaxs_bec/bec_widgets/widgets/client.py is a checked-in generated file containing one RPC stub class per plugin widget, mirroring its USER_ACCESS at the time bw-generate-cli was last run. The ipython client's BECGuiClient._add_widget() resolves a widget's class by name lookup against that generated module (getattr(client, state["widget_class"], None)) — not by dynamically importing the real widget class — so a stale generated file means the new method genuinely doesn't exist anywhere the client can find it, no matter how fresh the actual XRayEye class on disk is. This is exactly the same kind of generated-stub step core bec_widgets widgets also need (their generated file lives in the bec_widgets package itself); plugin widgets just have their own copy living inside csaxs_bec.