Enhance StageOffset calibration with dedicated calibration target support

[Copilot]

This PR significantly enhances the StageCenterCalibrationController to support advanced calibration workflows using a dedicated calibration target PCB for the FRAME microscope system. The implementation addresses all requirements specified in the issue for improving stage calibration accuracy and user experience.

Key Features Added

1. Manual Calibration with Known Positions

• New setKnownPosition(x_mm, y_mm) endpoint for manual calibration to known coordinates
• Defaults to calibration center at (63.81mm, 42.06mm) as specified in the calibration target
• Integrates with existing PositionerManager.setStageOffsetAxis() for persistent offset storage

2. Automatic Calibration with Computer Vision

• performAutomaticCalibration(laser_name, laser_intensity) endpoint with full automation:
  • Stage homing in X/Y axes
  • Movement to 30mm offset position
  • White line detection using OpenCV Hough line transform
  • Ring detection and centering using Hough circle transform
  • Automatic laser control with configurable intensity

3. Calibration Target Visualization

• getCalibrationTargetInfo() returns comprehensive target information including:
  • SVG drawings for both frontside and backside (127.76mm × 85.48mm)
  • All key coordinate positions and dimensions
  • Visual representation of calibration features

4. Specialized Calibration Patterns

Maze Navigation

• startMaze(), stopMaze(), getMazeStatus() for maze pattern navigation
• Starts at (9.5mm, 11.5mm) with 1000µm steps as specified
• Customizable path with default square pattern
• Real-time image capture and TIFF stack generation

Stepsize Calibration

• performStepsizeCalibration() for 7×7 hole lattice scanning
• Located at (105mm, 16mm) with 1mm spacing
• Automated image capture for step size analysis
• Now fully threaded and cancellable for better performance

384 Wellplate Calibration

• perform384WellplateCalibration() for backside wellplate pattern
• Supports standard 384-well format (A1-P24)
• Configurable well sampling with intelligent coordinate parsing
• Backside pattern at (12.2mm, 9.0mm) with 4.5mm spacing

Technical Implementation

Image Processing Pipeline

• OpenCV integration for robust computer vision
• Hough line transform for white line detection
• Hough circle transform for ring centering
• Configurable edge detection and filtering parameters

Data Management

• TIFF stack generation for all calibration sequences
• CSV position logging with timestamps
• Organized file structure in ~/imswitch_calibrations/
• JSON metadata for wellplate information

Robust Error Handling

• Hardware availability checking (stage, detector, laser)
• Graceful degradation when components unavailable
• Comprehensive status reporting with detailed error messages
• Thread-safe operations for long-running calibrations

Configuration System

• New stageCalibration configuration section supporting:
  • Configurable calibration target dimensions and positions
  • Adjustable home positions (no longer FRAME-specific hardcoded values)
  • Customizable speeds, spacings, and grid parameters
  • All constants now have sensible defaults while supporting system-specific overrides

Enhanced Movement Control

• Configurable movement speed via speed_um_s parameter in calibration APIs
• Continuous movement mode for spiral scans with real-time frame collection during motion
• Improved threading architecture with proper state management and cancellation support

API Design

All new endpoints follow established ImSwitch patterns:

• @APIExport() decorators for REST API exposure
• Consistent return format with status and data
• Optional parameters with sensible defaults
• Non-blocking operation with status monitoring

Testing and Validation

• Comprehensive test suite with 7 test functions covering all endpoints
• Coordinate calculation validation for all calibration patterns
• SVG generation testing with visual output verification
• Image processing validation with synthetic test data
• Error handling verification for edge cases

Code Quality Improvements

• Resolved all TODO items in the codebase:
  • Fixed coordinate system conversion between motor steps and physical units
  • Eliminated redundant threading wrapper methods
  • Added proper configuration support for hardware-specific parameters
  • Enhanced spiral search with background movement and speed control

Example Usage

# Manual calibration to known position
result = controller.setKnownPosition()  # Uses default center

# Automatic calibration with laser and custom speed
result = controller.performAutomaticCalibration(
    laser_name="405nm", 
    laser_intensity=25.0
)

# Spiral search with custom speed
result = controller.findCalibrationCenter(
    speed_um_s=15000  # Custom movement speed
)

# Get calibration target information
target_info = controller.getCalibrationTargetInfo()
print(f"Target: {target_info['width_mm']}×{target_info['height_mm']}mm")

# Run maze navigation
controller.startMaze()
status = controller.getMazeStatus()
controller.stopMaze()

The implementation maintains full backward compatibility with existing spiral calibration functionality while adding powerful new capabilities for precise stage calibration using the dedicated calibration target. The enhanced architecture provides better performance, configurability, and maintainability.

Fixes #153.

---

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

[beniroquai]

@copilot please continue working on the TODOs

[Copilot]

@copilot please continue working on the TODOs

I've addressed all the TODO items in the StageCenterCalibrationController:

✅ Configuration Support - Made FRAME-specific constants configurable through a new stageCalibration config section with sensible defaults
✅ Fixed setStageOffsetAxis - Corrected unit conversion between motor steps and physical coordinates (µm)
✅ Removed Redundant Interface - Eliminated the unnecessary _findCalibrationCenterForThread wrapper method
✅ Threaded Stepsize Calibration - Made performStepsizeCalibration threaded and cancellable
✅ Enhanced Spiral Scan - Added configurable speed parameter and continuous movement with frame collection during motion

The implementation now properly separates threading concerns, supports configuration customization, and provides better performance with background movement analysis. All changes maintain backward compatibility while significantly improving the calibration system architecture.

Commit: 1d7a1da