From bf201d6afb7ece989f0d7a291ec2fc3458cbc2cf Mon Sep 17 00:00:00 2001 From: jack Date: Thu, 25 Jun 2026 13:51:01 -0700 Subject: [PATCH] update readme --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b44c13e..481189e 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,36 @@ Small PySide6 + Qt Quick application scaffold for the `ISenseCloud` desktop UI shell. +## Key App Features + +The `ISenseCloud` application provides a real-time monitor and analysis dashboard for silicon wafer temperature profiles: + +- **Real-Time Data Streaming & Coalescing**: Decodes binary frame streams from thermal sensors over serial/COM connections at ~20 Hz with low CPU overhead. +- **RBF Heatmap Interpolation**: A Radial Basis Function (RBF) interpolation engine paints a smooth 2D temperature gradient across the wafer surface based on physical sensor locations. +- **Interactive Review & Playback**: A `FramePlayer` component supports variable-speed playback (play, pause, step, seek) of recorded runs. +- **Interactive Trend Charts**: Renders multi-series temperature trends using a custom QtQuick painted item (`GraphQuickItem`) with automatic scaling, custom legends, and grid layouts. +- **Tabular Data Inspection**: Direct inspection of tabular dataset grids for frame-by-frame diagnostic checkups. +- **Custom Safety Limits & Thresholds**: Configurable alarm thresholds and set-points with automatic alerts when temperatures diverge from normal boundaries. + +### App Showcase +![ISenseCloud UI displaying successful connection on COM6](image-1.png) +*Figure 1: Main Status Dashboard displaying successful connection, active serial communications, and automated logging terminal.* + +> [!NOTE] +> **Take Screenshots for Visual Placeholders:** +> - **Wafer Heatmap Tab**: Take a screenshot of the Wafer Map tab showing the radial heatmap interpolation, save it to `docs/design/wafer_heatmap_tab.png` and add it here. +> - **Temperature Trend Graph**: Take a screenshot of the Graph tab plotting multi-sensor trend lines, save it to `docs/design/temp_trend_tab.png` and add it here. + +## Key Architectural & Design Decisions + +During the refactoring from the flat-layout prototype (`SettingTab` branch) to the unified package application (`main`), the following structural changes were made: + +1. **Package Layout Restructuring**: Reorganized flat imports into a clean `src/` layout under `pygui.*` sub-packages (`controllers/`, `models/`, `data/`, `visualization/`, `wafer/`) for better module isolation. +2. **QML Component Decoupling**: Monolithic pages were refactored into reusable component blocks (e.g., `ReadoutPanel.qml`, `WaferMapView.qml`, `TransportBar.qml` under `src/pygui/ISC/Tabs/components/`), easing tab maintenance. +3. **Decoupled Controller Architecture**: Introduced QML-bound controllers (`DeviceController`, `SessionController`) acting as bridges between UI triggers and backend model states (`FramePlayer`, `SessionModel`), keeping UI files strictly visual. +4. **Robust Slot Error Boundaries**: Decorated QML-callable slots with a custom `@slot_error_boundary` wrapper to intercept runtime errors gracefully without terminating the Qt environment. +5. **Modernized Rendering Engine**: Replaced outdated contour algorithms with Radial Basis Function (RBF) interpolation (`rbf_heatmap.py`) to render high-fidelity, real-time thermal profiles. + ## Requirements - Python 3.11+ (tested with Python 3.14 in this workspace) @@ -28,10 +58,10 @@ pip install -e . # install the `pygui` package (src/ layout) in edita ## Run +### Launch PySide6 QML App ```bash make run ``` - This launches the Qt window and loads the `ISC` QML module from `src/pygui/ISC/Main.qml`. ## Development @@ -78,6 +108,41 @@ The application lives under a `src/` layout as the `pygui` package: - `tests/`: pytest suite. - `packaging/`: PyInstaller spec (`isc.spec`) and app icons. +## Architecture + +``` +┌────────────────────────────────────────────────────────────┐ +│ QML Layer (src/pygui/ISC/) │ +│ HomePage.qml ─ WaferMapTab.qml ─ DataTab.qml │ +│ StatusTab.qml ─ SettingsTab.qml ─ components/* │ +└─────────────────────────┬──────────────────────────────────┘ + │ Q_PROPERTY / @Slot / Signal +┌─────────────────────────▼──────────────────────────────────┐ +│ Controller Layer (backend/controllers/) │ +│ DeviceController ─ SessionController │ +│ (serial ops, status) (streaming, playback) │ +└─────────────────────────┬──────────────────────────────────┘ + │ +┌─────────────────────────▼──────────────────────────────────┐ +│ Model Layer (backend/models/) │ +│ FramePlayer ─ SessionModel ─ ReplayStatsTracker │ +│ ThresholdClassifier ─ SensorEditor ─ ClusterAverage │ +│ TemperatureTableModel │ +└─────────────────────────┬──────────────────────────────────┘ + │ +┌─────────────────────────▼──────────────────────────────────┐ +│ Serial / Data Layer (serialcomm/ + data/) │ +│ SerialPort ─ DeviceService ─ StreamReader ─ data_parser │ +│ LocalSettings ─ FileBrowser ─ CsvRecorder │ +└─────────────────────────┬──────────────────────────────────┘ + │ +┌─────────────────────────▼──────────────────────────────────┐ +│ Visualization (backend/visualization/) │ +│ WaferMapItem ─ GraphView ─ TrendChartItem │ +│ RBFHeatmap ─ WaferMapView (QML wrapper) │ +└────────────────────────────────────────────────────────────┘ +``` + ## Window Configuration Window dimensions and constraints are defined in `src/pygui/ISC/Main.qml`: @@ -143,4 +208,4 @@ Launch the **Wafer Simulator Control Panel** (`wafer_sim_gui.py`): #### Step 3: Run the UI and Connect Launch the `pygui` client application. On the left navigation rail, click **DETECT WAFER**. The application will scan all active COM ports, automatically detect the virtual wafer simulator on **`COM6`**, and update the status indicator to **Connected** (green). -![ISenseCloud UI displaying successful connection on COM6](image-1.png) \ No newline at end of file +![ISenseCloud UI displaying successful connection on COM6](image-1.png)