System Architecture
===================

Pycroglia is designed with a strict separation between its computational core and its PyQt6 graphical user interface. This separation enables both a responsive GUI and an accessible library mode for script-based execution.

Core Module (``pycroglia.core``)
--------------------------------

The core module houses all image processing algorithms, geometry calculations, and parallel execution infrastructure. It has no dependencies on PyQt.

Compute Infrastructure
~~~~~~~~~~~~~~~~~~~~~~

To handle intensive operations like 3D skeletonization and Euclidean distance transforms without blocking the UI, Pycroglia uses a flexible multiprocessing architecture.

* **``Computable`` Interface:** All major analytical tasks (e.g., ``BranchAnalysis``, ``Centroids``, ``FullCellAnalysis``, ``TerritorialVolume``) inherit from a ``Computable`` abstract base class, exposing a ``compute() -> dict`` method.
* **Pool Facade:** The ``Pool`` class acts as a unified frontend for job submission. It abstracts the underlying execution backend.
* **Backends:**
    * ``QPool``: Uses Qt's ``QThreadPool`` and ``QRunnable``. Ideal for GUI execution as it natively integrates with Qt's event loop and signals.
    * ``MPPool``: Uses Python's standard ``multiprocessing.Pool``. Used when Pycroglia is imported as a library without a Qt QApplication.

Metrics DAG
~~~~~~~~~~~

Because some metrics depend on the results of others (e.g., branch lengths require the centroid to be calculated first to determine distance order), the computation is orchestrated by a ``MetricsDAG`` (Directed Acyclic Graph). 

The DAG submits independent tasks (Centroid, Territorial Volume, Full Cell Analysis) to the pool simultaneously. Once the Centroid task completes, it dynamically submits the dependent ``BranchAnalysis`` tasks. Progress is tracked via atomic ``QCounter`` barriers.

Algorithm Highlights
~~~~~~~~~~~~~~~~~~~~

* **Skeletonization (``slimskel3d``):** Pycroglia contains a native Python/NumPy implementation of the Lee-Kashyap-Chu 3D thinning algorithm, matching the exact behavior of the MATLAB `Skeleton3D` implementation used in *CellSelect-3DMorph*. It recursively erodes border voxels while preserving Euler topology and endpoints.
* **Branch Analysis:** Once skeletonized, the core uses 3x3x3 26-connected convolutional kernels to identify branch points and endpoints. Branches are isolated by path-finding from endpoints to the cell centroid. Arc length is calculated using Euclidean distance between ordered voxels.
* **I/O (``pycroglia.core.io``):** 
    * Handles parsing of TIFF and LSM stacks.
    * Outputs exporters (Excel, JSON) map the heterogeneous ``Computable`` result dictionaries to structured output formats.

UI Module (``pycroglia.ui``)
----------------------------

The UI is built on PyQt6 and follows a structured model-view-controller (MVC) pattern adapted for wizard-style navigation.

* **Widgets:** Custom PyQt widgets (found in ``pycroglia.ui.widgets``) handle display logic. E.g., ``FileSelectionEditor``, ``FilterEditorStack``, ``ResultsDashboardStack``.
* **Controllers / State:** Pure state managers (e.g., ``SegmentationEditorState``, ``ResultsDashboardState``) handle the business logic of UI interactions, decoupled from the views. They emit ``pyqtSignal``s when data changes, which the views observe to update themselves.
* **Wizard Navigation:** A ``PageManager`` wraps major widgets into ``BasePage`` objects. It orchestrates the flow of data forward. For instance, when clicking "Next" on the Filter page, the ``PageManager`` extracts the binary masks using ``get_state()`` and injects them into the Segmentation page using ``set_data()``.