Implement Focus Map & Global Z-Offset Correction System for Automatic Sample Tilt Compensation

[Copilot]

This PR implements a comprehensive focus map system that automatically compensates for sample tilt and stage non-planarity during experiments by applying Z-offset corrections based on XY position.

Overview

The focus map system enables automatic focus correction across large scanning areas by:

1. Calibrating focus at multiple XY positions using autofocus or manual measurements
2. Fitting a planar surface to the calibration data using least-squares regression
3. Automatically applying Z corrections during stage movements based on interpolated offsets
4. Monitoring focus lock health with real-time watchdog functionality

Key Components

FocusLockManager

• Manages focus map persistence with JSON storage per profile
• Implements 3-point plane fitting algorithm with collinearity detection
• Provides Z-offset interpolation with sub-micrometer accuracy
• Handles channel-specific Z offsets for multi-channel workflows

Configuration System

• Robust JSON-based configuration with validation and merging
• Per-profile settings with automatic migration from legacy formats
• Configurable parameters for settle timeouts, error thresholds, and move order

API Integration

• 12 new REST API endpoints across FocusLockController and ExperimentController
• Real-time signal emission via commchannel for UI integration
• Comprehensive status reporting and error metrics

ExperimentController Integration

• Automatic Z-offset application during XY stage movements
• Configurable move order (Z-first or Z-last) for different stage types
• Live focus lock integration with settled state detection
• Watchdog monitoring to abort experiments on focus lock failure

Usage Example

# Calibrate focus map
controller.start_focus_map_acquisition(grid_rows=3, grid_cols=3)
controller.add_focus_point(0, 0, autofocus=True)
controller.add_focus_point(1000, 0, autofocus=True) 
controller.add_focus_point(0, 1000, autofocus=True)
controller.fit_focus_map(method="plane")

# During experiments, Z corrections are applied automatically
# based on the fitted plane and channel-specific offsets

Testing

• 20 comprehensive unit tests with 100% pass rate
• Integration tests verify end-to-end workflows including persistence
• MockFocusLockController enables testing without hardware
• Configuration validation ensures robust parameter management

Backward Compatibility

The implementation maintains full backward compatibility with existing focus lock functionality. When hardware is unavailable, the system gracefully falls back to mock behavior, allowing continued development and testing.

Configuration

Example focus map configuration:

focuslock:
  settle_band_um: 1.0
  settle_timeout_ms: 1500
  watchdog:
    max_abs_error_um: 5.0

experiment:
  use_focus_map: true
  use_focus_lock_live: true
  z_move_order: "Z_first"
  channel_z_offsets:
    DAPI: 0.0
    FITC: 0.8
    TRITC: 1.2

This system provides automatic focus correction that is essential for high-quality imaging across large sample areas, particularly beneficial for tiling experiments and samples with significant tilt.

Fixes #168.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.