|
| 1 | +--- |
| 2 | +date: '2026-03-23T09:15:13-04:00' |
| 3 | +title: Adver-City ML Workflow |
| 4 | +draft: false |
| 5 | +tags: ["featured"] |
| 6 | +categories: ["project"] |
| 7 | +ShowToc: true |
| 8 | +--- |
| 9 | + |
| 10 | +This project implements a **Machine Learning (ML) pipeline** for the [Adver-City](https://labs.cs.queensu.ca/quarrg/datasets/adver-city/) synthetic dataset. The dataset is designed for investigating **cooperative perception** in autonomous vehicles. Overall, this project enables efficient, reproducible modelling of the Adver-City dataset through ML workflows. We have chosen to train a model to identify weather conditions (clear, fog, rain) from nighttime images. |
| 11 | + |
| 12 | +Note: full GitRepo available [here](https://github.com/tjards/adver-city-ETL). |
| 13 | + |
| 14 | +<figure> |
| 15 | + <img src="/img/2026/example_view.gif" alt="Example Scenario (foggy)" width="800" style="border: 1px solid #ddd; border-radius: 8px; padding: 8px; background-color: #f9f9f9;"> |
| 16 | + <figcaption style="text-align: center; margin-top: 12px; font-style: italic; color: #666;"> |
| 17 | + <strong>Figure 1:</strong> Example Scenario (foggy) from the Adver-City dataset. The dataset contains images of a variety of weather conditions (clear, fog, rain) and times of day (day, night). In this project we focus on classifying weather conditions from nighttime images. |
| 18 | + </figcaption> |
| 19 | +</figure> |
| 20 | + |
| 21 | +## Operation |
| 22 | + |
| 23 | +The project is organized into four main stages. Depending on what your goal is (data exploration, ingestion, or training), the notebooks indicated below describe how to run each stage of the workflow. |
| 24 | + |
| 25 | +1. **Initial Data Exploration:** A detailed [readme](./docs/README_ETL.md) has been provided to describe the Extract, Transform, and Load (ETL) process. This is complemented by a [notebook](./notebooks/initial_explore.ipynb) that walks through an exploration of the dataset. |
| 26 | + |
| 27 | +2. **Data Ingestion Pipeline:** The pipeline selectively ingests data from the [FRDR remote server](https://www.frdr-dfdr.ca/repo/dataset/3bda7692-779f-4cbd-b806-b8aa69d5dff9), extracts files based on a sampling plan, creates labels, and generates clean train/val/test splits. A detailed [notebook](./notebooks/data_ingestion_pipeline.ipynb) describes the data ingestion pipeline, including how data is ingested, sampled, and prepared for training. |
| 28 | + |
| 29 | +3. **Data Management Pipeline:** A detailed [notebook](./notebooks/data_management_pipeline.ipynb) describes the data management pipeline, including how the data is cleaned and transformed. A custom Dataset class is defined for use with PyTorch DataLoader. Some Preprocessing (resizing, normalization, and augmentation) is applied to the data. |
| 30 | + |
| 31 | +4. **Training and Testing Pipeline:** A detailed [notebook](./notebooks/training_pipeline.ipynb) describes the training and testing pipeline, including how to train a model, save checkpoints, and evaluate performance on a test set. |
| 32 | + |
| 33 | +## Project Structure |
| 34 | + |
| 35 | +We have organized the project into a modular structure to facilitate efficient development and reproducibility. The main directories and their purposes are as follows: |
| 36 | + |
| 37 | +``` |
| 38 | +pytorch_project_advercity/ |
| 39 | +├── README.md |
| 40 | +├── requirements.txt # required packages and their versions |
| 41 | +├── venv/ # virtual environment for project dependencies |
| 42 | +├── config/ |
| 43 | +│ └── config.json # all configuration parameters stored here |
| 44 | +├── data/ # raw and processed data stored here |
| 45 | +│ ├── index/ |
| 46 | +│ ├── raw/ |
| 47 | +│ ├── ready/ # train, val, test splits stored here |
| 48 | +│ └── sampled/ |
| 49 | +├── docs/ |
| 50 | +│ └── README_ETL.md |
| 51 | +├── exploration/ |
| 52 | +│ ├── __init__.py |
| 53 | +│ ├── utils.py |
| 54 | +│ └── data/ |
| 55 | +├── master_scripts/ # useful master scripts for data pipelines |
| 56 | +│ ├── __init__.py |
| 57 | +│ ├── data_management_pipeline.py |
| 58 | +│ ├── ETL_pipeline.py |
| 59 | +│ └── __pycache__/ |
| 60 | +├── notebooks/ # notebooks for each stage of the workflow |
| 61 | +│ ├── data_ingestion_pipeline.ipynb |
| 62 | +│ ├── data_management_pipeline.ipynb |
| 63 | +│ ├── initial_explore.ipynb |
| 64 | +│ ├── training_pipeline.ipynb |
| 65 | +│ └── img/ |
| 66 | +├── results/ |
| 67 | +│ └── # models and their training results saved here |
| 68 | +├── src/ # the main source code for the project |
| 69 | +│ ├── __init__.py |
| 70 | +│ ├── __pycache__/ |
| 71 | +│ ├── data_management/ |
| 72 | +│ ├── ingestion/ |
| 73 | +│ ├── testing/ |
| 74 | +│ ├── training/ # model definitions stored here |
| 75 | +│ └── utils/ |
| 76 | +``` |
| 77 | + |
| 78 | +## Results |
| 79 | + |
| 80 | +We trained a Convolutional Neural Network (CNN) model to classify weather conditions (clear, fog, rain) from nighttime images. The architecture of the model can be found in the `src/training/model_definitions.py` file. |
| 81 | + |
| 82 | +Models and metrics are saved incrementally during training (using checkpoints) and the **best** model is updated along the way. Below shows an example of the results directory structure for a single training run. Each training run is saved in a separate subdirectory with a unique name (based on the experiment name defined in the config file) and timestamp. |
| 83 | + |
| 84 | +``` |
| 85 | +results/ |
| 86 | +└── advercity_weather_classification_128x128_20260322_110258/ |
| 87 | + ├── best_model.pt |
| 88 | + ├── config.json |
| 89 | + ├── final_model.pt |
| 90 | + ├── metrics.json |
| 91 | + └── checkpoints/ |
| 92 | + ├── epoch_1.pt |
| 93 | + ├── epoch_2.pt |
| 94 | + ├── epoch_3.pt |
| 95 | + └── latest.pt |
| 96 | +``` |
| 97 | + |
| 98 | +### Training and Validation |
| 99 | + |
| 100 | +The model was trained on the **train** set split and validated on the **val** set split. The training process was monitored using the validation set to track performance and prevent overfitting. |
| 101 | +<figure> |
| 102 | + <img src="/img/2026/training_results.png" alt="Training Results Visualization" width="800" style="border: 1px solid #ddd; border-radius: 8px; padding: 8px; background-color: #f9f9f9;"> |
| 103 | + <figcaption style="text-align: center; margin-top: 12px; font-style: italic; color: #666;"> |
| 104 | + <strong>Figure 2:</strong> Training performance metrics show accuracy of our model improving over 10 epochs, with the best model achieving about 96% accuracy on the validation set. |
| 105 | + </figcaption> |
| 106 | +</figure> |
| 107 | + |
| 108 | +### Testing |
| 109 | + |
| 110 | +As shown in the [Training and Testing Pipeline notebook](./notebooks/training_pipeline.ipynb), the model above was tested on a separate **test** set split. The accuracy of the model on this split was 96.26%, consistent with the validation performance. |
| 111 | + |
| 112 | +## Conclusion |
| 113 | + |
| 114 | +In this project we implemented a complete ML workflow for the Adver-City dataset, including data ingestion, data management, training, and testing. The modular structure of the codebase allows for efficient development and reproducibility. The trained model achieved high accuracy in classifying weather conditions as clear, foggy, or rainy from nighttime images, demonstrating the effectiveness of our approach. |
| 115 | + |
| 116 | +## References |
| 117 | + |
| 118 | +**Karvat, M., & Givigi, S. (2024).** [Adver-City: Open-Source Multi-Modal Dataset for Collaborative Perception Under Adverse Weather Conditions](https://arxiv.org/abs/2410.06380). *arXiv preprint arXiv:2410.06380*. |
0 commit comments