Integrate useq-schema MDASequence with ImSwitch ExperimentController

[Copilot]

This PR integrates the useq-schema standard for multi-dimensional acquisition protocols with ImSwitch's ExperimentController, providing a modern, software-agnostic interface for designing microscope workflows.

Overview

The useq-schema provides a standardized way to define complex microscopy experiments including time-lapse, Z-stacks, multi-channel imaging, and multi-position acquisitions. This integration allows ImSwitch users to leverage this established standard while maintaining full compatibility with the existing workflow system.

Key Features

MDASequenceManager

• Converts useq.MDASequence objects into ImSwitch WorkflowStep objects
• Supports complex multi-dimensional experiments (time × position × Z × channels)
• Provides sequence analysis and duration estimation
• Graceful handling when useq-schema is not available

New API Endpoints

• GET /api/experimentcontroller/get_mda_capabilities - Check available MDA features
• POST /api/experimentcontroller/start_mda_experiment - Execute MDA protocols
• POST /api/experimentcontroller/get_mda_sequence_info - Preview experiments without execution

Example Usage

import requests

# Define a multi-dimensional experiment
experiment = {
    "channels": [
        {"name": "DAPI", "exposure": 50.0, "power": 100.0},
        {"name": "FITC", "exposure": 100.0, "power": 80.0}
    ],
    "z_range": 10.0,      # 10 μm Z-stack
    "z_step": 2.0,        # 2 μm steps
    "time_points": 5,     # 5 timepoints
    "time_interval": 30.0, # Every 30 seconds
    "experiment_name": "My_MDA_Experiment"
}

# Start the experiment
response = requests.post(
    "http://localhost:8000/api/experimentcontroller/start_mda_experiment",
    json=experiment
)

Implementation Details

Each MDAEvent from a useq sequence is converted into multiple workflow steps:

1. Stage positioning (XY and Z movements)
2. Illumination setup (channel selection and power)
3. Camera configuration (exposure settings)
4. Image acquisition
5. Illumination cleanup (turn off lights)

This ensures seamless integration with ImSwitch's existing hardware control architecture.

Benefits

• Standardization: Uses the established useq-schema standard adopted by the microscopy community
• Software Agnostic: Protocols can be shared between different acquisition systems
• Rich Validation: Automatic parameter validation and error checking
• Backward Compatible: Existing ImSwitch functionality remains unchanged
• Future Proof: Built on actively maintained, modern Python libraries

Testing

Comprehensive validation includes:

• Multi-channel Z-stack experiments (verified 24 events for 3 channels × 4 Z-positions × 2 timepoints)
• Time-lapse imaging protocols
• Multi-position acquisition patterns
• API parameter validation and error handling
• Interactive demo script for easy testing (examples/mda_demo.py)

Documentation

• Complete API documentation with examples (docs/mda_integration.md)
• Interactive demo script with multiple experiment types
• Migration guidance for users transitioning from existing workflows

This integration addresses the need for a modern, standardized approach to microscopy workflow design while preserving the flexibility and power of ImSwitch's existing experiment system.

Fixes #144.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.