# dcbia-ortholab/slicerdentalmodelseg architecture

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

- Interactive diagram: https://gitdiagram.com/dcbia-ortholab/slicerdentalmodelseg
- Repository: https://github.com/dcbia-ortholab/slicerdentalmodelseg

## Overview

##### Project type and purpose
- This is a 3D Slicer extension (CrownSegmentation) plus a standalone CLI (CrownSegmentationcli) for deep-learning–based automatic segmentation and labeling of dental crown models (.vtk).
- It provides both a GUI module (loaded by 3D Slicer) and a command-line interface, leverages PyTorch for inference, and wraps everything with CMake for cross-platform build/packaging.

##### Key directories and files
- Top-level:
- CMakeLists.txt – orchestrates building the Slicer extension and CLI
- readme.md – explains installation and usage
- examples/ – sample .vtk meshes and expected outputs
- CrownSegmentation/ (the Slicer module)
- CrownSegmentation.py – main Python controller for the Slicer GUI
- Resources/UI/CrownSegmentation.ui – QtDesigner file defining the GUI layout
- CrownSegmentation_utils/ – Python helper functions (data I/O, model download/installation)
- CrownSegmentationcli/ (standalone CLI)
- CrownSegmentationcli.py – entry-point script for headless usage
- CrownSegmentationcli.xml – descriptor for CLI arguments, used by CMake to generate wrap
- Testing/ – CMake and Python test scripts
- .gitignore, LICENSE

##### Architectural overview and components
A. Slicer Host Application
- Loads the extension via CMake-generated module
- Passes MRMLModelNodes (.vtk meshes) into the module
B. GUI Module (CrownSegmentation)
- UI Definition (Qt .ui file)
- Controller (CrownSegmentation.py)
- Invokes utils for pre-/post-processing and inference
C. Core Segmentation Engine
- Python code in CrownSegmentation_utils
- install_pytorch.py for dependency management (CUDA/PyTorch)
- Data preparation: converting 3D mesh to 2D views
- Model inference: loads a serialized .pt or .pth file, runs forward pass
D. CLI Module
- CrownSegmentationcli.py + XML descriptor
- Mirrors GUI module’s calls to utils and core engine
E. External Dependencies
- PyTorch + CUDA
- VTK I/O (via Slicer or directly in Python)
- Qt (embedded in Slicer)
F. Data Flow/Storage
- Input: .vtk mesh → MRMLModelNode (GUI) or file path (CLI)
- Intermediate: rendered 2D slices, tensor batches
- Output: labeled .vtk mesh (single or per-tooth output files)

##### Relationships and interactions
- UI Controller calls CrownSegmentation_utils for:
- Checking/installing dependencies
- Loading the PyTorch model
- Preprocessing the input mesh
- Running inference
- Postprocessing and saving output mesh(es)
- All data I/O flows through VTK or Slicer MRML APIs
- Testing harness invokes CLI or individual utils functions to validate outputs

##### Architectural patterns and design principles
- Plugin architecture: the extension cleanly separates GUI (view/controller) from the segmentation engine (model)
- Single Responsibility: utils directory isolates environment setup, model loading, data transforms
- Reuse via CMake: same source code base builds both Slicer module and standalone CLI
- Dependency injection: model path, number of views, resolution, and numbering system are all parameterized

- Blue: Host applications (3D Slicer, CLI)
- Green: GUI Layer (CrownSegmentation.py + .ui)
- Orange: Core Engine (CrownSegmentation_utils)
- Gray: External services/dependencies (PyTorch/CUDA, VTK)
- Yellow: Data stores (input/output .vtk files, model files)
- From Host → GUI/CLI, from GUI/CLI → Core Engine, from Engine → Data Store
- Rectangles for modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Applications
    subgraph "Host Applications"
        Slicer["3D Slicer"]:::host
        CLIApp["CrownSegmentation CLI"]:::host
    end

    %% GUI Module
    subgraph "GUI Module (CrownSegmentation)"
        UI["CrownSegmentation.ui"]:::gui
        Ctrl["CrownSegmentation.py"]:::gui
    end

    %% Core Engine
    subgraph "Core Segmentation Engine (CrownSegmentation_utils)"
        UtilsInit["__init__.py"]:::core
        InstallPT["install_pytorch.py"]:::core
        OtherUtils["Helper Modules"]:::core
    end

    %% CLI Module
    subgraph "CLI Module"
        CLIScript["CrownSegmentationcli.py"]:::host
        CLIXML["CrownSegmentationcli.xml"]:::host
        CLICMake["CMakeLists.txt"]:::host
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PyTorch["PyTorch & CUDA"]:::external
        VTK["VTK I/O"]:::external
        Qt["Qt (embedded)"]:::external
    end

    %% Data Stores
    InputMesh["Input .vtk Meshes"]:::data
    Slices["Intermediate 2D Slices & Tensors"]:::data
    ModelFile["Model Files (.pt/.pth)"]:::data
    OutputMesh["Output Labeled .vtk Meshes"]:::data
    Examples["examples/"]:::data

    %% Build & Docs
    CMake["CMakeLists.txt"]:::build
    Readme["readme.md"]:::build
    License["LICENSE"]:::build
    GitIgnore[".gitignore"]:::build

    %% Testing Harness
    subgraph "Testing Harness"
        SlicerTests["CrownSegmentation/Testing/CMakeLists.txt"]:::test
        PyTests["CrownSegmentation/Testing/Python/CMakeLists.txt"]:::test
    end

    %% Relationships
    CMake -->|builds extension| Slicer
    CMake -->|builds CLI| CLIScript

    Slicer -->|loads GUI Module| Ctrl
    Ctrl -->|loads UI| UI
    Ctrl -->|calls utils| UtilsInit
    Ctrl -->|checks/deps| InstallPT
    InstallPT -->|installs| PyTorch

    UtilsInit -->|preprocess| Slices
    UtilsInit -->|load model| ModelFile
    UtilsInit -->|inference| PyTorch
    UtilsInit -->|postprocess| OutputMesh
    UtilsInit -->|uses I/O| VTK

    CLIScript -->|reads args| CLIXML
    CLIScript -->|calls utils| UtilsInit

    CLIApp -->|invokes| CLIScript

    SlicerTests -->|tests CLI & utils| CLIScript
    SlicerTests -->|tests GUI| Ctrl
    PyTests -->|tests utils| UtilsInit

    %% Data flows
    InputMesh -->|file I/O| VTK
    InputMesh -->|to MRMLNode| Slicer
    OutputMesh -->|saved files| examples

    %% Documentation & Examples
    Readme -->|describes| CMake
    Readme -->|includes| Examples

    %% Click Events
    click CMake "https://github.com/dcbia-ortholab/slicerdentalmodelseg/blob/main/CMakeLists.txt"
    click Readme "https://github.com/dcbia-ortholab/slicerdentalmodelseg/blob/main/readme.md"
    click Examples "https://github.com/dcbia-ortholab/slicerdentalmodelseg/tree/main/examples/"
    click UI "https://github.com/dcbia-ortholab/slicerdentalmodelseg/blob/main/CrownSegmentation/Resources/UI/CrownSegmentation.ui"
    click Ctrl "https://github.com/dcbia-ortholab/slicerdentalmodelseg/blob/main/CrownSegmentation/CrownSegmentation.py"
    click UtilsInit "https://github.com/dcbia-ortholab/slicerdentalmodelseg/blob/main/CrownSegmentation/CrownSegmentation_utils/__init__.py"
    click InstallPT "https://github.com/dcbia-ortholab/slicerdentalmodelseg/blob/main/CrownSegmentation/CrownSegmentation_utils/install_pytorch.py"
    click CLIScript "https://github.com/dcbia-ortholab/slicerdentalmodelseg/blob/main/CrownSegmentationcli/CrownSegmentationcli.py"
    click CLIXML "https://github.com/dcbia-ortholab/slicerdentalmodelseg/blob/main/CrownSegmentationcli/CrownSegmentationcli.xml"
    click CLICMake "https://github.com/dcbia-ortholab/slicerdentalmodelseg/blob/main/CrownSegmentationcli/CMakeLists.txt"
    click SlicerTests "https://github.com/dcbia-ortholab/slicerdentalmodelseg/blob/main/CrownSegmentation/Testing/CMakeLists.txt"
    click PyTests "https://github.com/dcbia-ortholab/slicerdentalmodelseg/blob/main/CrownSegmentation/Testing/Python/CMakeLists.txt"

    %% Styles
    classDef host fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef gui fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef core fill:#ffcc80,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef data fill:#fff9c4,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef build fill:#d1c4e9,stroke:#333,stroke-width:1px
    classDef test fill:#f5f5f5,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
