feat(gui): host-computed phase-contrast annulus with per-configuration rings

[hongquanli]

What

Host side of the host-programmable LED matrix: a Phase Contrast tab that computes an annular illumination pattern in Python and drives it through the programmable LED-matrix source. Because the pattern is computed on the host, the ring can be tuned — and new patterns added — with no firmware reflash.

Requires #623 (firmware) to be flashed — this PR targets illumination source 10, added there. Files are disjoint (host-only), so they can merge in either order, but both must land for the feature to run.

Changes

Protocol (_def.py, microcontroller.py)

• Mirror the firmware commands: SET_ILLUMINATION_LED_MATRIX_PIXEL (45), CLEAR_ILLUMINATION_LED_MATRIX (46), ILLUMINATION_SOURCE_LED_ARRAY_PROGRAMMABLE (10).
• set_illumination_led_matrix_pixel / clear_illumination_led_matrix, and set_illumination_led_matrix_frame(frame) to push a full 128-LED frame (clear + non-black pixels), using the same R/G order and scaling as set_illumination_led_matrix.

GUI (widgets.py, gui_hcs.py, live_controller.py)

• New Phase Contrast tab (LedMatrixRingWidget) computes a 128-LED annulus frame and hands it to the live controller, which sends it per-pixel and selects the programmable source.
• Ring is specified by inner/outer diameter in pixels (LED pitches), with inner constrained ≤ outer. Ring type (full / 180° half), direction, and color are selectable; intensity comes from the channel's own live-view slider.
• Per-configuration settings: a selector lists the imaging configurations that use the programmable source; each keeps its own ring, persisted to cache/phase_contrast_annulus_settings.json. get_frame(intensity, channel_name) reads stored settings by name (plain data, not Qt widgets), so live view and wellplate multipoint acquisition both use the correct ring for whichever configuration is imaging — thread-safe from the acquisition worker.
• live_controller routes the programmable source through the widget frame and includes source 10 in _is_led_matrix; gui_hcs adds the tab and auto-follows the active live configuration.

Required machine config (not in this PR)

The annulus imaging channel and its port mapping live in machine_configs/ + user_profiles/, which are gitignored (per-machine). To enable the feature on a device, add:

machine_configs/illumination_channel_config.yaml — map a free controller port to source 10, and add the channel:

controller_port_mapping:
  USB6: 10          # any UNUSED port; must match ^(D[1-8]|USB[1-8])$ (USB9 is rejected)
channels:
  - name: Phase contrast annulus
    type: transillumination
    controller_port: USB6
    wavelength_nm: null
    intensity_calibration_file: null

user_profiles/<profile>/channel_configs/general.yaml — add the imaging channel (merges into every objective):

- name: Phase contrast annulus
  enabled: true
  display_color: '#FFFFFF'
  z_offset_um: 0.0
  camera_settings: {exposure_time_ms: 20.0, gain_mode: 10.0}
  illumination_settings:
    illumination_channel: Phase contrast annulus   # MUST equal the name above
    intensity: 20.0

Any imaging configuration whose illumination_channel resolves to source 10 appears in the tab's selector and gets its own ring.

Testing

• Host compiles; launched against a Teensy flashed with feat(firmware): host-programmable per-pixel LED matrix framebuffer #623. Verified the "Phase contrast annulus" configuration paints the ring in live view and applies the correct per-configuration ring during acquisition. Ring geometry checked numerically (default 6→8 px lights the expected 20-LED ring; half-ring lights exactly half).