Skip to content

DESIGN_PLAN.md

Latest commit

 

History

History
426 lines (353 loc) · 15.3 KB

DESIGN_PLAN.md

File metadata and controls

426 lines (353 loc) · 15.3 KB

PhasorKit Plugin - Design Plan

Project Overview

PhasorKit is a Fiji/ImageJ plugin that enables Fluorescence Lifetime Imaging Microscopy (FLIM) analysis using one of three phasor libraries through a Swing-based GUI. The plugin will delegate computations to Python via PyImageJ while focusing on a robust, SciJava-compliant frontend.

Architecture Overview

High-Level Components

┌─────────────────────────────────────┐
│   ImageJ Plugin (Java/Swing)        │
│  - PhasorKitPlugin (entry point)    │
│  - PhasorKitFrame (main GUI window) │
│  - Parameter panels                 │
│  - Result visualization             │
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│  Core Logic Layer                   │
│  - PhasorAnalyzer (orchestrator)    │
│  - ParameterValidator               │
│  - OutputHandler                    │
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│  PyImageJ Integration (Placeholder) │
│  - PythonScriptExecutor             │
│  - DataSerializer/Deserializer      │
└─────────────────────────────────────┘

Design Constraints & Principles

1. SciJava Ecosystem First

  • Use SciJava POM as parent for Maven configuration
  • Leverage scijava-common for plugin discovery and lifecycle
  • Use scijava-swing-ui for UI components where available
  • Minimize external dependencies; prefer SciJava modules

2. Minimal Dependencies

  • Core: imagej-core, imglib2, scijava-common, scijava-swing-ui
  • Avoid third-party UI frameworks (use Swing primitives)
  • External Python integration via PyImageJ (already handled by host environment)

3. Clear Separation of Concerns

  • GUI Layer: Swing components for user interaction
  • Logic Layer: Parameter validation, orchestration, result processing
  • Integration Layer: Python communication (placeholder implementation)

Feature Requirements

Input Parameters

1. Phasor Library Selection

  • Type: Dropdown/ComboBox
  • Options: PhasorPy, FlimLib, imgal
  • Scope: Global setting for the analysis session
  • UI Component: JComboBox<String>

2. Modulation Parameter

  • Type: Floating-point array or single value
  • Range: 0.0 to 1.0 (typical for FLIM)
  • Purpose: Normalize lifetime intensity
  • UI Component: JSpinner or JTextField with validation
  • Support: Per-channel configuration (future enhancement)

3. Phase Parameter

  • Type: Floating-point array or single value
  • Range: 0 to 2π (or 0° to 360°)
  • Purpose: Reference phase offset
  • UI Component: JSpinner or JTextField with validation
  • Support: Angle unit selector (radians/degrees)

4. Calibration Values

  • Modulation Calibration: Reference/background modulation correction
    • Type: Float array matching data channels
    • UI: Multi-field input panel or load from file
  • Phase Calibration: Reference phase offset correction
    • Type: Float array matching data channels
    • UI: Multi-field input panel or load from file
  • Pre-built Calibration Profiles: Drop-in presets for common microscopy setups

5. Boolean Mask Support

  • Type: Binary image (ImagePlus or RandomAccessibleInterval)
  • Source:
    • Load from ROI (Region of Interest)
    • Load from another image
    • Generate from threshold
  • Application: Restrict phasor calculation to masked regions
  • UI: Button to select/load mask, preview panel showing mask overlay

Output

  • Primary Output: G/S Phasor Array (2-channel image)
    • G channel: X-coordinate in phasor space
    • S channel: Y-coordinate in phasor space
  • Format: ImagePlus or RandomAccessibleInterval (ImgLib2 compatible)
  • Data Type: 32-bit float for precision
  • Visualization: Display in new ImageJ window with appropriate LUT

GUI Layout Design

Main Window Structure

┌──────────────────────────────────────────────────┐
│           PhasorKit FLIM Analyzer                 │
├──────────────────────────────────────────────────┤
│                                                   │
│  ┌─ Input Image Selection ──────────────────┐   │
│  │ Current Image: [Dropdown] [?]            │   │
│  └──────────────────────────────────────────┘   │
│                                                   │
│  ┌─ Phasor Library ──────────────────────────┐   │
│  │ Library: [PhasorPy ▼]                    │   │
│  └──────────────────────────────────────────┘   │
│                                                   │
│  ┌─ Phasor Parameters ───────────────────────┐   │
│  │ Modulation:     [___________] ◄─ Slider  │   │
│  │ Phase (rad):    [___________] ◄─ Spinner │   │
│  │ Phase Units:    [Radians ▼]             │   │
│  └──────────────────────────────────────────┘   │
│                                                   │
│  ┌─ Calibration ──────────────────────────────┐  │
│  │ ☐ Use Calibration                          │  │
│  │ Mod Calibration:  [Load File] [Edit]      │  │
│  │ Phase Calibration: [Load File] [Edit]     │  │
│  │ Presets: [Common Microscopes ▼]           │  │
│  └──────────────────────────────────────────┘  │
│                                                   │
│  ┌─ Mask Configuration ───────────────────────┐ │
│  │ ☐ Apply Mask                               │ │
│  │ Mask Source: [ROI ▼]   [Select]            │ │
│  │ [Preview Mask]                             │ │
│  └──────────────────────────────────────────┘ │
│                                                   │
│  [Cancel]  [Reset to Defaults]  [Advanced...] │
│  [Analyze]                                      │
│                                                   │
└──────────────────────────────────────────────────┘

Key GUI Panels

  1. ImageSelectionPanel

    • Dropdown of open ImagePlus instances
    • Display selected image dimensions/metadata
    • Help tooltips

  2. LibrarySelectionPanel

    • Radio buttons or ComboBox for library choice
    • Library-specific documentation link

  3. PhasorParametersPanel

    • Modulation slider (0.0-1.0) with numeric input
    • Phase spinner with angle unit toggle
    • Preset manager for common values

  4. CalibrationPanel

    • Checkbox to enable/disable calibration
    • File picker for calibration data (CSV/text format)
    • Inline editor for calibration arrays
    • Preset profiles dropdown

  5. MaskPanel

    • Checkbox to enable/disable mask
    • Dropdown: ROI, Image, Threshold
    • Preview button showing mask overlay
    • Invert mask option

  6. ControlPanel

    • Cancel, Reset, Advanced Settings, Analyze buttons
    • Progress bar (for long-running analyses)

Class Structure & Design Patterns

Core Classes

// Main plugin entry point
public class PhasorKitPlugin implements Command {
    // Handles plugin initialization and command execution
}

// Main GUI window
public class PhasorKitFrame extends JFrame {
    private PhasorAnalyzer analyzer;
    private ImageSelectionPanel imagePanel;
    private LibrarySelectionPanel libraryPanel;
    private PhasorParametersPanel paramsPanel;
    private CalibrationPanel calibrationPanel;
    private MaskPanel maskPanel;
}

// Orchestrator for analysis logic
public class PhasorAnalyzer {
    public void analyze(AnalysisParameters params) throws Exception;
    public void validateParameters(AnalysisParameters params) throws ValidationException;
}

// Container for all user inputs
public class AnalysisParameters {
    private ImagePlus sourceImage;
    private PhasorLibrary selectedLibrary;
    private float modulation;
    private float phase;
    private boolean useCalibration;
    private CalibrationData calibration;
    private boolean useMask;
    private ImagePlus maskImage;
    
    // Getters, setters, validation methods
}

// Enumeration for supported libraries
public enum PhasorLibrary {
    PHASORPY("PhasorPy"),
    FLIMLIB("FlimLib"),
    IMGAL("imgal");
}

// Calibration data container
public class CalibrationData {
    private float[] modulationCalibration;
    private float[] phaseCalibration;
    
    // Methods to load from file, validate
}

// Parameter validation
public class ParameterValidator {
    public static ValidationResult validate(AnalysisParameters params);
}

// Output handling
public class OutputHandler {
    public static void displayPhasorResult(
        float[][] gChannel, 
        float[][] sChannel,
        String title
    );
}

// Python integration (placeholder)
public class PythonScriptExecutor {
    public float[][] executePhasorAnalysis(
        float[][] inputData,
        AnalysisParameters params
    ) throws PyImageJException;
    // Implementation details deferred
}

Design Patterns Used

  • MVC Pattern: Separate GUI (View) from data (Model) and logic (Controller)
  • Builder Pattern: For constructing complex AnalysisParameters
  • Singleton Pattern: For PhasorAnalyzer (single instance per plugin)
  • Strategy Pattern: Different calibration strategies (none, preset, custom)
  • Observer Pattern: For panel state changes and progress updates

Data Flow

Typical User Workflow

1. User opens image in ImageJ
   ↓
2. Launch PhasorKit plugin
   → GUI window appears with defaults
   ↓
3. User selects parameters via GUI panels
   ↓
4. User clicks "Analyze"
   ↓
5. ParameterValidator.validate() checks inputs
   ↓
6. PhasorAnalyzer.analyze() called
   ↓
7. PythonScriptExecutor sends data to Python
   ↓
8. Python library computes phasor values
   ↓
9. G/S arrays returned to Java
   ↓
10. OutputHandler displays result in new ImageJ window
    ↓
11. User can save/process results further

Implementation Phases

Phase 1: Foundation (Critical Path)

  • Project structure with SciJava POM
  • Plugin entry point and basic GUI frame
  • Image selection panel
  • Library selection panel
  • Basic parameter input panels (modulation/phase)
  • Parameter validation framework

Phase 2: Core Features

  • Calibration panel and data handling
  • Mask support panel
  • Advanced settings dialog
  • PythonScriptExecutor placeholder
  • OutputHandler and result visualization

Phase 3: Polish

  • Help/documentation tooltips
  • Preset profiles for calibration
  • Progress feedback during analysis
  • Error handling and user-friendly messages
  • Unit tests for validation logic

Technical Considerations

Maven/POM Configuration

  • Parent: org.scijava:pom-scijava
  • Key dependencies: 
    <imagej.version>2.x.x</imagej.version>
<scijava-swing-ui.version>latest</scijava-swing-ui.version>

ImgLib2 Integration

  • Use RandomAccessibleInterval for image data internally
  • Convert to/from ImagePlus at boundaries
  • Float32 for precision in phasor calculations

Error Handling

  • Custom exceptions: PhasorAnalysisException, ValidationException
  • User-facing error dialogs via JOptionPane
  • Logging via SciJava logging (if available)

Testing Strategy

  • Unit tests for ParameterValidator
  • Unit tests for CalibrationData loading
  • Integration tests for full workflow (deferred until Python layer available)

Future Enhancements (Out of Scope for MVP)

  • Multi-channel support with per-channel calibration
  • Batch processing of multiple images
  • Phasor space visualization with fluorophore reference points
  • Advanced ROI-based masking (irregular shapes)
  • Export results to HDF5 or NetCDF
  • Integration with OMERO for remote data

Questions for Discussion

  1. Calibration File Format: Should we use CSV, plain text, or a custom format?
  2. Multi-Channel Handling: Should the MVP support multi-channel FLIM data?
  3. Output Display: Should we show the phasor space (G vs S plot) in addition to the arrays?
  4. Undo/History: Should users be able to undo/redo analyses within a session?
  5. Batch Processing: Is batch processing a requirement, or future work?
  6. Unit Preferences: Should angle units be a global preference or per-image?

File Structure

phasorkit/
├── pom.xml
├── README.md
├── DESIGN_PLAN.md
├── src/
│   ├── main/
│   │   ├── java/org/scijava/phasorkit/
│   │   │   ├── PhasorKitPlugin.java
│   │   │   ├── gui/
│   │   │   │   ├── PhasorKitFrame.java
│   │   │   │   ├── panels/
│   │   │   │   │   ├── ImageSelectionPanel.java
│   │   │   │   │   ├── LibrarySelectionPanel.java
│   │   │   │   │   ├── PhasorParametersPanel.java
│   │   │   │   │   ├── CalibrationPanel.java
│   │   │   │   │   └── MaskPanel.java
│   │   │   │   └── dialogs/
│   │   │   │       └── AdvancedSettingsDialog.java
│   │   │   ├── model/
│   │   │   │   ├── AnalysisParameters.java
│   │   │   │   ├── CalibrationData.java
│   │   │   │   ├── PhasorLibrary.java
│   │   │   │   └── ValidationResult.java
│   │   │   ├── analyzer/
│   │   │   │   ├── PhasorAnalyzer.java
│   │   │   │   ├── ParameterValidator.java
│   │   │   │   └── OutputHandler.java
│   │   │   └── python/
│   │   │       └── PythonScriptExecutor.java
│   │   └── resources/
│   │       ├── scripts/
│   │       │   └── (Python scripts - placeholders)
│   │       └── help/
│   │           └── (Documentation)
│   └── test/
│       └── java/org/scijava/phasorkit/
│           └── (Unit tests)
└── target/