# khaliladib11/msc_thesis architecture

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

- Interactive diagram: https://gitdiagram.com/khaliladib11/msc_thesis
- Repository: https://github.com/khaliladib11/msc_thesis

## Overview

1. This repository is a computer-vision thesis project centered on BDD100K. The architecture is organized around one shared data pipeline and several task-specific model paths: object detection, semantic segmentation, instance segmentation, and YOLO-based detection comparisons.

2. The core domain boundary is the dataset layer under `src/dataset`. `bdd.py` acts as the shared dataset superclass, while the other modules specialize it for detection, drivable-area segmentation, instance segmentation, and combined instance/drivable segmentation. These classes encapsulate BDD100K label parsing, sample construction, and task-specific target formatting.

3. Dataset metadata is pre-split in `src/dbs/train_db.json`, `val_db.json`, and `test_db.json`, which suggests the repository uses prepared split manifests rather than building splits dynamically at runtime. The `data/*.yaml` files provide model- and task-specific dataset configuration, especially for Faster R-CNN, Mask R-CNN, DeepLab, FCN, and YOLO formats.

4. Model code is separated by task family under `src/models`. Detection models live in `src/models/Detection` with a Faster R-CNN wrapper and a factory-like module for instantiation. Segmentation models live in `src/models/Segmentation` and include FCN, DeepLab, and Mask R-CNN wrappers plus a model-selection module. This keeps architecture boundaries clean between detection and segmentation while allowing the training/evaluation scripts to select a model by name.

5. Shared runtime utilities sit in `src/utils`. `DataLoaders.py` likely adapts the dataset classes into PyTorch dataloaders, while `utils.py` and `models.py` contain helper logic used across training, testing, and inference. `src/config/defaults.py` provides default configuration, acting as the central parameter boundary for experiments.

6. The top-level execution scripts form the main workflow. `train.py` handles training for Faster R-CNN and Mask R-CNN; `test.py` evaluates models, including mAP computation; `detect.py` runs single-image inference; `results.py` aggregates and displays experiment outcomes; `yolo_eval.py` evaluates YOLO predictions against ground truth. `util.py` appears to hold cross-cutting helper functions for these flows.

7. YOLO is treated as an external subsystem rather than a native implementation. The repo includes conversion support in `prepare.py`, which transforms BDD100K annotations into YOLO-compatible images/labels and writes outputs into external YOLO repository folders. The README explicitly expects separate cloned copies of YOLOv5, YOLOv6, and YOLOv7, so those models live outside this codebase and are integrated via file-format contracts and command-line handoff.

8. The data conversion boundary is important. Native BDD formats are used for Faster R-CNN / Mask R-CNN / segmentation training, while YOLO training requires a preprocessing step that writes a new dataset layout and label format. `prepare.py` and the `data/dataset_yolov5.yaml`, `data/dataset_yolov7.yaml`, and `data/yolo.yaml` files are the bridge between internal annotations and the external YOLO training pipelines.

9. There is a lightweight serving boundary under `api/app.py`, which exposes a Flask app for inference. This likely wraps the same model-loading and prediction logic used by `detect.py`, giving the repository both batch/script usage and a simple server interface for demo or integration purposes.

10. Data acquisition and weights are handled as separate operational concerns in `scripts/data.py` and `scripts/weights.py`, which download from Google Drive. That means the repo assumes large artifacts are not versioned in Git and must be fetched before training or inference.

11. The notebooks under `src/`, `notebooks/`, and `src/utils` are exploratory and instructional rather than production runtime. They document EDA, augmentation, format conversion, and model-specific experimentation, so they support the architecture but are not part of the core execution path.

12. Documentation and results are first-class outputs: `doc/images` contains figures used in the thesis/readme, and `doc/Khalil_Adib_MSc_AI_Thesis.pdf` is the thesis artifact itself. Architecturally, this repo is therefore a research workspace with three main flows: dataset preparation, model training/evaluation, and inference/demo serving.

Main entry points: [`src/dataset/bdd.py`](https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd.py) (BDD dataset), [`src/models/Segmentation/segmentation_models.py`](https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Segmentation/segmentation_models.py) (Seg models), [`data/fasterrcnn.yaml`](https://github.com/khaliladib11/msc_thesis/blob/main/data/fasterrcnn.yaml) (Task configs), [`train.py`](https://github.com/khaliladib11/msc_thesis/blob/main/train.py) (Train)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_data["Data pipeline"]
  node_n_bdd["BDD dataset<br/>shared dataset base<br/>[bdd.py]"]
  node_n_det_ds["Detection data<br/>dataset adapter<br/>[bdd_detetcion.py]"]
  node_n_drv_ds["Drivable data<br/>dataset adapter"]
  node_n_inst_ds["Instance data<br/>dataset adapter"]
  node_n_mix_ds["Mixed data<br/>dataset adapter"]
  node_n_bdd_utils["BDD utils<br/>label parsing<br/>[bdd_utils.py]"]
  node_n_db[("Split dbs<br/>manifest set<br/>[train_db.json]")]
  node_n_yaml["Task configs<br/>dataset config<br/>[fasterrcnn.yaml]"]
  node_n_prepare["Prepare data<br/>conversion pipeline<br/>[prepare.py]"]
end

subgraph group_grp_models["Model stack"]
  node_n_det_models["Detect models<br/>model selector"]
  node_n_frcnn["Faster R-CNN<br/>detection wrapper<br/>[Faster_RCNN.py]"]
  node_n_seg_models["Seg models<br/>model selector"]
  node_n_fcn["FCN<br/>segmentation wrapper<br/>[FCN.py]"]
  node_n_deeplab["DeepLab<br/>segmentation wrapper<br/>[DeepLab.py]"]
  node_n_maskrcnn["Mask R-CNN<br/>segmentation wrapper<br/>[MaskRCNN.py]"]
end

subgraph group_grp_runtime["Runtime"]
  node_n_weights["Fetch assets<br/>artifact download<br/>[weights.py]"]
  node_n_data["Fetch data<br/>artifact download<br/>[data.py]"]
  node_n_cfg["Defaults<br/>experiment config<br/>[defaults.py]"]
  node_n_dl["Data loaders<br/>loader bridge<br/>[DataLoaders.py]"]
  node_n_utils["Shared utils<br/>runtime helpers<br/>[utils.py]"]
  node_n_model_utils["Model helpers<br/>runtime helpers<br/>[models.py]"]
  node_n_train["Train<br/>[train.py]"]
  node_n_test["Test<br/>evaluation entrypoint<br/>[test.py]"]
  node_n_detect["Detect<br/>inference entrypoint<br/>[detect.py]"]
  node_n_results["Results<br/>reporting entrypoint<br/>[results.py]"]
  node_n_yolo_eval["YOLO eval<br/>evaluation entrypoint<br/>[yolo_eval.py]"]
  node_n_api["Flask API<br/>serving app<br/>[app.py]"]
end

subgraph group_grp_artifacts["Research outputs"]
  node_n_notebooks["Notebooks<br/>exploration"]
  node_n_src_nb["Src notebooks<br/>exploration"]
  node_n_doc["Thesis docs<br/>publication artifacts"]
end

node_n_bdd -->|"base class"| node_n_det_ds
node_n_bdd -->|"base class"| node_n_drv_ds
node_n_bdd -->|"base class"| node_n_inst_ds
node_n_bdd -->|"base class"| node_n_mix_ds
node_n_bdd_utils -->|"parsing"| node_n_bdd
node_n_db -->|"splits"| node_n_bdd
node_n_yaml -->|"configures"| node_n_det_ds
node_n_yaml -->|"configures"| node_n_drv_ds
node_n_yaml -->|"configures"| node_n_inst_ds
node_n_yaml -->|"bridges"| node_n_prepare
node_n_prepare -->|"writes"| node_n_yaml
node_n_data -->|"downloads"| node_n_db
node_n_weights -->|"supports"| node_n_train
node_n_cfg -->|"configures"| node_n_train
node_n_cfg -->|"configures"| node_n_test
node_n_dl -->|"feeds"| node_n_train
node_n_dl -->|"feeds"| node_n_test
node_n_model_utils -->|"supports"| node_n_det_models
node_n_model_utils -->|"supports"| node_n_seg_models
node_n_det_models -->|"selects"| node_n_frcnn
node_n_seg_models -->|"selects"| node_n_fcn
node_n_seg_models -->|"selects"| node_n_deeplab
node_n_seg_models -->|"selects"| node_n_maskrcnn
node_n_train -->|"uses"| node_n_det_models
node_n_train -->|"uses"| node_n_seg_models
node_n_test -->|"evaluates"| node_n_det_models
node_n_test -->|"evaluates"| node_n_seg_models
node_n_detect -->|"loads"| node_n_model_utils
node_n_detect -->|"uses"| node_n_utils
node_n_api -->|"wraps"| node_n_detect
node_n_results -->|"summarizes"| node_n_test
node_n_yolo_eval -->|"consumes"| node_n_prepare
node_n_notebooks -.->|"explores"| node_n_prepare
node_n_src_nb -.->|"explores"| node_n_bdd
node_n_doc -.->|"documents"| node_n_results

click node_n_bdd "https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd.py"
click node_n_det_ds "https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd_detetcion.py"
click node_n_drv_ds "https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd_drivable_segmentation.py"
click node_n_inst_ds "https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd_instance_segmentation.py"
click node_n_mix_ds "https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd_instance_segmentation_drivable.py"
click node_n_bdd_utils "https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd_utils.py"
click node_n_db "https://github.com/khaliladib11/msc_thesis/blob/main/src/dbs/train_db.json"
click node_n_yaml "https://github.com/khaliladib11/msc_thesis/blob/main/data/fasterrcnn.yaml"
click node_n_prepare "https://github.com/khaliladib11/msc_thesis/blob/main/prepare.py"
click node_n_weights "https://github.com/khaliladib11/msc_thesis/blob/main/scripts/weights.py"
click node_n_data "https://github.com/khaliladib11/msc_thesis/blob/main/scripts/data.py"
click node_n_cfg "https://github.com/khaliladib11/msc_thesis/blob/main/src/config/defaults.py"
click node_n_dl "https://github.com/khaliladib11/msc_thesis/blob/main/src/utils/DataLoaders.py"
click node_n_utils "https://github.com/khaliladib11/msc_thesis/blob/main/src/utils/utils.py"
click node_n_model_utils "https://github.com/khaliladib11/msc_thesis/blob/main/src/utils/models.py"
click node_n_det_models "https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Detection/detection_models.py"
click node_n_frcnn "https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Detection/Faster_RCNN.py"
click node_n_seg_models "https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Segmentation/segmentation_models.py"
click node_n_fcn "https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Segmentation/FCN.py"
click node_n_deeplab "https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Segmentation/DeepLab.py"
click node_n_maskrcnn "https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Segmentation/MaskRCNN.py"
click node_n_train "https://github.com/khaliladib11/msc_thesis/blob/main/train.py"
click node_n_test "https://github.com/khaliladib11/msc_thesis/blob/main/test.py"
click node_n_detect "https://github.com/khaliladib11/msc_thesis/blob/main/detect.py"
click node_n_results "https://github.com/khaliladib11/msc_thesis/blob/main/results.py"
click node_n_yolo_eval "https://github.com/khaliladib11/msc_thesis/blob/main/yolo_eval.py"
click node_n_api "https://github.com/khaliladib11/msc_thesis/blob/main/api/app.py"
click node_n_notebooks "https://github.com/khaliladib11/msc_thesis/blob/main/notebooks/Exploratory Data Analysis.ipynb"
click node_n_src_nb "https://github.com/khaliladib11/msc_thesis/blob/main/src/BDD Detection.ipynb"
click node_n_doc "https://github.com/khaliladib11/msc_thesis/blob/main/doc/Khalil_Adib_MSc_AI_Thesis.pdf"

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_n_bdd,node_n_det_ds,node_n_drv_ds,node_n_inst_ds,node_n_mix_ds,node_n_bdd_utils,node_n_db,node_n_yaml,node_n_prepare toneBlue
class node_n_det_models,node_n_frcnn,node_n_seg_models,node_n_fcn,node_n_deeplab,node_n_maskrcnn toneAmber
class node_n_weights,node_n_data,node_n_cfg,node_n_dl,node_n_utils,node_n_model_utils,node_n_train,node_n_test,node_n_detect,node_n_results,node_n_yolo_eval,node_n_api toneMint
class node_n_notebooks,node_n_src_nb,node_n_doc toneRose
```

## Components

### Data pipeline

Dataset manifests, conversion, and external data acquisition.

- [BDD dataset](https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd.py): shared dataset base · Common BDD100K dataset superclass used by task-specific loaders. · `src/dataset/bdd.py`
- [Detection data](https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd_detetcion.py): dataset adapter · BDD detection dataset specialization and target formatting. · `src/dataset/bdd_detetcion.py`
- [Drivable data](https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd_drivable_segmentation.py): dataset adapter · BDD drivable-area segmentation dataset specialization. · `src/dataset/bdd_drivable_segmentation.py`
- [Instance data](https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd_instance_segmentation.py): dataset adapter · BDD instance segmentation dataset specialization. · `src/dataset/bdd_instance_segmentation.py`
- [Mixed data](https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd_instance_segmentation_drivable.py): dataset adapter · Combined instance and drivable segmentation dataset specialization. · `src/dataset/bdd_instance_segmentation_drivable.py`
- [BDD utils](https://github.com/khaliladib11/msc_thesis/blob/main/src/dataset/bdd_utils.py): label parsing · Shared BDD100K parsing and dataset helper functions. · `src/dataset/bdd_utils.py`
- [Split dbs](https://github.com/khaliladib11/msc_thesis/blob/main/src/dbs/train_db.json): manifest set · Prepared train, validation, and test split manifests. · `src/dbs/train_db.json`
- [Task configs](https://github.com/khaliladib11/msc_thesis/blob/main/data/fasterrcnn.yaml): dataset config · Model-specific dataset configuration files for detection, segmentation, and YOLO formats. · `data/fasterrcnn.yaml`
- [Prepare data](https://github.com/khaliladib11/msc_thesis/blob/main/prepare.py): conversion pipeline · Converts BDD annotations into YOLO-compatible layout and labels. · `prepare.py`

### Model stack

Task-specific model wrappers and selection boundaries.

- [Detect models](https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Detection/detection_models.py): model selector · Detection model factory and task boundary. · `src/models/Detection/detection_models.py`
- [Faster R-CNN](https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Detection/Faster_RCNN.py): detection wrapper · Faster R-CNN model wrapper. · `src/models/Detection/Faster_RCNN.py`
- [Seg models](https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Segmentation/segmentation_models.py): model selector · Segmentation model factory and task boundary. · `src/models/Segmentation/segmentation_models.py`
- [FCN](https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Segmentation/FCN.py): segmentation wrapper · FCN model wrapper. · `src/models/Segmentation/FCN.py`
- [DeepLab](https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Segmentation/DeepLab.py): segmentation wrapper · DeepLab model wrapper. · `src/models/Segmentation/DeepLab.py`
- [Mask R-CNN](https://github.com/khaliladib11/msc_thesis/blob/main/src/models/Segmentation/MaskRCNN.py): segmentation wrapper · Mask R-CNN model wrapper. · `src/models/Segmentation/MaskRCNN.py`

### Runtime

Training, evaluation, inference, serving, and shared utilities.

- [Fetch assets](https://github.com/khaliladib11/msc_thesis/blob/main/scripts/weights.py): artifact download · Downloads data and weights from external storage. · `scripts/weights.py`
- [Fetch data](https://github.com/khaliladib11/msc_thesis/blob/main/scripts/data.py): artifact download · Downloads dataset assets from external storage. · `scripts/data.py`
- [Defaults](https://github.com/khaliladib11/msc_thesis/blob/main/src/config/defaults.py): experiment config · Central default experiment parameters. · `src/config/defaults.py`
- [Data loaders](https://github.com/khaliladib11/msc_thesis/blob/main/src/utils/DataLoaders.py): loader bridge · Adapts dataset classes into runtime dataloaders. · `src/utils/DataLoaders.py`
- [Shared utils](https://github.com/khaliladib11/msc_thesis/blob/main/src/utils/utils.py): runtime helpers · Cross-cutting helper functions for training, evaluation, and inference. · `src/utils/utils.py`
- [Model helpers](https://github.com/khaliladib11/msc_thesis/blob/main/src/utils/models.py): runtime helpers · Shared model utility functions used across task families. · `src/utils/models.py`
- [Train](https://github.com/khaliladib11/msc_thesis/blob/main/train.py): training entrypoint · Training workflow for detection and segmentation models. · `train.py`
- [Test](https://github.com/khaliladib11/msc_thesis/blob/main/test.py): evaluation entrypoint · Model evaluation and mAP computation. · `test.py`
- [Detect](https://github.com/khaliladib11/msc_thesis/blob/main/detect.py): inference entrypoint · Single-image inference script. · `detect.py`
- [Results](https://github.com/khaliladib11/msc_thesis/blob/main/results.py): reporting entrypoint · Aggregates and displays experiment outcomes. · `results.py`
- [YOLO eval](https://github.com/khaliladib11/msc_thesis/blob/main/yolo_eval.py): evaluation entrypoint · Evaluates YOLO predictions against ground truth. · `yolo_eval.py`
- [Flask API](https://github.com/khaliladib11/msc_thesis/blob/main/api/app.py): serving app · Lightweight inference service for demo or integration use. · `api/app.py`

### Research outputs

Documentation, notebooks, and thesis artifacts.

- [Notebooks](https://github.com/khaliladib11/msc_thesis/blob/HEAD/notebooks/Exploratory%20Data%20Analysis.ipynb): exploration · Research notebooks for EDA, augmentation, and model experiments. · `notebooks/Exploratory Data Analysis.ipynb`
- [Src notebooks](https://github.com/khaliladib11/msc_thesis/blob/HEAD/src/BDD%20Detection.ipynb): exploration · In-repo notebooks for dataset and model experimentation. · `src/BDD Detection.ipynb`
- [Thesis docs](https://github.com/khaliladib11/msc_thesis/blob/main/doc/Khalil_Adib_MSc_AI_Thesis.pdf): publication artifacts · Thesis PDF and generated figures. · `doc/Khalil_Adib_MSc_AI_Thesis.pdf`

## Connections

- BDD dataset → Detection data: base class · Detection dataset specialization extends shared BDD behavior.
- BDD dataset → Drivable data: base class · Drivable-area dataset specialization extends shared BDD behavior.
- BDD dataset → Instance data: base class · Instance segmentation dataset specialization extends shared BDD behavior.
- BDD dataset → Mixed data: base class · Combined segmentation dataset specialization extends shared BDD behavior.
- BDD utils → BDD dataset: parsing · Shared parsing and helper logic supports dataset construction.
- Split dbs → BDD dataset: splits · Prepared manifests provide train/val/test samples to the dataset layer.
- Task configs → Detection data: configures · Dataset YAML files define task-specific input and label conventions.
- Task configs → Drivable data: configures · Dataset YAML files define task-specific input and label conventions.
- Task configs → Instance data: configures · Dataset YAML files define task-specific input and label conventions.
- Task configs → Prepare data: bridges · YOLO configs connect prepared outputs to external YOLO training.
- Prepare data → Task configs: writes · Conversion step produces YOLO-compatible dataset layout and labels.
- Fetch data → Split dbs: downloads · Dataset artifacts are fetched before training or evaluation.
- Fetch assets → Train: supports · Pretrained or auxiliary weights feed runtime workflows.
- Defaults → Train: configures · Default parameters shape training runs.
- Defaults → Test: configures · Default parameters shape evaluation runs.
- Data loaders → Train: feeds · Dataloaders supply batches to training.
- Data loaders → Test: feeds · Dataloaders supply batches to evaluation.
- Model helpers → Detect models: supports · Shared model helpers support detection model construction.
- Model helpers → Seg models: supports · Shared model helpers support segmentation model construction.
- Detect models → Faster R-CNN: selects · Detection selector instantiates the Faster R-CNN wrapper.
- Seg models → FCN: selects · Segmentation selector instantiates the FCN wrapper.
- Seg models → DeepLab: selects · Segmentation selector instantiates the DeepLab wrapper.
- Seg models → Mask R-CNN: selects · Segmentation selector instantiates the Mask R-CNN wrapper.
- Train → Detect models: uses · Training selects detection models by name.
- Train → Seg models: uses · Training selects segmentation models by name.
- Test → Detect models: evaluates · Evaluation loads detection model family.
- Test → Seg models: evaluates · Evaluation loads segmentation model family.
- Detect → Model helpers: loads · Inference reuses shared model loading logic.
- Detect → Shared utils: uses · Inference relies on shared runtime helpers.
- Flask API → Detect: wraps · Serving layer likely wraps the same inference path as detect.py.
- Results → Test: summarizes · Results aggregation consumes evaluation outputs.
- YOLO eval → Prepare data: consumes · YOLO evaluation assumes the converted dataset contract.
- Notebooks → Prepare data: explores · Notebooks document conversion and experimentation.
- Src notebooks → BDD dataset: explores · In-repo notebooks illustrate dataset-specific experiments.
- Thesis docs → Results: documents · Thesis and figures capture final research outputs.
