How shrillgig/semantic-segmentation works
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 main.py · unet_light.py Encoder · linknet.py Residual encoder · pspnet.py PSPNet
Components 15
Entry
Top-level orchestration boundary
- main.py · Chooses and runs a segmentation model workflow
main.py
Light U-Net
Lightweight encoder-decoder segmentation model
- U-Net · Lightweight U-Net variant for dense prediction
unet_light.py - Encoder · Downsamples input while growing feature depth
unet_light.py - Bottleneck · Compresses features at the lowest resolution
unet_light.py - Decoder · Restores spatial resolution toward the mask output
unet_light.py - Skip links · Carries high-resolution features around the bottleneck
unet_light.py
LinkNet
Efficient residual encoder-decoder segmentation model
- LinkNet · Residual-style encoder-decoder for efficient segmentation
linknet.py - Residual encoder · Builds hierarchical features with residual blocks
linknet.py - Light decoder · Reconstructs mask resolution with efficient upsampling
linknet.py - Skip paths · Transfers encoder features directly to decoder stages
linknet.py
PSPNet
Context-focused pyramid pooling segmentation model
- PSPNet · Multi-scale context network for dense prediction
pspnet.py - Backbone · Produces the deepest feature map for context aggregation
pspnet.py - Pyramid pool · Pools features at multiple spatial scales and concatenates them
pspnet.py - Seg head · Converts pooled context into per-pixel class logits
pspnet.py
Other components
- Mask output · Final per-pixel class map or segmentation mask
Connections 18
- 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