feat(record-zstack): Hamamatsu fps not settable — report achievable rate, read-only UI

[hongquanli]

Summary

On the Hamamatsu ORCA the continuous-mode frame rate is not settable — INTERNAL_FRAMERATE and INTERNAL_FRAMEINTERVAL are read-only in every camera state (bench-verified: DCAMERR.NOTWRITABLE). It free-runs at the exposure/readout-limited max, overlapping exposure with readout. This makes the Record + Z-Stack UI and worker reflect that, generalized via a camera capability so it composes cleanly with the ToupTek _continuous_max_framerate work already on this branch (ToupTek can set the rate via PRECISE_FRAMERATE and is untouched).

Supersedes the earlier INTERNAL_FRAMERATE-writing attempt (which produced a NOTWRITABLE ERROR at the bench and silently forced READOUTSPEED=FASTEST).

Changes

• AbstractCamera: can_set_frame_rate() (default True) + estimate_frame_rate(exposure_ms) (default sequential 1000/(exposure+strobe)).
• HamamatsuCamera:
  • can_set_frame_rate() → False.
  • set_frame_rate() reports the camera's authoritative free-run rate by reading the read-only INTERNAL_FRAMERATE — which reflects readout mode (fast/standard/ultraquiet), bit depth, ROI and exposure — falling back to the overlap estimate only if the read fails. No writes.
  • estimate_frame_rate() = overlap 1000/max(readout, exposure) (readout = INTERNAL_LINEINTERVAL × rows), for the widget's preview at a hypothetical exposure the camera isn't set to.
• Record widget: when the camera can't set fps, the fps field is read-only "≈ X fps", recomputed from the (still-editable) recording exposure — including after a YAML preset load.
• Worker: for not-settable cameras, size/pace the recording to the achievable max instead of honoring params.fps.

Testing

• camera: base/sim capability + estimate; Hamamatsu authoritative-read vs formula-fallback + overlap math (guarded on the DCAM lib — absent off-instrument, runs where DCAM exists).
• worker: recording sized to the achievable max for not-settable cameras.
• widget: fps read-only + live recompute (both max() branches) vs editable for settable cameras.
• Local run: camera 8 passed / 1 skipped, widget 87 passed, worker 26 passed. black clean.

Review

Independent review: no Critical, no Important; Minor items addressed (docstring accuracy on the capability default; refresh the read-only display after YAML load) or noted (display-only spinbox clamp at multi-second exposures). Reading INTERNAL_FRAMERATE for the actual rate resolves the reviewer's "ROI not reflected in the estimate" note for the worker path.

Off-instrument constraint

HamamatsuCamera can't be imported/run without the DCAM library, so its methods are py_compile + static-review verified here and will first execute on the ORCA. Bench check: confirm set_frame_rate returns a plausible full-frame value (~40–95 fps at short exposures) and the widget's "≈ X fps" tracks exposure.

🤖 Generated with Claude Code