# laboratoryopticsbiosciences/flute architecture

> Architecture diagram of the GitHub repository laboratoryopticsbiosciences/flute, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/laboratoryopticsbiosciences/flute
- Repository: https://github.com/laboratoryopticsbiosciences/flute

## Overview

##### Project type and purpose
- This is a Python desktop GUI application (“FLUTE”) for interactive phasor analysis of Fluorescence Lifetime Microscopy (FLIM) data.
- It loads a TIFF stack, lets users calibrate lifetimes, explore phasor plots, adjust parameters in real time, and export analysis results.

##### File structure
Top-level modules:
- main.py – application entrypoint, loads the main window UI and kicks off the Qt event loop
- Calibration.py – handles lifetime calibration routines
- DataWindows.py – manages secondary dialog windows (e.g. data entry, save dialogs)
- ImageHandler.py – loads TIFF stacks, extracts decay curves, prepares data arrays
- range_slider.py – custom slider widget for selecting phasor parameter ranges
- MplWidget.py – embeds a Matplotlib canvas in PyQt for phasor/graph plotting
UI definitions (ui files/*.ui): Qt Designer XML files for MainWindow, CalibrationWindow, Graph view, Picture view, SaveData dialog, BoundEntry, CloseWindow.

##### README for additional insights
- Built with PyQt5 (UI), NumPy/SciPy (numeric & phasor calculations), scikit-image/OpenCV (image I/O), Matplotlib (plotting)
- Supports stand-alone Windows exe via auto-py-to-exe
- Core workflow: load data → calibrate using reference fluorescein → compute phasor transform → interactive visualization → export results

##### Main components
a. UI Layer
- MainWindow (mainwindow.ui)
- CalibrationWindow
- GraphWindow (phasor plot)
- PictureWindow (image display)
- SaveData dialog / BoundEntry / CloseWindow
b. Controller / Logic Layer
- main.py orchestrates startup and signal-slot wiring
- DataWindows.py for pop-up dialogs
- Calibration.py implements calibration computations
- range_slider.py custom range selector
- ImageHandler.py for TIFF loading & data model
c. Visualization
- MplWidget.py integrates Matplotlib canvas for dynamic plotting
d. Data Persistence
- File system for input TIFF stacks
- Export module in DataWindows.py for CSV or image outputs
e. External libraries
- PyQt5 (Qt GUI framework)
- NumPy / SciPy (array math, phasor transforms)
- scikit-image / OpenCV (TIFF I/O)
- Matplotlib (plots)

##### Relationships & data flow
- User clicks “Load” in MainWindow → signal → ImageHandler loads TIFF → returns data array
- Data array → Calibration (if needed) → phasor math via SciPy → result array
- User opens SaveData dialog → DataWindows exports selected region data via NumPy → CSV/image → disk

##### Architectural patterns & design principles
- Model-View-Controller (MVC):
– Model: ImageHandler + calibration results
– View: .ui files + MplWidget visualizations
– Controller: main.py + module methods handling user actions
- Signal-Slot decoupling in Qt: GUI widgets emit signals, logic modules handle slots
- Modular separation: UI definitions (.ui) are distinct from processing logic (.py)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        MainWindow["MainWindow"]:::ui
        CalibrationWindow["CalibrationWindow"]:::ui
        GraphWindow["GraphWindow"]:::ui
        PictureWindow["PictureWindow"]:::ui
        SaveData["SaveData Dialog"]:::ui
        BoundEntry["BoundEntry Dialog"]:::ui
        CloseWindow["CloseWindow Dialog"]:::ui
    end

    %% Controller / Logic Layer
    subgraph "Controller / Logic Layer"
        MainPy["main.py"]:::processing
        DataWindows["DataWindows.py"]:::processing
        Calibration["Calibration.py"]:::processing
        RangeSlider["range_slider.py"]:::processing
        ImageHandler["ImageHandler.py"]:::processing
    end

    %% Visualization
    subgraph "Visualization"
        MplWidget["MplWidget.py"]:::processing
    end

    %% Data & Storage
    subgraph "Data & Storage"
        TIFFStack["TIFF Stack"]:::data
        ExportFile["Exported CSV/Image"]:::data
    end

    %% External Libraries
    subgraph "External Libraries"
        PyQt5["PyQt5"]:::lib
        NumPy["NumPy/SciPy"]:::lib
        SciKit["scikit-image/OpenCV"]:::lib
        Matplotlib["Matplotlib"]:::lib
    end

    %% Data & Control Flow
    User["User"]:::actor
    User --> MainWindow
    MainPy --> MainWindow
    MainWindow -->|"load TIFF"| ImageHandler
    ImageHandler -->|"data array"| Calibration
    Calibration -->|"phasor result"| MplWidget
    MplWidget -->|"display plot"| GraphWindow
    GraphWindow -->|"adjust range"| RangeSlider
    RangeSlider -->|"update plot"| MplWidget
    MainWindow -->|"open Save dialog"| DataWindows
    DataWindows -->|"export data"| ExportFile

    %% Library Dependencies
    PyQt5 --> MainWindow
    PyQt5 --> CalibrationWindow
    PyQt5 --> GraphWindow
    PyQt5 --> PictureWindow
    PyQt5 --> SaveData
    PyQt5 --> BoundEntry
    PyQt5 --> CloseWindow
    PyQt5 --> DataWindows
    NumPy --> Calibration
    NumPy --> DataWindows
    SciKit --> ImageHandler
    Matplotlib --> MplWidget

    %% Click Events
    click MainWindow "https://github.com/laboratoryopticsbiosciences/flute/blob/main/ui files/mainwindow.ui"
    click CalibrationWindow "https://github.com/laboratoryopticsbiosciences/flute/blob/main/ui files/CalibrationWindow.ui"
    click GraphWindow "https://github.com/laboratoryopticsbiosciences/flute/blob/main/ui files/Graph.ui"
    click PictureWindow "https://github.com/laboratoryopticsbiosciences/flute/blob/main/ui files/Picture.ui"
    click SaveData "https://github.com/laboratoryopticsbiosciences/flute/blob/main/ui files/SaveData.ui"
    click BoundEntry "https://github.com/laboratoryopticsbiosciences/flute/blob/main/ui files/BoundEntry.ui"
    click CloseWindow "https://github.com/laboratoryopticsbiosciences/flute/blob/main/ui files/CloseWindow.ui"
    click MainPy "https://github.com/laboratoryopticsbiosciences/flute/blob/main/main.py"
    click DataWindows "https://github.com/laboratoryopticsbiosciences/flute/blob/main/DataWindows.py"
    click Calibration "https://github.com/laboratoryopticsbiosciences/flute/blob/main/Calibration.py"
    click ImageHandler "https://github.com/laboratoryopticsbiosciences/flute/blob/main/ImageHandler.py"
    click RangeSlider "https://github.com/laboratoryopticsbiosciences/flute/blob/main/range_slider.py"
    click MplWidget "https://github.com/laboratoryopticsbiosciences/flute/blob/main/MplWidget.py"
    click User "https://github.com/laboratoryopticsbiosciences/flute/tree/main/icons/"

    %% Styles
    classDef ui fill:#D6EAF8,stroke:#2980B9,color:#154360;
    classDef processing fill:#D5F5E3,stroke:#27AE60,color:#145A32;
    classDef data fill:#FAD7A0,stroke:#D35400,color:#7E5109;
    classDef lib fill:#E5E8E8,stroke:#7B7D7D,color:#424949;
    classDef actor fill:#F2F3F4,stroke:#85929E,color:#1B2631,shape:parallelogram;
    class User actor;
```
