# rociavl/seeg_automatic_segmentation architecture

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

- Interactive diagram: https://gitdiagram.com/rociavl/seeg_automatic_segmentation
- Repository: https://github.com/rociavl/seeg_automatic_segmentation

## Overview

##### Project type and purpose
- From the file tree and the README title “SEEG_automatic_segmentation,” we infer this is a domain-specific, full-pipeline tool for automatic segmentation and analysis of SEEG (stereo-EEG) imaging data.
- It ingests raw CT/MRI volumes, applies multiple segmentation strategies, extracts spatial features (centroids, end points, bolt heads), constructs electrode trajectories, and produces final data outputs and visualizations.

##### File structure
- Top‐level scripts (e.g., SEEG_masking.py, centroids_data_converter.py) likely orchestrate high-level workflows.
- Modular directories group functionality:
- Brain_mask_methods – brain‐mask extraction
- Threshold_mask – threshold‐based segmentation pipelines
- Masks_ensemble – fuses multiple masks
- Centroids_pipeline & Outermost_centroids_coordinates – centroid and layering feature extraction
- End_points – pipeline for finding end-points and midplanes
- Electrode_path – adaptive clustering and path construction of electrodes
- Bolt_head – specialized scripts to detect/locate bolt heads
- Results – postprocessing, comparisons, visualizations
- Resources/UI and docs/ hold static assets and documentation.
- Testing/ contains CMake and Python tests.
- CMakeLists.txt indicates some compiled components or cross-language builds.

##### README
- Very minimal; we rely mostly on file‐tree naming conventions and folder purposes.

##### Components
a. Data Ingestion & Preprocessing
- Raw imaging inputs (DICOM/NIfTI)
- Preprocessing utilities (resampling, subtraction, csv_to_markups)
- Brain_mask_methods
b. Segmentation Engines
- Threshold_mask (multiple approaches + ML models)
- Masks_ensemble (fusion of segmentation outputs)
- SEEG_masking.py as high‐level entry point
c. Feature Extraction
- Centroids_pipeline (key feature plots, extractions)
- Outermost_centroids_coordinates (k-d tree, slicing, layering)
- End_points (center_points, midplane computation)
- bolt_head modules for bolt detection
d. Trajectory Construction
- Electrode_path (adaptive clustering, angle/path construction)
e. Postprocessing & Results
- Results/ (entry point comparisons, image enhancement, point predictors)
- Model artifacts (Models/random_forest_model…)
f. External/Support Components
- Testing suite (CMake, Python tests)
- Build system (CMakeLists.txt)

##### Relationships & data flow
Raw Data → Preprocessing → Brain Mask
Brain Mask + Raw Data → Segmentation Engines (Threshold_mask → Masks_ensemble)
Segmented Masks → Feature Extraction modules (Centroids, Outermost, End_points, Bolt_head)
Extracted Features → Electrode_path → Final Trajectories
All outputs → Results scripts/visualizations
- Dependencies: e.g., Masks_ensemble depends on multiple sub-modules in Threshold_mask; Centroids_pipeline reads segmentation outputs.

##### Architectural patterns & design principles
- Modular “pipeline” style: each folder is a stage.
- Separation of concerns: segmentation vs. feature extraction vs. trajectory construction.
- Extensibility points:
- New segmentation strategies plug into Threshold_mask.
- New feature modules can join Centroids_pipeline or Outermost_centroids_coordinates.
- Reuse of common utilities (resampler, symmetry, confidence scoring).

##### Essential elements to capture
- Flow of data between them.
- Key external artifacts (Models/, Resources/, Tests/).
- Build/deployment node (CMake).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing
    subgraph "Data Ingestion & Preprocessing"
        direction TB
        RawData["Raw CT/MRI Volumes"]:::preprocessing
        CSV2MK["csv_to_markups.py"]:::preprocessing
        Resample1["resample_roi.py"]:::preprocessing
        Resample2["resampler_module_slicer.py"]:::preprocessing
        Subtract["subtract_images.py"]:::preprocessing
        Symmetry["symmetry.py"]:::preprocessing
        Confidence["confidence.py"]:::preprocessing
    end

    %% Brain Mask Extraction
    subgraph "Brain Mask Extraction"
        direction TB
        BrainMask["brain_mask_extractor_otsu.py"]:::preprocessing
    end

    %% Segmentation Engines
    subgraph "Segmentation Engines"
        direction TB
        EntrySeg["SEEG_masking.py"]:::segmentation
        Threshold["Threshold_mask (P1–P8)"]:::segmentation
        ThPerc["threshold_percentile.py"]:::segmentation
        CTPEnh["ctp_enhancer.py"]:::segmentation
        Enhance["enhance_ctp.py"]:::segmentation
        HistPipe["histogram_pipeline.py"]:::segmentation
        ThModel["threshold_model.py"]:::segmentation
        ThROI["threshold_roi.py"]:::segmentation
        NewML["new_enhance_ml*.py"]:::segmentation
        MasksEnsemble["masks_fusion.py\nmasks_fusion_top.py"]:::segmentation
    end

    %% Feature Extraction
    subgraph "Feature Extraction"
        direction TB
        CentroidsPipe["centroids.py\ncentroids_feature_extraction.py\njust_centroids_coordinates.py\nmodel_application.py"]:::feature
        KeyPlots["create_key_feature_plots.py"]:::feature
        CTfeat["ct_features.py"]:::feature
        AddFeat["extract_additional_features.py"]:::feature
        PreprocElec["preprocess_electrode_data.py"]:::feature
        Outermost["c_outermost_kdtree.py\ncentroids_csv.py\nlayering.py\noutermost_centroids_slicer.py"]:::feature
        EndPoints["center_points.py\nend_points.py\nmidplane.py"]:::feature
        BoltHead["bolt_head.py\nbolt_head_2.py\nbolt_head_concensus.py\nfilter_bolt_heads.py"]:::feature
    end

    %% Trajectory Construction
    subgraph "Trajectory Construction"
        direction TB
        AdaptiveClust["adaptive_clustering.py"]:::trajectory
        ConstructPath["construction_path.py\nconstruction_angles_adaptive.py"]:::trajectory
        Orgabot["orga.py\norga_bolt.py"]:::trajectory
    end

    %% Postprocessing & Results
    subgraph "Postprocessing & Results"
        direction TB
        EntryComp["entry_points_comparison.py"]:::results
        ImgEnh["image_enhancement.py"]:::results
        PointsPred["points_predictor.py"]:::results
        ModelArt["random_forest_modelP1.joblib"]:::results
    end

    %% External & Support
    subgraph "External & Support"
        direction TB
        UI["SEEG_masking.ui"]:::external
        Icons["Resources/Icons/"]:::external
        CMakeRoot["CMakeLists.txt"]:::external
        TestCM["Testing/CMakeLists.txt"]:::external
        PyTestCM["Testing/Python/CMakeLists.txt"]:::external
    end

    %% Flow connections
    RawData -->|ingest| CSV2MK
    RawData --> Resample1
    RawData --> Resample2
    RawData --> Subtract
    RawData --> Symmetry
    Subtract --> Confidence
    CSV2MK --> BrainMask
    Resample1 --> BrainMask
    Resample2 --> BrainMask
    BrainMask --> EntrySeg
    EntrySeg --> Threshold
    Threshold --> ThPerc
    Threshold --> CTPEnh
    Threshold --> Enhance
    Threshold --> HistPipe
    Threshold --> ThModel
    Threshold --> ThROI
    Threshold --> NewML
    ThPerc --> MasksEnsemble
    CTPEnh --> MasksEnsemble
    Enhance --> MasksEnsemble
    MasksEnsemble --> CentroidsPipe
    MasksEnsemble --> Outermost
    MasksEnsemble --> EndPoints
    MasksEnsemble --> BoltHead
    CentroidsPipe --> KeyPlots
    CentroidsPipe --> CTfeat
    CentroidsPipe --> AddFeat
    CentroidsPipe --> PreprocElec
    Outermost --> EndPoints
    EndPoints --> BoltHead
    BoltHead --> AdaptiveClust
    AdaptiveClust --> ConstructPath
    ConstructPath --> Orgabot
    Orgabot --> EntryComp
    Orgabot --> ImgEnh
    Orgabot --> PointsPred
    PointsPred --> ModelArt

    %% Click Events
    click CSV2MK "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/csv_to_markups.py"
    click Resample1 "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/resample_roi.py"
    click Resample2 "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/resampler_module_slicer.py"
    click Subtract "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/subtract_images.py"
    click Symmetry "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/symmetry.py"
    click Confidence "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/confidence.py"
    click BrainMask "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Brain_mask_methods/brain_mask_extractor_otsu.py"
    click EntrySeg "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/SEEG_masking.py"
    click ThPerc "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Threshold_mask/Percentiles_approach/threshold_percentile.py"
    click CTPEnh "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Threshold_mask/ctp_enhancer.py"
    click Enhance "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Threshold_mask/enhance_ctp.py"
    click HistPipe "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Threshold_mask/histogram_pipeline.py"
    click ThModel "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Threshold_mask/threshold_model.py"
    click ThROI "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Threshold_mask/threshold_roi.py"
    click NewML "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Threshold_mask/new_enhance_ml*.py"
    click MasksEnsemble "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Masks_ensemble/masks_fusion.py"
    click MasksEnsemble "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Masks_ensemble/masks_fusion_top.py"
    click CentroidsPipe "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Centroids_pipeline/centroids.py"
    click KeyPlots "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Centroids_pipeline/Features/create_key_feature_plots.py"
    click CTfeat "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Centroids_pipeline/Features/ct_features.py"
    click AddFeat "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Centroids_pipeline/Features/extract_additional_features.py"
    click PreprocElec "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Centroids_pipeline/Features/preprocess_electrode_data.py"
    click Outermost "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Outermost_centroids_coordinates/c_outermost_kdtree.py"
    click EndPoints "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/End_points/end_points.py"
    click BoltHead "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Bolt_head/bolt_head.py"
    click AdaptiveClust "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Electrode_path/adaptive_clustering.py"
    click ConstructPath "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Electrode_path/construction_path.py"
    click Orgabot "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Electrode_path/orga.py"
    click EntryComp "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Results/entry_points_comparison.py"
    click ImgEnh "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Results/image_enhancement.py"
    click PointsPred "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Results/points_predictor.py"
    click ModelArt "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Models/random_forest_modelP1.joblib"
    click UI "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Resources/UI/SEEG_masking.ui"
    click Icons "https://github.com/rociavl/seeg_automatic_segmentation/tree/main/Resources/Icons/"
    click CMakeRoot "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/CMakeLists.txt"
    click TestCM "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Testing/CMakeLists.txt"
    click PyTestCM "https://github.com/rociavl/seeg_automatic_segmentation/blob/main/Testing/Python/CMakeLists.txt"

    %% Styles
    classDef preprocessing fill:#D6EAF8,stroke:#2980B9;
    classDef segmentation fill:#D5F5E3,stroke:#27AE60;
    classDef feature fill:#FCF3CF,stroke:#F1C40F;
    classDef trajectory fill:#FAD7A0,stroke:#E67E22;
    classDef results fill:#E8DAEF,stroke:#8E44AD;
    classDef external fill:#E5E7E9,stroke:#7F8C8D;
```
