# chequanghuy/twinlitenet architecture

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

- Interactive diagram: https://gitdiagram.com/chequanghuy/twinlitenet
- Repository: https://github.com/chequanghuy/twinlitenet

## Overview

##### Project Type and Purpose
- TwinLiteNet is a pure machine‐learning pipeline for drivable‐area segmentation and lane detection. It is not a client-server or full-stack web app but an end-to-end deep-learning system that covers data ingestion, model definition, training, validation, inference, and export.

##### File Structure
Top‐level files and directories:
- DataSet.py         → Dataset class and data loader logic
- IOUEval.py         → Metric computation (IoU, lane metrics)
- const.py           → Global constants and configuration keys
- export.py          → Model‐export utilities (ONNX/TensorRT)
- loss.py            → Loss functions (segmentation + lane)
- model/             → Model architecture: TwinLite.py
- pretrained/        → Checkpoints (best.pth)
- train.py           → Training loop, optimizer, checkpointing
- val.py             → Validation loop
- test_image.py      → Offline inference on single images
- test_trt.py        → Inference with TensorRT engine
- utils.py           → Helper routines (logging, visualization)
- requirements.txt   → Dependencies

##### README for Insights
- Confirms the pipeline stages: Data Preparation → Training → Testing → Inference → Visualization.
- Specifies external dataset (BDD100K) and external libraries (PyTorch, TensorRT).

##### Main Components
a. Data Ingestion & Preprocessing
- Block: “BDD100K Data (images + annotations)”
- Component: DataSet.py
- Output: preprocessed batches
b. Model
- Block: “TwinLiteNet Architecture”
- Location: model/TwinLite.py
- Subcomponents: shared encoder, two decoders (drivable area head, lane head)
c. Loss & Metrics
- Block: “Loss Computation” → loss.py
- Block: “Metric Evaluation” → IOUEval.py
d. Training Orchestration
- Block: train.py
- Interactions: takes data batches and model, applies loss, optimizer, scheduler, checkpoints to pretrained/
e. Validation
- Block: val.py
- Interaction: loads checkpoint, runs data through model, computes metrics
f. Inference
- Blocks: test_image.py (PyTorch) and test_trt.py (TensorRT)
- export.py: ONNX/TensorRT conversion
g. Utilities
- utils.py: logging, visualization, saving images

##### Relationships and Data Flow
1. Raw Dataset → DataSet.py → DataLoader batches
2. Batches → TwinLiteNet → Predictions
3. Predictions + Ground Truth → loss.py → Loss
4. Loss → train.py optimizer step → updated model → checkpoint
5. Checkpoint → val.py → IOUEval.py → Metrics
6. Final Checkpoint → export.py → ONNX/TensorRT engine → test_trt.py
7. Inference outputs → utils.py → visualization

##### Architectural Patterns & Design Principles
- Modular separation of concerns: data / model / loss / orchestration / utils.
- Encoder–Decoder architecture with dual heads.
- Checkpointing for reproducibility.
- Export layer decoupled from core model.
- Use of external services (PyTorch, TensorRT) abstracted in export.py and test_trt.py.

##### Relevant Technologies
- Python 3.x, PyTorch (model training), TorchMetrics/Custom IOU (metrics),
- ONNX + TensorRT (export/inference acceleration), CUDA (GPU compute),
- Common libraries: numpy, opencv, tensorboard.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Stage
    subgraph "Data Ingestion" 
        BDD["BDD100K Data (images + annotations)"]:::external
        Data["Data Ingestion & Preprocessing\nDataSet.py"]:::data
        Const["Global Config & Constants\nconst.py"]:::config
    end

    %% Model Definition
    subgraph "Model Definition"
        Model["TwinLiteNet Architecture\nmodel/TwinLite.py"]:::model
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        Train["Training Loop\ntrain.py"]:::training
        Loss["Loss Computation\nloss.py"]:::training
        Metric["Metric Evaluation\nIOUEval.py"]:::training
        Checkpt["Pretrained Checkpoints\npretrained/best.pth"]:::storage
    end

    %% Validation
    subgraph "Validation Pipeline"
        Val["Validation Loop\nval.py"]:::training
    end

    %% Export & Inference
    subgraph "Export & Inference"
        Export["Model Export\nexport.py"]:::inference
        InferPT["Inference (PyTorch)\ntest_image.py"]:::inference
        InferTRT["Inference (TensorRT)\ntest_trt.py"]:::inference
    end

    %% Utilities & Docs & Config
    Utils["Utilities\nutils.py"]:::utils
    Req["Dependencies\nrequirements.txt"]:::config
    Doc["Documentation & Diagrams\nREADME.md, images/"]:::docs

    %% Data Flow
    BDD -->|"images+labels"| Data
    Const -->|"config params"| Data
    Data -->|"preprocessed batches"| Train
    Model -->|"model definition"| Train
    Train -->|"predictions + labels"| Loss
    Loss -->|"loss values"| Train
    Train -->|"updated weights"| Checkpt
    Checkpt -->|"load checkpoint"| Val
    Val -->|"predictions|labels"| Metric
    Metric -->|"evaluation metrics"| Val
    Val -->|"validated model"| Checkpt
    Checkpt -->|"final checkpoint"| Export
    Export -->|"ONNX/TensorRT engine"| InferTRT
    Checkpt -->|"load checkpoint"| InferPT
    Model -->|"architecture"| InferPT
    InferPT -->|"predictions"| Utils
    InferTRT -->|"predictions"| Utils

    %% Auxiliary
    Req -.->|specifies| Data
    Req -.->|specifies| Train
    Req -.->|specifies| Val
    Req -.->|specifies| Export
    Req -.->|specifies| InferPT
    Req -.->|specifies| InferTRT
    Utils -.->|logging/visualization| Train
    Utils -.->|logging/visualization| Val
    Doc -.->|overview| Data

    %% Click Events
    click Data "https://github.com/chequanghuy/twinlitenet/blob/main/DataSet.py"
    click Const "https://github.com/chequanghuy/twinlitenet/blob/main/const.py"
    click Model "https://github.com/chequanghuy/twinlitenet/blob/main/model/TwinLite.py"
    click Train "https://github.com/chequanghuy/twinlitenet/blob/main/train.py"
    click Loss "https://github.com/chequanghuy/twinlitenet/blob/main/loss.py"
    click Metric "https://github.com/chequanghuy/twinlitenet/blob/main/IOUEval.py"
    click Checkpt "https://github.com/chequanghuy/twinlitenet/blob/main/pretrained/best.pth"
    click Val "https://github.com/chequanghuy/twinlitenet/blob/main/val.py"
    click Export "https://github.com/chequanghuy/twinlitenet/blob/main/export.py"
    click InferPT "https://github.com/chequanghuy/twinlitenet/blob/main/test_image.py"
    click InferTRT "https://github.com/chequanghuy/twinlitenet/blob/main/test_trt.py"
    click Utils "https://github.com/chequanghuy/twinlitenet/blob/main/utils.py"
    click Req "https://github.com/chequanghuy/twinlitenet/blob/main/requirements.txt"
    click Doc "https://github.com/chequanghuy/twinlitenet/blob/main/README.md"
    click Doc "https://github.com/chequanghuy/twinlitenet/tree/main/images/"

    %% Styles
    classDef data fill:#D0E1F9,stroke:#03396C,color:#03396C;
    classDef model fill:#E2F0CB,stroke:#4F772D,color:#4F772D;
    classDef training fill:#FFD8B1,stroke:#FF6F00,color:#FF6F00;
    classDef inference fill:#EAD1DC,stroke:#C71585,color:#C71585;
    classDef utils fill:#F0F0F0,stroke:#606060,color:#404040;
    classDef external fill:#CCE5FF,stroke:#6699CC,color:#336699;
    classDef storage fill:#FFEFD5,stroke:#FFB347,color:#FF8C00;
    classDef config fill:#FFF2CC,stroke:#E1AD01,color:#B08600;
    classDef docs fill:#FDE7E7,stroke:#D9534F,color:#C12E2A;
```
