MFX Detector Viewer - Feature Request

[lg345]

MFX Detector Viewer - Feature Request

Overview

Develop a near-time detector image analysis tool for the MFX beamline that provides interactive visualization and analysis of live PSANA-II detector data. For aligning spectrometers. In the future integrate it into shared memory optionally.

Requirements

1. Core Data Acquisition

• Connect to PSANA-II data source with configurable experiment and run number
• Support configurable detector name to view different detector types
• Real-time streaming of detector images from live experiments
• ADU (Analog-to-Digital Unit) threshold filtering with option to disable for performance
• Image accumulation/averaging over configurable number of shots
• Thread-safe data queue for background data acquisition
• Configurable timeout for PSANA connection

2. Image Display and Visualization

• 2D detector image display using PyQtGraph
• Interactive histogram-based color scaling control
• Auto-scale toggle for continuous or manual color adjustment
• Color scaling using 1st-99th percentile
• Detector boundary outline (white dashed rectangle)
• Aspect-locked display to preserve pixel aspect ratio
• Auto-range buttons for axis adjustment
• Reset color scale button

3. Region of Interest (ROI) Analysis

• Interactive ROI rectangle on image display
• Draggable and resizable ROI with handles
• Coordinate spinbox controls for precise ROI positioning
• ROI coordinate synchronization between UI controls and image display
• Bounds checking to prevent ROI from extending beyond detector edges
• Real-time ROI coordinate updates in control panel

4. Projection Analysis

• X projection plot (mean along Y axis)
• Y projection plot (mean along X axis) with right-axis positioning
• Y-axis label rotation for Y projection readability
• Auto-range controls for projection plots
• Grid display on projection plots
• Full-width X projection layout
• Side-by-side image and Y projection layout

5. Reference Trace Management

• Independent reference trace capture for X and Y projections
• Multiple reference traces with cycling color scheme
• Reference buttons above each projection plot
• Clear reference buttons for individual projection cleanup
• Visual distinction (dashed colored lines) for reference traces
• Bright color palette for reference visibility (yellow, lime, red, cyan, orange, white)
• Status messages tracking reference operations

6. User Interface

• Control panel (left side) with acquisition and analysis settings
• Visualization panel (right side) with image and projections
• Styled title with orange color (RGB 247, 130, 40) and black outline
• Color-coded autoscale checkbox (green=ON, red=OFF)
• Instructions and tips display
• Status message box with timestamped messages
• Configurable window layout and sizing

7. Configuration Options

• Experiment ID input field
• Run number spinbox with range 0-100000
• Detector name text field
• Shots to accumulate spinbox (1-1000)
• ADU threshold spinbox with zero-skip optimization
• PSANA timeout configuration
• ROI X/Y coordinate spinboxes (0-760)
• Default values preset for typical use cases

8. Status and Logging

• Real-time status message box (up to 20 messages)
• Timestamped log entries
• Acquisition state notifications
• Error message display
• Reference operation logging
• Auto-scroll to latest message

9. Performance Optimization

• Skip ADU filtering when threshold is 0
• Thread-safe queue for data handling
• ~10 Hz GUI update rate
• Non-blocking image accumulation
• Worker thread for background acquisition

10. Error Handling

• Graceful PSANA connection error handling
• Bounds checking for ROI coordinates
• Shape validation for projection data
• Thread synchronization and cleanup on exit
• Safe window close event handling

11. Code Quality

• Comprehensive docstrings for all functions and classes
• NumPy/SciPy documentation style
• Clear variable naming
• Modular method design
• Signal-slot based architecture for thread safety

12. Documentation

• README.md with feature overview
• Installation and setup instructions
• SLAC environment setup requirement
• Usage guide with configuration details
• Control descriptions
• Window layout diagram
• Tips for effective usage
• Troubleshooting guide
• Performance optimization notes

Technology Stack

• Language: Python 3.7+
• GUI Framework: PyQt5
• Plotting: PyQtGraph
• Data Processing: NumPy
• Data Source: PSANA-II
• Threading: Python threading module

Acceptance Criteria

• Application successfully connects to PSANA data source
• Real-time image display updates at ~10 Hz
• All UI controls function as designed
• ROI operations don't crash on boundary conditions
• Reference traces can be independently managed
• Status messages appear with timestamps
• Application exits cleanly without hanging threads
• Documentation is complete and accurate
• Code follows Python best practices with comprehensive docstrings

Notes

• Supports flexible detector selection for different experimental setups
• Optimized for epix100_0 detector but configurable for others
• User-friendly with visual feedback and comprehensive logging