Move camera delay to waveform constants (#1245)

* Move camera delay to waveform constants

* Fix camera delay migration and reload behavior

Goal:\nComplete the camera-delay move to waveform constants without regressing legacy configurations or leaving DAQ devices on stale timing after a waveform file reload.

Root cause:\nWaveform verification considered camera.delay but not the older camera.delay_percent field. DAQBase also retained the original waveform_constants mapping even though the reload path replaces the root mapping.

Changes:\n- fall back from camera.delay to camera.delay_percent when camera_delay is missing or invalid\n- expose the existing DAQ waveform_constants attribute as a live property\n- remove obsolete camera timing fields from shipped and reference configurations\n- document millisecond units, global scope, reload behavior, migration, and legacy calibration values\n- remove the unrelated AGENTS.md ignore entry and format PR-owned test changes

Regression coverage:\nAdd tests for legacy-field precedence, delay_percent migration, shipped synthetic configuration structure, and replaced waveform mappings in base and NI DAQ implementations.

Reuse analysis:\nReuse the existing waveform_constants attribute and all current DAQ callers; no new refresh API, public resource owner, or duplicate state lifecycle is introduced.

Verification:\n- 158 focused tests passed\n- Black 22.10.0 passed on files without known baseline debt\n- git diff --check passed\n- all 11 shipped/reference YAML files parsed with no camera delay fields\n- Sphinx dummy build parsed edited pages with zero page diagnostics\n- canonical Sphinx build remains blocked by unrelated missing gui_settings_popup autosummary modules

---------

Co-authored-by: Kevin M. Dean <kevin.dean@utsouthwestern.edu>

Author: annie-xd-wang

docs/source/02_user_guide/01_supported_hardware/camera.rst

@@ -7,6 +7,11 @@ Cameras
 The software supports camera-based acquisition. It can run both normal and rolling
 shutter modes of contemporary scientific CMOS cameras.
 
+Set the camera trigger delay in
+:menuselection:`Microscope Configuration --> Waveform Parameters`. The camera
+configuration examples below describe camera hardware and acquisition settings;
+they do not set waveform timing.
+
 Driver Installation
 -------------------
 
@@ -46,7 +51,6 @@ More information on the Daheng MER2-1220-32U3C camera can be found on the
                 type: daheng.Daheng
                 serial_number: "123456"
               defect_correct_mode: 2.0
-              delay: 1.0  #ms
               settle_down: 0.1 #ms
               flip_x: False
               flip_y: False
@@ -87,7 +91,6 @@ ORCA-Flash4.0 V3
                 serial_number: 111
                 camera_connection:
               defect_correct_mode: 2.0
-              delay: 1.0  #ms
               settle_down: 0.1 #ms
               flip_x: False
               flip_y: False
@@ -117,7 +120,6 @@ ORCA-Fusion
                 serial_number: 111
                 camera_connection:
               defect_correct_mode: 2.0
-              delay: 1.0  #ms
               settle_down: 0.1 #ms
               flip_x: False
               flip_y: False
@@ -147,7 +149,6 @@ ORCA-Lightning
                 serial_number: 111
                 camera_connection:
               defect_correct_mode: 2.0
-              delay: 1.0  #ms
               settle_down: 0.1 #ms
               flip_x: False
               flip_y: False
@@ -178,7 +179,6 @@ ORCA-Fire
                 serial_number: 111
                 camera_connection:
               defect_correct_mode: 2.0
-              delay: 1.0  #ms
               settle_down: 0.1 #ms
               flip_x: False
               flip_y: False
@@ -215,10 +215,10 @@ Iris 15
                 serial_number: 111
                 camera_connection: PMPCIECam00
               defect_correct_mode: 2.0
-              delay: 1.0  #ms
               settle_down: 0.1 #ms
               flip_x: False
               flip_y: False
+
 |
 
 -----------------
@@ -241,7 +241,6 @@ MU196MR-ON
                 type: ximea.MU196XR
                 serial_number: 111
               defect_correct_mode: 2.0
-              delay: 1.0  #ms
               settle_down: 0.1 #ms
               flip_x: False
               flip_y: False
@@ -264,6 +263,7 @@ MU196MR-ON
               y_pixels: 3840
               y_pixels_min: 2
               y_pixels_step: 2
+
 |
 
 ------------------
@@ -288,7 +288,6 @@ the synthetic camera class must be used.
                 serial_number: 111
                 camera_connection:
               defect_correct_mode: 2.0
-              delay: 1.0  #ms
               settle_down: 0.1 #ms
               flip_x: False
               flip_y: False

docs/source/02_user_guide/03_user_interface_walkthrough/06_popups_and_tools.rst

@@ -91,7 +91,11 @@ Waveform Parameters
    :align: center
    :alt: Waveform Parameter Settings popup.
 
-Use this popup to configure waveform amplitudes, offsets, timing, and smoothing used by :ref:`Waveform Settings <ui_waveform_settings>`.
+Use this popup to configure waveform amplitudes, offsets, timing, and smoothing
+used by :ref:`Waveform Settings <ui_waveform_settings>`. The
+:guilabel:`Camera Delay` value is measured in milliseconds and is saved in
+``waveform_constants.yml``. It is shared by all microscope modes in the active
+configuration.
 
 Advanced Galvo Setting
 ======================

docs/source/02_user_guide/04_microscope_setup/01_software_configuration/software_configuration.rst

@@ -339,6 +339,18 @@ The ``waveform_constants.yml`` file stores waveform parameters exposed through
 Users normally do not need to edit this file manually. **navigate** updates it
 automatically during use and on exit.
 
+:guilabel:`Camera Delay` is the delay between the acquisition trigger and the
+camera trigger, in milliseconds. The value in ``waveform_constants.yml`` is
+used during acquisition and is shared by all microscope modes in the active
+configuration. Loading another waveform constants file updates the value used
+by the data acquisition device.
+
+For compatibility with older configurations, **navigate** initializes a missing
+or non-numeric ``camera_delay`` from the first configured microscope's legacy
+``camera.delay`` value, or its older ``camera.delay_percent`` value. If neither
+value exists, the default is 1 millisecond. After migration, set Camera Delay
+through the Waveform Parameters popup rather than adding it to a camera block.
+
 .. _configure_waveform_templates:
 
 Waveform Templates File

docs/source/05_reference/implementations/configurations/configuration_OPMv2.yaml

@@ -32,7 +32,6 @@ microscopes:
         type: HamamatsuOrca
         serial_number: 304064
       defect_correct_mode: 2.0
-      delay: 7.5 #ms
       settle_down: 0.0 #ms
     remote_focus_device:
       hardware:

docs/source/05_reference/implementations/configurations/configuration_OPMv3.yaml

@@ -42,7 +42,6 @@ microscopes:
         type: HamamatsuOrca
         serial_number: 001301
       defect_correct_mode: 2.0
-      delay: 10 #ms
       settle_down: 0.0 #ms
     remote_focus_device:
       hardware:
@@ -199,7 +198,6 @@ microscopes:
         type: HamamatsuOrca
         serial_number: 001301
       defect_correct_mode: 2.0
-      delay: 10 #ms
 
     remote_focus_device:
       hardware:

docs/source/05_reference/implementations/configurations/configuration_biofrontiers.yaml

@@ -15,7 +15,6 @@ microscopes:
         type: HamamatsuOrca
         serial_number: 000646
       defect_correct_mode: 2.0
-      delay: 10.0 #ms
       settle_down: 0.0 #ms
       flip_x: False
       flip_y: False

docs/source/05_reference/implementations/configurations/configuration_ctaslmv1.yaml

@@ -19,7 +19,6 @@ microscopes:
         type: HamamatsuOrca
         serial_number: 000420
       defect_correct_mode: 2.0
-      delay: 2.0 #ms
       settle_down: 0.0 #ms
       flip_x: False
       flip_y: False

docs/source/05_reference/implementations/configurations/configuration_ctaslmv2.yaml

@@ -22,7 +22,6 @@ microscopes:
       flip_x: True
       flip_y: False
       defect_correct_mode: 2.0
-      delay: 20
     remote_focus_device:
       hardware:
         type: EquipmentSolutions # NI

docs/source/05_reference/implementations/configurations/configuration_mesospimbt.yaml

@@ -19,7 +19,6 @@ microscopes:
         type: HamamatsuOrca
         serial_number: 003209
       defect_correct_mode: 2.0 #2.0
-      delay: 10 #ms
       settle_down: 0.0 #ms
       flip_x: True
       flip_y: False

docs/source/05_reference/implementations/configurations/configuration_multiscale.yaml

@@ -40,7 +40,6 @@ microscopes:
       trigger_polarity: 2.0  # positive pulse
       trigger_source: 2.0  # 2 = external, 3 = software.
       exposure_time: 20 # Use milliseconds throughout.
-      delay_percent: 10
       pulse_percent: 1
       line_interval: 0.000075
       display_acquisition_subsampling: 4
@@ -251,7 +250,6 @@ microscopes:
         type: HamamatsuOrca
         serial_number: 500502
       defect_correct_mode: 2.0
-      delay: 10 #ms
       settle_down: 0.0 #ms
 
     remote_focus_device: