Workflow and UI Guide

The Pycroglia Graphical User Interface (GUI) is built as a step-by-step wizard. This design ensures a logical progression from raw image data to final morphological analysis, minimizing user error and providing immediate visual feedback at every stage.

The wizard is orchestrated by the ConfigurableMainStack and PageManager components, which handle navigation (Next/Back) and state transfer between the major steps.

1. File Selection

The entry point of the application.

UI Elements: * File List: Displays the list of selected files. * Add/Remove Buttons: Browse and select TIFF or LSM files to process.

Connection: The selected file paths are gathered and passed forward as state to the Filter Editor page.

2. Filter Editor

Here, users apply initial pre-processing to clean up the raw microscopy images. This step is critical for separating foreground (cells) from background.

UI Elements: * Channel Selector: If a multi-channel image is loaded (like an LSM file), you select which channel contains the cells of interest. * Per-Slice Otsu Thresholding: A slider allows you to manually adjust the automatically calculated Otsu threshold. This applies 2D thresholding slice-by-slice, improving robustness against uneven Z-illumination. * Small Object Removal: A spin box to define the minimum volume (in voxels) to keep. Smaller disconnected components are discarded as noise. * Morphological Erosion: Tools to define a structuring element (e.g., 2D Diamond, radius) to erode the binary mask, helping to separate touching cells. * Image Viewer: Provides real-time visual feedback of the filtering operations.

Connection: The resulting binary masks and filter configurations for each file are sent to the Segmentation Editor page.

3. Segmentation Editor

This page isolates individual cells from the filtered binary mask using connected-component labeling.

UI Elements: * Cell Viewer: Displays the labeled components. Each color represents a distinct connected component. * GMM Splitting Tool: If two cells are physically merged in the binary mask, you can select the combined object and apply a Gaussian Mixture Model (GMM) clustering to split it based on its morphology and intensity profile. * Action History/Rollback: Allows you to undo splitting or merging operations, restoring the previous segmentation state. * Size/Property Tables: Lists all detected cells with their initial voxel volumes.

Connection: The fully separated and labeled cell masks are passed to the Cell Selection page.

4. Cell Selection

A quality control step to finalize which cells will be analyzed.

UI Elements: * Filter Panel: Global filters to exclude cells that touch the image borders (incomplete cells) or fall outside a specified size range. * Interactive Cell List: Allows manual deselection of specific cells that are artifacts or otherwise unsuited for analysis. * Preview Viewer: Renders the 3D footprint of the selected cells.

Connection: The finalized list of individual cell masks is transmitted to the Results Dashboard for computation.

5. Results Dashboard

The final stage where quantitative analysis is executed and visualized.

UI Elements: * Configuration Panel: Input the physical dimensions of the image voxels (XY scale in µm, Z scale in µm). This is crucial for calculating accurate physical volumes and branch lengths. * Run Button: Triggers the MetricsDAG parallel computation engine to analyze all selected cells. * Summary Table: Displays aggregated metrics for the entire image (e.g., total territorial volume, average centroid distance). * Per-Cell Table: Details metrics for every individual cell (volume, territorial volume, ramification index, branch count, endpoints, max/min/avg branch lengths). * 3D PyVista Renderers: Interactive 3D plots showing the cell surface, the skeleton, branch points, and convex hull. * Export Panel: Buttons to save the data to Excel (.xlsx), JSON, or export the 3D geometries (OBJ, PLY, VTP).

Under the Hood: When computation is triggered, the dashboard relies on a QPool facade to execute CPU-intensive tasks (skeletonization, convex hull calculation, distance transforms) concurrently across available threads without freezing the Qt GUI.