# shrillgig/semantic-segmentation architecture

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

- Interactive diagram: https://gitdiagram.com/shrillgig/semantic-segmentation
- Repository: https://github.com/shrillgig/semantic-segmentation

## Overview

1. **Repository purpose**
   - This repo is a small semantic-segmentation model zoo in Python.
   - It focuses on three architectures: **light U-Net**, **LinkNet**, and **PSPNet**.
   - The codebase is centered on defining pixel-wise classification networks rather than on data ingestion, deployment, or UI.

2. **Top-level structure**
   - The tree is flat: one entry script and three model modules.
   - `main.py` is the likely orchestration point.
   - `unet_light.py`, `linknet.py`, and `pspnet.py` each isolate one segmentation architecture, which makes the repo easy to diagram as independent model components behind a common entry point.

3. **Main control boundary**
   - `main.py` is the only obvious coordinator.
   - Its role is probably to choose a model, pass input through it, and run the intended workflow around segmentation.
   - There is no separate service layer or package hierarchy, so the application boundary is very thin.

4. **Shared architectural pattern**
   - All three models follow the same high-level flow: **image tensor in → feature extraction → contextual processing/decoding → per-pixel class map out**.
   - The output is a segmentation mask aligned to the input image resolution or class grid.
   - This shared contract is the main integration point between `main.py` and the model files.

5. **`unet_light.py` subsystem**
   - This is a lightweight U-Net variant.
   - It uses the classic **encoder-decoder** pattern with **skip connections** between matching resolution levels.
   - The “light” aspect comes from reduced channel width, so it trades some capacity for lower memory use and faster training/inference.

6. **`linknet.py` subsystem**
   - LinkNet is also encoder-decoder based, but it is optimized for efficiency and real-time segmentation.
   - The encoder uses residual-style feature extraction blocks, while the decoder restores spatial detail with upsampling/transposed convolution.
   - Skip connections transfer features directly from encoder to decoder, reducing information loss during downsampling.

7. **`pspnet.py` subsystem**
   - PSPNet differs from the other two by emphasizing **context aggregation** rather than only symmetric decoding.
   - Its defining block is the **Pyramid Pooling Module**, which pools the deepest features at multiple spatial scales.
   - Those multi-scale features are concatenated and passed to a segmentation head to combine global scene context with local detail.

8. **Data flow across models**
   - The models all consume an image and produce class-wise logits or masks.
   - U-Net and LinkNet preserve detail through skip connections across stages.
   - PSPNet preserves context through multi-scale pooling from the encoder’s final feature map.
   - In diagram terms, the repo contains three alternative segmentation pipelines, not a chained pipeline.

9. **Important boundaries for an architecture diagram**
   - **Entry boundary:** `main.py`
   - **Model boundary:** one file per architecture
   - **Inference boundary:** input image tensor to output mask
   - **No visible persistence boundary:** there are no dataset, checkpoint, API, or database modules in the tree
   - **No visible deployment boundary:** nothing suggests web, mobile, or cloud packaging in this repo snapshot

10. **Technologies that materially shape the design**
   - The repository is clearly built around **deep learning / CNN-based semantic segmentation**.
   - The code organization suggests a Python-based implementation with model classes/functions separated by architecture.
   - The README frames the repo as an educational/comparative implementation of segmentation networks rather than a production system.

11. **How to draw it**
   - A good diagram would show `main.py` at the top branching into three independent model modules.
   - Each module should be drawn as a self-contained network block with its own internal stages:
     - U-Net: encoder → bottleneck → decoder with skips
     - LinkNet: residual encoder → lightweight decoder with skips
     - PSPNet: backbone encoder → pyramid pooling → segmentation head
   - All three end in the same kind of output: a dense segmentation mask.

12. **Overall interpretation**
   - This is a compact comparison repo for segmentation architectures.
   - The key design idea is substitutability: the same segmentation task can be served by three different network families with different tradeoffs in accuracy, context capture, and efficiency.

Main entry points: [`main.py`](https://github.com/shrillgig/semantic-segmentation/blob/main/main.py) (main.py), [`unet_light.py`](https://github.com/shrillgig/semantic-segmentation/blob/main/unet_light.py) (Encoder), [`linknet.py`](https://github.com/shrillgig/semantic-segmentation/blob/main/linknet.py) (Residual encoder), [`pspnet.py`](https://github.com/shrillgig/semantic-segmentation/blob/main/pspnet.py) (PSPNet)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry"]
  node_main["main.py<br/>orchestrator<br/>[main.py]"]
end

subgraph group_unet["Light U-Net"]
  node_unet_model["U-Net<br/>segmentation net<br/>[unet_light.py]"]
  node_unet_enc["Encoder<br/>feature extractor<br/>[unet_light.py]"]
  node_unet_bottleneck(("Bottleneck<br/>latent core<br/>[unet_light.py]"))
  node_unet_dec["Decoder<br/>upsampler<br/>[unet_light.py]"]
  node_unet_skips{{"Skip links<br/>feature fusion<br/>[unet_light.py]"}}
end

subgraph group_linknet["LinkNet"]
  node_linknet_model["LinkNet<br/>segmentation net<br/>[linknet.py]"]
  node_linknet_enc["Residual encoder<br/>feature extractor<br/>[linknet.py]"]
  node_linknet_dec["Light decoder<br/>upsampler<br/>[linknet.py]"]
  node_linknet_skips{{"Skip paths<br/>feature fusion<br/>[linknet.py]"}}
end

subgraph group_pspnet["PSPNet"]
  node_pspnet_model["PSPNet<br/>segmentation net<br/>[pspnet.py]"]
  node_pspnet_backbone["Backbone<br/>feature extractor<br/>[pspnet.py]"]
  node_pspnet_ppm{{"Pyramid pool<br/>context module<br/>[pspnet.py]"}}
  node_pspnet_head["Seg head<br/>prediction head<br/>[pspnet.py]"]
end

node_mask_out["Mask output<br/>dense logits"]

node_main -->|"selects"| node_unet_model
node_main -->|"selects"| node_linknet_model
node_main -->|"selects"| node_pspnet_model
node_unet_model -->|"uses"| node_unet_enc
node_unet_enc -->|"compresses"| node_unet_bottleneck
node_unet_bottleneck -->|"expands"| node_unet_dec
node_unet_enc -.->|"routes"| node_unet_skips
node_unet_skips -.->|"fuses"| node_unet_dec
node_unet_dec -->|"predicts"| node_mask_out
node_linknet_model -->|"uses"| node_linknet_enc
node_linknet_enc -.->|"routes"| node_linknet_skips
node_linknet_enc -->|"feeds"| node_linknet_dec
node_linknet_skips -.->|"fuses"| node_linknet_dec
node_linknet_dec -->|"predicts"| node_mask_out
node_pspnet_model -->|"uses"| node_pspnet_backbone
node_pspnet_backbone -->|"aggregates"| node_pspnet_ppm
node_pspnet_ppm -->|"refines"| node_pspnet_head
node_pspnet_head -->|"predicts"| node_mask_out

click node_main "https://github.com/shrillgig/semantic-segmentation/blob/main/main.py"
click node_unet_model "https://github.com/shrillgig/semantic-segmentation/blob/main/unet_light.py"
click node_unet_enc "https://github.com/shrillgig/semantic-segmentation/blob/main/unet_light.py"
click node_unet_bottleneck "https://github.com/shrillgig/semantic-segmentation/blob/main/unet_light.py"
click node_unet_dec "https://github.com/shrillgig/semantic-segmentation/blob/main/unet_light.py"
click node_unet_skips "https://github.com/shrillgig/semantic-segmentation/blob/main/unet_light.py"
click node_linknet_model "https://github.com/shrillgig/semantic-segmentation/blob/main/linknet.py"
click node_linknet_enc "https://github.com/shrillgig/semantic-segmentation/blob/main/linknet.py"
click node_linknet_dec "https://github.com/shrillgig/semantic-segmentation/blob/main/linknet.py"
click node_linknet_skips "https://github.com/shrillgig/semantic-segmentation/blob/main/linknet.py"
click node_pspnet_model "https://github.com/shrillgig/semantic-segmentation/blob/main/pspnet.py"
click node_pspnet_backbone "https://github.com/shrillgig/semantic-segmentation/blob/main/pspnet.py"
click node_pspnet_ppm "https://github.com/shrillgig/semantic-segmentation/blob/main/pspnet.py"
click node_pspnet_head "https://github.com/shrillgig/semantic-segmentation/blob/main/pspnet.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main toneBlue
class node_unet_model,node_unet_enc,node_unet_bottleneck,node_unet_dec,node_unet_skips toneAmber
class node_linknet_model,node_linknet_enc,node_linknet_dec,node_linknet_skips toneMint
class node_pspnet_model,node_pspnet_backbone,node_pspnet_ppm,node_pspnet_head toneRose
class node_mask_out toneNeutral
```

## Components

### Entry

Top-level orchestration boundary

- [main.py](https://github.com/shrillgig/semantic-segmentation/blob/main/main.py): orchestrator · Chooses and runs a segmentation model workflow · `main.py`

### Light U-Net

Lightweight encoder-decoder segmentation model

- [U-Net](https://github.com/shrillgig/semantic-segmentation/blob/main/unet_light.py): segmentation net · Lightweight U-Net variant for dense prediction · `unet_light.py`
- [Encoder](https://github.com/shrillgig/semantic-segmentation/blob/main/unet_light.py): feature extractor · Downsamples input while growing feature depth · `unet_light.py`
- [Bottleneck](https://github.com/shrillgig/semantic-segmentation/blob/main/unet_light.py): latent core · Compresses features at the lowest resolution · `unet_light.py`
- [Decoder](https://github.com/shrillgig/semantic-segmentation/blob/main/unet_light.py): upsampler · Restores spatial resolution toward the mask output · `unet_light.py`
- [Skip links](https://github.com/shrillgig/semantic-segmentation/blob/main/unet_light.py): feature fusion · Carries high-resolution features around the bottleneck · `unet_light.py`

### LinkNet

Efficient residual encoder-decoder segmentation model

- [LinkNet](https://github.com/shrillgig/semantic-segmentation/blob/main/linknet.py): segmentation net · Residual-style encoder-decoder for efficient segmentation · `linknet.py`
- [Residual encoder](https://github.com/shrillgig/semantic-segmentation/blob/main/linknet.py): feature extractor · Builds hierarchical features with residual blocks · `linknet.py`
- [Light decoder](https://github.com/shrillgig/semantic-segmentation/blob/main/linknet.py): upsampler · Reconstructs mask resolution with efficient upsampling · `linknet.py`
- [Skip paths](https://github.com/shrillgig/semantic-segmentation/blob/main/linknet.py): feature fusion · Transfers encoder features directly to decoder stages · `linknet.py`

### PSPNet

Context-focused pyramid pooling segmentation model

- [PSPNet](https://github.com/shrillgig/semantic-segmentation/blob/main/pspnet.py): segmentation net · Multi-scale context network for dense prediction · `pspnet.py`
- [Backbone](https://github.com/shrillgig/semantic-segmentation/blob/main/pspnet.py): feature extractor · Produces the deepest feature map for context aggregation · `pspnet.py`
- [Pyramid pool](https://github.com/shrillgig/semantic-segmentation/blob/main/pspnet.py): context module · Pools features at multiple spatial scales and concatenates them · `pspnet.py`
- [Seg head](https://github.com/shrillgig/semantic-segmentation/blob/main/pspnet.py): prediction head · Converts pooled context into per-pixel class logits · `pspnet.py`

### Other components

- **Mask output**: dense logits · Final per-pixel class map or segmentation mask

## Connections

- main.py → U-Net: selects · Main entry can run the light U-Net path
- main.py → LinkNet: selects · Main entry can run the LinkNet path
- main.py → PSPNet: selects · Main entry can run the PSPNet path
- U-Net → Encoder: uses · U-Net begins with downsampling feature extraction
- Encoder → Bottleneck: compresses · Encoded features flow into the deepest block
- Bottleneck → Decoder: expands · Decoder restores resolution from the bottleneck
- Encoder → Skip links: routes · High-resolution features are routed to the decoder
- Skip links → Decoder: fuses · Skip features are merged during decoding
- Decoder → Mask output: predicts · Decoder produces dense segmentation logits
- LinkNet → Residual encoder: uses · LinkNet starts with residual feature extraction
- Residual encoder → Skip paths: routes · Encoder features are forwarded to matching decoder stages
- Residual encoder → Light decoder: feeds · Encoded representation enters the lightweight decoder
- Skip paths → Light decoder: fuses · Skip connections recover spatial detail
- Light decoder → Mask output: predicts · Decoder outputs the final segmentation mask
- PSPNet → Backbone: uses · PSPNet extracts deep features with a backbone encoder
- Backbone → Pyramid pool: aggregates · Deep features are pooled at multiple scales
- Pyramid pool → Seg head: refines · Multi-scale context is prepared for classification
- Seg head → Mask output: predicts · Segmentation head emits per-pixel logits