{"id":20960000,"url":"https://github.com/njroussel/roadsegmentation","last_synced_at":"2025-06-25T09:38:48.759Z","repository":{"id":73248046,"uuid":"74598088","full_name":"njroussel/RoadSegmentation","owner":"njroussel","description":"Segmenting satellite images of earth : determining which parts are roads.","archived":false,"fork":false,"pushed_at":"2017-03-26T20:04:54.000Z","size":50572,"stargazers_count":11,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-14T07:34:22.302Z","etag":null,"topics":["computer-vision","convolutional-neural-networks","jupyter-notebook","python","road-segmentation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/njroussel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-11-23T17:11:36.000Z","updated_at":"2024-03-22T22:03:22.000Z","dependencies_parsed_at":"2023-04-26T12:00:31.289Z","dependency_job_id":null,"html_url":"https://github.com/njroussel/RoadSegmentation","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/njroussel/RoadSegmentation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njroussel%2FRoadSegmentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njroussel%2FRoadSegmentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njroussel%2FRoadSegmentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njroussel%2FRoadSegmentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/njroussel","download_url":"https://codeload.github.com/njroussel/RoadSegmentation/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njroussel%2FRoadSegmentation/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261845994,"owners_count":23218684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-vision","convolutional-neural-networks","jupyter-notebook","python","road-segmentation"],"created_at":"2024-11-19T01:57:04.452Z","updated_at":"2025-06-25T09:38:48.746Z","avatar_url":"https://github.com/njroussel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Road Segmentation  \n\nCollaborators:\n* [JBouron](https://github.com/jbouron)\n* [Rimbaud13](https://github.com/rimbaud13)    \n* [Trofleb](https://github.com/trofleb)\n\n### Table of Contents :\n  * [Introduction](#introduction)\n  * [Results](#results)\n  * [Setup](#setup)\n    * [Python](#pyton)\n    * [Environment](#environment)\n  * [Code overview](#code-overview)\n  * [Configuration](#configuration)\n  * [Running](#running)\n\n\n### Introduction\n  This project is part of the [EPFL](www.epfl.ch) \"Pattern classification and machine\nlearning\" class. More specifically, it is our solution for the second project\non road segmentation.\n  This file gives an overview of our code and how it functions. All\nadditional explanations about the project itself can be found in the official\npaper for it (the `paper.pdf` file).\n\n  The goal of the project is to segment a satellite image of earth by determing\n  which patches of 16x16 pixels are roads or not.\n\n  In short, the code runs a first convolutional neural network to get basic predictions. After this it runs a second one, a postprocessing one, which uses the previously computed predictions to give a final prediction.\n\n### Results\nWe achieved about a 0.91 F1-score, below you will find an image illustrating\nthe qualitative result achieved. Every detected road patch is covered in red on\nthe image.\n  \n![Final result](result.jpg)\n\n\n### Setup\n  The machine learning part of the code runs entirely on python. These\nare our recommendations for the package versions and environment.\n\n#### Python\n  These are the python and its packages versions used to produce our\nresults. Python should be available at https://www.python.org/ and it's packages\ncan be found with 'pip' https://docs.python.org/3.5/installing/.\n```\npython: version 3.5\nmatplotlib : version 1.5.3\nnumpy : version 1.11.2\nscipy : version 0.18.1\nPillow : version 3.3.1\ntensorflow : version 0.12.0\nprogressbar2 : version 3.11.0\n```\n\n#### Environment\n  These are general recommendations for the environment in which the code\nruns:\n  1. If possible use a CUDA enabled GPU. Tensorflow supports CUDA enabled\nGPUs, which accelerates widely the computation needed by this project. More\ndocumentation can be found\n[here](https://www.tensorflow.org/get_started/os_setup).\n  2. Use a minimalist linux distribution and avoid performing other tasks\nwhile the code is running. A typical run of our code is computationally\nintensive, keeping the amount of resources available to our code as high as\npossible will reduce its running time. We highly recommend\n[Arch Linux](https://www.archlinux.org/).\n  3. [Here](https://inclass.kaggle.com/c/epfml-segmentation) are the datasets.\nThe training set should be at the root of the project in a folder named\n`training/` and the test set should be flattened into a folder named\n`test_set_images/`.\n  4. Do not delete the empty folders in the project, they are needed for outputs. Depending on the environment, our code is not allowed to create the folder by itself, hence our warning about the empty folders.\n\n\n### Code overview\nThe `run.py` file is the main file which runs our code from with the parameters found `global_vars.py` and `global_vars_pp.py`. The `learner.py` file contains the main Tensorflow code - it setups the model and runs the validation. `logger.py`, `prediction_helpers`, `image_helpers`, `mask_to_submission.py` and `tf_helpers.py` are files which contain helper methods to modularize our code.\n\n### Configuration\n  In the `global_vars.py` file are all the parameters which will be used for the\nfirst neural network. The `global_vars_pp.py` file contains the parameters for\nthe postprocessing neural network. Documentation about each parameter can be\nfound in the individual files.\n\nThe default parameters will load a pretrained model which was built from the other default parameters we provide.\n\n### Running\n16 GB of RAM + swap space is needed at least in order to run our optimal result (even when loading the model from the files).\n\n  Running the code is straight forward - simply use:\n```\npython3.5 run.py\n```\nin your favorite terminal emulator at the root of the project folder. If you did not change `global_vars.py` and `global_vars_pp.py` files, it will load our best model and compute the predictions with them (this should take about 10 mins). However if you decide to relearn the model by yourself, the runtime can take over two hours for our optimal parameters.\n  The run produces the following folders and files :\n\n* `test_predictions` : Contains the predictions on the images in the `test_set_images` folder after the first neural network.\n\n* `test_predictions_pp` : Contains the predictions on the images in the `test_set_images` folder after the postprocessing neural network.\n\nThe predictions for kaggle can then be created by running\n```\npython3.5 mask_to_submission.py\nor\npython3.5 mask_to_submission.py test_predictions_pp/\n```\nThe first command will create a `dummy_submisison.csv` file which is computed from the results in `test_predictions` (without postprocessing). Whereas, the second created the same file but this time from the `test_predictions_pp` results (with postprocessing).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjroussel%2Froadsegmentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnjroussel%2Froadsegmentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjroussel%2Froadsegmentation/lists"}