How khaliladib11/msc_thesis works
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: bdd.py BDD dataset · segmentation_models.py Seg models · fasterrcnn.yaml Task configs · train.py Train
Components 30
Data pipeline
Dataset manifests, conversion, and external data acquisition.
- BDD dataset · Common BDD100K dataset superclass used by task-specific loaders.
src/dataset/bdd.py - Detection data · BDD detection dataset specialization and target formatting.
src/dataset/bdd_detetcion.py - Drivable data · BDD drivable-area segmentation dataset specialization.
src/dataset/bdd_drivable_segmentation.py - Instance data · BDD instance segmentation dataset specialization.
src/dataset/bdd_instance_segmentation.py - Mixed data · Combined instance and drivable segmentation dataset specialization.
src/dataset/bdd_instance_segmentation_drivable.py - BDD utils · Shared BDD100K parsing and dataset helper functions.
src/dataset/bdd_utils.py - Split dbs · Prepared train, validation, and test split manifests.
src/dbs/train_db.json - Task configs · Model-specific dataset configuration files for detection, segmentation, and YOLO formats.
data/fasterrcnn.yaml - Prepare data · Converts BDD annotations into YOLO-compatible layout and labels.
prepare.py
Model stack
Task-specific model wrappers and selection boundaries.
- Detect models · Detection model factory and task boundary.
src/models/Detection/detection_models.py - Faster R-CNN · Faster R-CNN model wrapper.
src/models/Detection/Faster_RCNN.py - Seg models · Segmentation model factory and task boundary.
src/models/Segmentation/segmentation_models.py - FCN · FCN model wrapper.
src/models/Segmentation/FCN.py - DeepLab · DeepLab model wrapper.
src/models/Segmentation/DeepLab.py - Mask R-CNN · Mask R-CNN model wrapper.
src/models/Segmentation/MaskRCNN.py
Runtime
Training, evaluation, inference, serving, and shared utilities.
- Fetch assets · Downloads data and weights from external storage.
scripts/weights.py - Fetch data · Downloads dataset assets from external storage.
scripts/data.py - Defaults · Central default experiment parameters.
src/config/defaults.py - Data loaders · Adapts dataset classes into runtime dataloaders.
src/utils/DataLoaders.py - Shared utils · Cross-cutting helper functions for training, evaluation, and inference.
src/utils/utils.py - Model helpers · Shared model utility functions used across task families.
src/utils/models.py - Train · Training workflow for detection and segmentation models.
train.py - Test · Model evaluation and mAP computation.
test.py - Detect · Single-image inference script.
detect.py - Results · Aggregates and displays experiment outcomes.
results.py - YOLO eval · Evaluates YOLO predictions against ground truth.
yolo_eval.py - Flask API · Lightweight inference service for demo or integration use.
api/app.py
Research outputs
Documentation, notebooks, and thesis artifacts.
- Notebooks · Research notebooks for EDA, augmentation, and model experiments.
notebooks/Exploratory Data Analysis.ipynb - Src notebooks · In-repo notebooks for dataset and model experimentation.
src/BDD Detection.ipynb - Thesis docs · Thesis PDF and generated figures.
doc/Khalil_Adib_MSc_AI_Thesis.pdf
Connections 35
- 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.