# juglab/featureforest architecture

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

- Interactive diagram: https://gitdiagram.com/juglab/featureforest
- Repository: https://github.com/juglab/featureforest

## Overview

##### Main components
- User Interface (UI) Layer:
– Represented by the napari widgets and plugin entry points (e.g., _feature_extractor_widget.py, _segmentation_widget.py)
– Registered via napari.yaml (for plugin discovery)
– Handles user interaction (scribble input, image display)

- Model and Feature Extraction Layer:
– Contains the model adapters and implementations (under src/featureforest/models…) such as Cellpose, DinoV2, MobileSAM, SAM, and SAM2
– Each adapter (adapter.py files) encapsulates specific integration logic for the respective segmentation or vision models
– The “exports” directory might provide abstraction layers or exportable functions for integration into external workflows

- Pipeline & Utility Layer:
– Pipeline functions including feature extraction, Random Forest model training, and predictions are provided in files like pipeline_prediction.py and extract.py within the utils folder
– Configuration and data handling functions (config.py, data.py, downloader.py, usage_stats.py) support the overall process

- Postprocessing Layer:
– The postprocess folder contains scripts to refine the segmentation output (for example, mean curvature adjustments and handling outputs when using SAM)

- Testing and CI/CD:
– Directories like tests/ and configuration files (tox.ini, GitHub workflow files) indicate automated testing and continuous integration

##### Relationships and interactions
- The UI layer (napari widgets) takes input from the user (scribbles, image selections) and triggers the feature extraction process.
- The feature extraction module (utils/extract.py and pipeline_prediction.py) processes the image data using foundation models.
- The extracted features are then passed to the model adapters, where different segmentation methods (Cellpose, SAM, etc.) are applied.
- Once the segmentation is performed, outputs are optionally refined via the postprocessing modules.
- Throughout this process, utility components like configuration, data management, and logging (usage_stats) help ensure consistency and reproducibility.
- The modular design (with adapters for each model type) clearly delineates responsibilities and allows for extension or replacement of one model without affecting other parts.

##### Important architectural patterns and design principles
- Modular Architecture – with decoupled components for UI, model adapters, and utilities.
- Plugin Architecture – implementation as a napari plugin, exposing extension points via napari.yaml.
- Separation of Concerns – each main component (UI, model handling, postprocessing) has specific responsibilities.
- Test-Driven Design – evidenced by a dedicated tests directory and CI workflows.

##### Relevant technologies and frameworks
- napari – for interactive image visualization and annotation.
- Vision Transformers and related deep learning frameworks (e.g., PyTorch, hinted by model files and environment YAMLs, though not explicitly listed, are likely used for handling foundation models).
- Random Forest classifier – for machine learning segmentation tasks (the documentation emphasizes its use in combination with extracted features).
- CI/CD tools – GitHub Workflows ensure code quality and continuous deployment/testing.
- Conda – environment management (env_cpu.yml and env_gpu.yml).

##### Detail
- This separation will not only clarify dependencies and interactions but ensure that every element of the architecture is represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer (Napari Plugin)"
        UI1["Feature Extractor Widget"]:::ui
        UI2["Segmentation Widget"]:::ui
        UI3["Plugin Registration (napari.yaml)"]:::ui
    end

    subgraph "Pipeline & Utility Layer"
        P1["Feature Extraction (extract.py)"]:::pipeline
        P2["Pipeline Prediction (pipeline_prediction.py)"]:::pipeline
        subgraph "Config & Data Handling"
            C1["Configuration (config.py)"]:::pipeline
            C2["Data Handling (data.py)"]:::pipeline
            C3["Downloader (downloader.py)"]:::pipeline
            C4["Usage Stats (usage_stats.py)"]:::pipeline
        end
        P3["Random Forest Classifier"]:::pipeline
    end

    subgraph "Model Adapters Layer"
        A1["Cellpose Adapter"]:::adapter
        A2["DinoV2 Adapter"]:::adapter
        A3["MobileSAM Adapter"]:::adapter
        A4["SAM Adapter"]:::adapter
        A5["SAM2 Adapter"]:::adapter
    end

    subgraph "Postprocessing Layer"
        PP1["Mean Curvature Adjustment"]:::postproc
        PP2["Postprocessing (postprocess.py)"]:::postproc
        PP3["Postprocessing with SAM (postprocess_with_sam.py)"]:::postproc
    end

    subgraph "Testing / CI-CD"
        T1["Automated Tests (tests)"]:::testing
        T2["CI/CD Workflows (.github/workflows)"]:::testing
    end

    %% Connections from UI to Pipeline
    UI1 -->|"trigger"| P1
    UI2 -->|"trigger"| P1
    UI3 -.->|"registers"| UI1

    %% Pipeline & Utility connections
    P1 -->|"results"| P2
    P1 -->|"config"| C1
    P1 -->|"data"| C2
    P1 -->|"downloader"| C3
    P1 -->|"usage"| C4
    P2 -->|"features"| P3

    %% Pipeline to Model Adapters
    P3 -->|"applies"| A1
    P3 -->|"applies"| A2
    P3 -->|"applies"| A3
    P3 -->|"applies"| A4
    P3 -->|"applies"| A5

    %% Model Adapters to Postprocessing
    A1 -->|"segmentation"| PP1
    A2 -->|"segmentation"| PP1
    A3 -->|"segmentation"| PP1
    A4 -->|"segmentation"| PP2
    A5 -->|"segmentation"| PP3

    %% Postprocessing to UI for display
    PP1 -->|"final_output"| UI2
    PP2 -->|"final_output"| UI2
    PP3 -->|"final_output"| UI2

    %% Styling classes
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef pipeline fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef adapter fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef postproc fill:#DA70D6,stroke:#000,stroke-width:2px;
    classDef testing fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events
    click UI1 "https://github.com/juglab/featureforest/blob/main/src/featureforest/_feature_extractor_widget.py"
    click UI2 "https://github.com/juglab/featureforest/blob/main/src/featureforest/_segmentation_widget.py"
    click UI3 "https://github.com/juglab/featureforest/blob/main/src/featureforest/napari.yaml"
    click A1 "https://github.com/juglab/featureforest/blob/main/src/featureforest/models/Cellpose/adapter.py"
    click A2 "https://github.com/juglab/featureforest/blob/main/src/featureforest/models/DinoV2/adapter.py"
    click A3 "https://github.com/juglab/featureforest/blob/main/src/featureforest/models/MobileSAM/adapter.py"
    click A4 "https://github.com/juglab/featureforest/blob/main/src/featureforest/models/SAM/adapter.py"
    click A5 "https://github.com/juglab/featureforest/blob/main/src/featureforest/models/SAM2/adapter.py"
    click P1 "https://github.com/juglab/featureforest/blob/main/src/featureforest/utils/extract.py"
    click P2 "https://github.com/juglab/featureforest/blob/main/src/featureforest/utils/pipeline_prediction.py"
    click C1 "https://github.com/juglab/featureforest/blob/main/src/featureforest/utils/config.py"
    click C2 "https://github.com/juglab/featureforest/blob/main/src/featureforest/utils/data.py"
    click C3 "https://github.com/juglab/featureforest/blob/main/src/featureforest/utils/downloader.py"
    click C4 "https://github.com/juglab/featureforest/blob/main/src/featureforest/utils/usage_stats.py"
    click PP1 "https://github.com/juglab/featureforest/blob/main/src/featureforest/postprocess/mean_curvature.py"
    click PP2 "https://github.com/juglab/featureforest/blob/main/src/featureforest/postprocess/postprocess.py"
    click PP3 "https://github.com/juglab/featureforest/blob/main/src/featureforest/postprocess/postprocess_with_sam.py"
    click T1 "https://github.com/juglab/featureforest/tree/main/tests/"
    click T2 "https://github.com/juglab/featureforest/tree/main/.github/workflows"
```
