Shady Shenanigans

---

Introduction

Shady Shenanigans is a deep learning model based off Deep Umbra and pix2pix. It is a Generative Adversarial Network designed to generate Tree-Aware Urban Shade Maps, based off of outputs generated by Lukas Beuster's Slim Shady project. The goal of this model is to speed up the workflow described by Lukas, and generate high quality tree-aware urban shade rasters with fewer inputs and higher speed.

This repository has two branches, one being the MAIN branch which contains the code used for the $M_{1*}$ models (those without the vegetation mask in the input). The other branch is TREE_SEGMENTATION which contains the changed code used for the $M_{2*}$ models (those that include the vegetation mask in the input) as well as some updated visualization code used to support the production of the thesis report.

Said report is still a work in progress, and a link will be visible here when it has been published.

---

Installation

This project has been run and tested using Python 3.13.9, it is recommended to use this or a higher version. It is not guranteed that this project will function as intended on a different version of Python.

The primary requirements for the project are outlined in the included requirements.txt file. It is recommended to use a separate Python environment when running the program. To set up the python environment, you can do the following:

python3 -m venv shady_environment
source shady_environment/bim/activate

Alternatively, you can utilize built in environment handling from an IDE like PyCharm.

Once your environment is created and activated, install the requirements file:

pip install -r requirements.txt

The environment should now be fully set up and prepared to run the project code.

---

Training Dataset Setup

To create the CSV file that is needed by dataset.py, the method write_dataset_csv must be run. This method expects as input a data_path which points to a folder structure that matches the following:

data_path_root    
└───<osmid_1>
│   └───input
│   │   │   <osmid_1>_p_1_<date>_dsm.tif
│   │   │   <osmid_1>_p_2_<date>_dsm.tif
│   │   │   ...
│   │
│   └───masks
│   │   │   <osmid_1>_p_1_<date>_rgb_segmented.tif
│   │   │   <osmid_1>_p_2_<date>_rgb_segmented.tif
│   │   │   ...
│   │
│   └───targets
│       └───tile_1
│       │    │   <osmid_1>_p_1_Shadow_<date>_<time1>_dsm.tif
│       │    │   <osmid_1>_p_1_Shadow_<date>_<time2>_dsm.tif
│       │    │   ...
│       │
│       └───tile_2
│       ...
│   
└───<osmid_2>

In this case, the training data was generated using the Slim Shady code. Note that the masks folder is only necessary if you are on the TREE_SEGMENTATION branch.

Once the function has been run, it will generate a CSV file called dataset.csv in the resources folder of the project.

---

Model Training

The model described in the report was trained on the Delft AI Cluster. The code itself ran in an Apptainer environment, and the train_slurm_distributed.sbatch file is used to manage the SLURM job that runs the model training code.

The model training is defined in train_validate.py. It assumes that the code is running on the AI cluster, and thus expects an environment with multiple CUDA GPUs. If you are not running on such an environment, simply modify the fabric.launch command on line 35 to fit the specifications of the system that you are using.

The file can be run in the terminal using Python:

usage: train_validate.py [-h] [--batch_size BATCH_SIZE] [--workers WORKERS] [--epochs EPOCHS] [--learning_rate LEARNING_RATE] [--validation_split VALIDATION_SPLIT] [--momentum MOMENTUM] [--LAMBDA LAMBDA] [--devices DEVICES]

Train a Shade raster prediction model

options:
  -h, --help            show this help message and exit
  --batch_size BATCH_SIZE
                        Batch size for training and validation
  --workers WORKERS     Number of workers for DataLoader
  --epochs EPOCHS       Number of epochs for training
  --learning_rate LEARNING_RATE
                        Initial learning rate
  --validation_split VALIDATION_SPLIT
                        Ratio of training data for validation
  --momentum MOMENTUM   Optimizer momentum
  --LAMBDA LAMBDA       Determines ratio between adversarial and composite loss
  --devices DEVICES     Number of GPUs to use

All options have reasonable defaults based off of literature, but it should be noted that DEVICES should be the number of GPUs available for training, and WORKERS should not exceed the number of available CPUs.

---

Model Evaluation

The file evaluator.py defines a class and various helper functions which can be used in order to evaluate the model. The notebook evaluate_model.ipynb showcases the functionalities:

• Initializing the model based off of saved weights
• Generating new shade predictions
• Visualizing loss curves of the model training
• Generating a model performance metrics CSV that derives RMSE, MAE, SSIM, and runtime metrics.

Case Study

The case study was performed on data generated using a slightly modified version of Slim Shady, the code can be found here.

License

MIT