# saeedahmadicp/teeth_segmentation architecture

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

- Interactive diagram: https://gitdiagram.com/saeedahmadicp/teeth_segmentation
- Repository: https://github.com/saeedahmadicp/teeth_segmentation

## Overview

##### Project type and purpose
- This is a research‐oriented machine‐learning codebase for performing teeth segmentation using UNet and its variants (UNet, UNet++, ResUNet, Attention UNet, etc.).
- The main goal is to load dental image data, train one of several UNet‐based architectures, compute segmentation metrics (accuracy, dice score), and save model checkpoints and results.

##### File structure
Top‐level files and directories:
- train.py       – the entry point for training and evaluation
- dataset.py     – data loading and preprocessing
- lookahead.py   – custom optimizer wrapper (Lookahead)
- utils.py       – logging, checkpoint saving, metric computation
- models/        – implementations of UNet variants and shared modules
– model.py       (base UNet class & training wrapper)
– modules.py     (building blocks: conv blocks, up/down samples)
– dense_unet.py, unetplusplus.py (specific architectures)
- attentions/    – custom attention modules (CBAM, custom spatial attention)
- losses/        – loss functions (DiceLoss, FocalLoss)
- configuration files: .gitignore, CITATION.cff, CONTRIBUTING.md, LICENSE, etc.

##### README for additional insights
- No external services; data must be provided manually.
- You run `python train.py` after pointing to your local dataset.
- The code reports test accuracy & dice score for each variant.
- Intended for learning—no production concerns like scaling or APIs.

a. Main components:
1. Data Source
– Raw dental images (external).
2. Data Loader & Preprocessor (dataset.py)
– Reads images, applies augmentations, resizes to desired resolution.
3. Model Architectures (models/ + attentions/)
– Base UNet, UNet++, Dense UNet, Attention modules (CBAM, custom).
4. Loss & Optimization (losses/, lookahead.py)
– FocalLoss, DiceLoss, optimizers (Adam + Lookahead).
5. Training Loop (train.py)
– Orchestrates data ingestion, forward/backward pass, logging.
6. Utilities (utils.py)
– Checkpointing, metric computation, visualization, logging to console/files.
7. Evaluation & Reporting
– Computes final metrics on test set; produces summary table.

b. Relationships and interactions:

c. Architectural patterns and design principles:
- Modularity: separate directories for models, losses, attentions.
- Dependency injection: train.py selects model variant, loss, and optimizer at runtime.
- Reusability: core UNet building blocks in modules.py; attention modules decoupled.
- Extensibility: plug new models or losses by dropping files into models/ or losses/.

d. Key technologies and libraries:
- PyTorch (implied by model definitions and training loops)
- Python scripting for orchestration
- NumPy, OpenCV or PIL for image I/O (in dataset.py)
- (Optional) CUDA/CuDNN for GPU acceleration

6. Offshoots from the training loop to “Logging & Checkpointing” (utils.py) and “Evaluation” (test metric computation).

## Diagram (Mermaid)

```mermaid
flowchart TB
    RawData["Raw Dental Images"]:::external
    DataLoader["Data Loader & Preprocessor\n(dataset.py)"]:::data
    Training["Training Loop\n(train.py)"]:::util
    subgraph "Model Architectures"
        BaseUNet["Base UNet\n(models/model.py)"]:::model
        UNetPP["UNet++\n(models/unetplusplus.py)"]:::model
        DenseUNet["Dense UNet\n(models/dense_unet.py)"]:::model
        Modules["Core Blocks\n(models/modules.py)"]:::model
        CBAM["CBAM\n(attentions/cbam.py)"]:::model
        CustomAtt["Custom Attention\n(attentions/custom_attention.py)"]:::model
    end
    subgraph "Loss Functions"
        Dice["DiceLoss\n(losses/dice_loss.py)"]:::loss
        Focal["FocalLoss\n(losses/focal_loss.py)"]:::loss
    end
    Optimizer["Optimizer\nAdam + Lookahead\n(lookahead.py)"]:::opt
    Utils["Logging & Checkpointing\n(utils.py)"]:::util
    Evaluation["Evaluation & Reporting"]:::util
    Results["Results Report\n(Accuracy & Dice)"]:::util

    RawData --> DataLoader
    DataLoader --> Training
    Training --> BaseUNet
    Training --> UNetPP
    Training --> DenseUNet
    Training --> Modules
    Training --> CBAM
    Training --> CustomAtt
    BaseUNet --> Dice
    UNetPP --> Dice
    DenseUNet --> Dice
    BaseUNet --> Focal
    UNetPP --> Focal
    DenseUNet --> Focal
    Dice --> Optimizer
    Focal --> Optimizer
    Optimizer --> Training
    Training --> Utils
    Training --> Evaluation
    Evaluation --> Results

    click DataLoader "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/dataset.py"
    click Training "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/train.py"
    click BaseUNet "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/models/model.py"
    click UNetPP "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/models/unetplusplus.py"
    click DenseUNet "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/models/dense_unet.py"
    click Modules "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/models/modules.py"
    click CBAM "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/attentions/cbam.py"
    click CustomAtt "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/attentions/custom_attention.py"
    click Dice "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/losses/dice_loss.py"
    click Focal "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/losses/focal_loss.py"
    click Optimizer "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/lookahead.py"
    click Utils "https://github.com/saeedahmadicp/teeth_segmentation/blob/master/utils.py"

    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef model fill:#90EE90,stroke:#333,stroke-width:1px
    classDef loss fill:#FFA500,stroke:#333,stroke-width:1px
    classDef opt fill:#FFB347,stroke:#333,stroke-width:1px
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
