adding docs

NHERI-SimCenter · Oct 7, 2019 · 28e81d1 · 28e81d1
1 parent 472b7a5
commit 28e81d1
Show file tree

Hide file tree

Showing 10 changed files with 268 additions and 0 deletions.
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/Logo/Brails.jpg b/docs/Logo/Brails.jpg
diff --git a/docs/Logo/Logo.pptx b/docs/Logo/Logo.pptx
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,123 @@
+# <img src="https://raw.githubusercontent.com/NHERI-SimCenter/BRAILS/master/docs/Logo/Logo.png" alt="logo" height="80"/> Building Recognition using AI at Large-Scale.
+
+<img src="https://raw.githubusercontent.com/NHERI-SimCenter/BRAILS/master/docs/images/pipeline-left.png" alt="BRAILS" height="200"/><img src="https://raw.githubusercontent.com/NHERI-SimCenter/BRAILS/master/docs/images/BIM3D.gif" height="200">
+
+
+## 1. What is BRAILS?
+
+BRAILS is the acronym for Building Recognition using AI at Large-Scale, 
+which is an AI-Based pipeline for city-scale building information modeling (BIM).
+
+## 2. How to use?
+
+
+### a. Data preparation 
+
+<a href="#preparedata">Prepare data</a>
+
+
+### b. Train
+
+#### Roof
+##### training
+```
+cd src/training/roof/2_train
+# train (better to run on a GPU machine)
+sh finetune_inception_v3_on_roof_train.sh
+```
+
+The training takes a long time on laptops. 
+If you don't want to run the training process, we have a CNN trained on TACC and can be downloaded [here](https://berkeley.box.com/shared/static/awyyc22sjwknn9xg3p7wru4v5zwnlkjp.zip).
+Put the downloaded file inside src/training/roof/tmp/roof-traindir/ and unzip it.
+
+##### testing
+
+ Before your run the test *"sh finetune_inception_v3_on_roof_eval.sh"*, make sure you set the following variables correctly in *"finetune_inception_v3_on_roof_eval.sh"*:
+ ```
+ checkpoint_file = the-path-of-your-checkpoint-file
+ TEST_DIR = the-path-of-your-testing-images-dir
+ ```
+ We've prepared some labeld images for you to test. These images can be downloaded [here](https://berkeley.box.com/shared/static/wfwf4ku9561lcytldy1p7vkjoobgv9sz.zip).
+
+Now you can test if the trained CNN works or not:
+ ```
+cd src/training/roof/2_train
+sh finetune_inception_v3_on_roof_eval.sh
+```
+
+
+### c. Predict
+
+#### Roof
+Now we use the CNN to predict roof types based on satellite images.
+
+Firstly we need to download those images by calling Google API (will cost $).
+
+```
+cd src/predicting
+python downloadRoofImages.py
+```
+
+To save $, instead of running the above python, you can just download them 
+[here](https://berkeley.box.com/shared/static/n8l9kusi9eszsnnkefq37fofz22680t2.zip).
+
+
+Now we can make predictions:
+
+```
+cd src/predicting
+sh classifyRoof.sh
+```
+This script will look into the BIM file and call CNN to predict the roof type of a building if the image is downloaded.
+
+If the image is not downloaded, it will assign a null value for the roof type in the new BIM file.
+
+
+### d. Enhance
+
+Use [*SURF*](https://github.com/charlesxwang/SURF) to predict missing building information:
+
+
+#### Year built
+
+<img src="https://raw.githubusercontent.com/NHERI-SimCenter/BRAILS/master/docs/images/yearBuilt-prediction-error.png" width="700">
+
+
+
+#### Number of stories 
+
+<img src="https://raw.githubusercontent.com/NHERI-SimCenter/BRAILS/master/docs/images/stories_Predictions_classification_error.png" width="700">
+
+#### Structure type
+
+<img src="https://raw.githubusercontent.com/NHERI-SimCenter/BRAILS/master/docs/images/structureType_Predictions_classification_error.png" width="700">
+
+#### Occupancy
+
+<img src="https://raw.githubusercontent.com/NHERI-SimCenter/BRAILS/master/docs/images/occupancy_Predictions_classification_error.png" width="700">
+
+
+## 3. Release of BIM data
+SimCenter will post obtained data here.
+### City-scale BIM for Atlantic coastal cities, NJ -> [Download](https://berkeley.box.com/shared/static/5tb6gszbbyj35bgpypk1gsdem0ntt5ca.geojson)
+<img src="https://raw.githubusercontent.com/NHERI-SimCenter/BRAILS/master/docs/images/AtlanticCities.png" width="700">
+<img src="https://raw.githubusercontent.com/NHERI-SimCenter/BRAILS/master/docs/images/BIM-demo.png" width="700">
+
+## 4. Release of trained CNN  
+Trained CNNs in the format of Tensorflow checkpoint will be posted here.
+### Roof type classifier ->[Download](https://berkeley.box.com/shared/static/awyyc22sjwknn9xg3p7wru4v5zwnlkjp.zip)
+
+
+## 5. How to Cite
+You can cite this software as follows:
+
+
+
+
+## 6. Acknowledgement
+This material is based upon work supported by the National Science Foundation under Grant No. 1612843.
+
+## 7. Contact
+Charles Wang, NHERI SimCenter, UC Berkeley, [email protected]
+
+
diff --git a/docs/images/bim-map.png b/docs/images/bim-map.png
diff --git a/docs/images/occlusion.pptx b/docs/images/occlusion.pptx
diff --git a/docs/images/tree.png b/docs/images/tree.png
diff --git a/docs/images/vision-map.png b/docs/images/vision-map.png
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: '',
+      repo: ''
+    }
+  </script>
+  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
+</body>
+</html>
diff --git a/docs/preparedata.md b/docs/preparedata.md
@@ -0,0 +1,124 @@
+<!-- originally from: /Users/simcenter/Files/SimCenter/Wind Storm Surge Workflow/Atlantic City/BIM -->
+
+# Prepare the data
+
+### 0. Get google map api key
+Define google api key in src/keys.py file like this:   
+``` 
+GoogleMapAPIKey = "replace this with your key" 
+```
+
+### 1. Prepare a list of building addresses in csv format
+For example, Atlantic_Cities_Addrs.csv looks like this
+![img](https://raw.githubusercontent.com/NHERI-SimCenter/BRAILS/master/docs/images/addressList.png)
+
+These basic information are scraped from tax websites. 
+
+For some buildings, some information may be missing from the websites, just leave them blank in csv file.
+
+Once [Atlantic_Cities_Addrs.csv](https://berkeley.box.com/shared/static/hi0nzfykbadtczioj4tymrsjjgwahhbw.csv) is prepared, define the path of it in src/confiugre.py like this:
+
+```
+cleanedBIMFileName = dataDir+"/Atlantic_Cities_Addrs.csv"
+```
+<!--
+To get Atlantic_Cities_Addrs.csv, with AtlanticMOD4.csv, run this
+1. python MOD4BIM-Get-Uniq-Addr.py
+2. python prepareRaw.py
+3. python geocoding_addr.py
+-->
+### 2. Prepare a boundary file of the region of interest in geojson format
+
+Define the path in src/configure.py like this:
+```
+RegionBoundaryFileName = dataDir+"/AtlanticCoastalCities_Boundary.geojson"
+```
+For this demo, we have prepared this boundary file for you, download [here](https://berkeley.box.com/shared/static/gfridzvcjo6k533554q9plh0g3v9fpzi.geojson)
+
+### 3. Prepare building footprints in geojson format
+
+Computer generated building footprints database -> [USBuildingFootprints](https://github.com/microsoft/USBuildingFootprints)
+
+We have prepared a cleaned version that just contains Atlantic coastal cities, download [here](https://berkeley.box.com/shared/static/0ueibjzbo1b0mgru4h6n8l2rmww8nx0z.geojson).
+
+Define the path of this footprints file in src/configure.py like this:
+```
+BuildingFootPrintsFileName = dataDir+"/AtlanticCoastalCities_Footprints.geojson"
+```
+
+### 4. Geocode buildings and create a basic BIM file for this region.
+Define the file path to store BIM for all buildings in src/configure.py like this:
+```
+resultBIMFileName = dataDir+"/Atlantic_Cities_BIM.geojson"
+```
+Then run the following command from src/preparedata (This will cost $ because it calls Google API. To avoid this, download the [Atlantic geocoding file](https://berkeley.box.com/shared/static/mb8dya89hslfj1eo8rzns2v6gllq4x68.zip) and unzip it in your data/preparedata dir. The code will first look into this dir for geocoding information, if it was not there, the code will call Google API.)
+
+```
+python geocoding_addr.py
+```
+
+This will create a BIM file Atlantic_Cities_BIM.geojson containing basic building information within the interested region.
+The generated BIM file can be visulized in a GIS software, such as QGIS.
+```
+{
+	"type": "FeatureCollection",
+	"features": [{
+			"type": "Feature",
+			"id": "8460",
+			"properties": {
+				"id": "8460",
+				"lat": 39.371879,
+				"lon": -74.456126,
+				"address": "1970 W RIVERSIDE DR, ATLANTIC CITY,NJ",
+				"stories": 2,
+				"yearBuilt": 2006,
+				"occupancy": "Residential",
+				"structureType": "Frame",
+				"buildingDescription": "2SF",
+				"city": "ATLANTIC CITY CITY"
+			},
+			"geometry": {
+				"type": "Polygon",
+				"coordinates": [
+					[
+						[-74.45606, 39.371837],
+						[-74.455935, 39.371934],
+						[-74.456037, 39.372013],
+						[-74.456162, 39.371916],
+						[-74.45606, 39.371837]
+					]
+				]
+			}
+		},
+		{
+			"type": "Feature",
+			"id": "8461",
+			"properties": {
+				"id": "8461",
+				"lat": 39.3716807,
+				"lon": -74.4513949,
+				"address": "1619 COLUMBIA AVE, ATLANTIC CITY,NJ",
+				"stories": 2,
+				"yearBuilt": 1979,
+				"occupancy": "Residential",
+				"structureType": "Frame",
+				"buildingDescription": "2SF",
+				"city": "ATLANTIC CITY CITY"
+			},
+			"geometry": {
+				"type": "Polygon",
+				"coordinates": [
+					[
+						[-74.451353, 39.371717],
+						[-74.451493, 39.371755],
+						[-74.451526, 39.37168],
+						[-74.451386, 39.371643],
+						[-74.451353, 39.371717]
+					]
+				]
+			}
+		}
+	]
+}
+``` 
+