4. Examples

4.1. Example 1: Inventory Generation Using BRAILS

This example shows you how to use the BRAILS InventoryGenerator workflow to obtain the building inventory for an area. At the minimum, InventoryGenerator requires the user to provide location information and a Google API key using location and GoogleAPIKey input parameters. Each time InventoryGenerator is executed, it will use Google APIs to access satellite and street-level imagery of the buildings in the defined area. Given that accessing these images requires using Google credits, it is advised to experiment with InventoryGenerator for a few buildings using the nbldgs input parameter.

The code snippet below runs InventoryGenerator for San Rafael, CA, and obtains the number of floors, roof shape, and building height information for a randomly selected 20 buildings from this area. Once the code is executed, it prints the obtained inventory and saves it in an inventory file titled inventory.csv in the directory the code is executed.

 1from brails.InventoryGenerator import InventoryGenerator
 2
 3# Initialize InventoryGenerator:
 4invGenerator = InventoryGenerator(location='San Rafael, CA',
 5                                  nbldgs=10, randomSelection=True,
 6                                  GoogleAPIKey="PROVIDE_YOUR_KEY")
 7
 8# Run InventoryGenerator to obtain a 10-building inventory from the entered location:
 9# To run InventoryGenerator for all enabled attributes set attributes='all':
10invGenerator.generate(attributes=['numstories','roofshape','buildingheight'])
11
12# View generated inventory:
13invGenerator.inventory

The contents of inventory.csv file will appear as follows. Given randomSelection was set to True, it is expected that the information stored in inventory.csv will be different each time this code is executed.

 1footprint,nstories,buildingheight,roofshape
 2"POLYGON ((-122.5259147 37.9248895, -122.5258144 37.9248847, -122.5258197 37.9248163, -122.5258415 37.9248174, -122.5258465 37.9247523, -122.5259084 37.9247553, -122.5259072 37.9247703, -122.5259239 37.9247711, -122.5259147 37.9248895))",2,53.1,Flat
 3"POLYGON ((-122.5307269 37.9267442, -122.5306426 37.9266658, -122.5305552 37.9267052, -122.5305798 37.9267415, -122.5304688 37.926789, -122.5305144 37.9268474, -122.5307269 37.9267442))",2,52.8,Hip
 4"POLYGON ((-122.5283394 37.927182, -122.5283711 37.9273104, -122.5282511 37.9273288, -122.5282194 37.9272004, -122.5283394 37.927182))",1,33.3,Flat
 5"POLYGON ((-122.5313485 37.9236359, -122.5314032 37.9235355, -122.5313854 37.9235295, -122.5314233 37.9234598, -122.5313427 37.9234325, -122.5313266 37.9234621, -122.5312801 37.9234464, -122.5312325 37.9235337, -122.5312816 37.9235503, -122.5312527 37.9236034, -122.5313485 37.9236359))",1,30.9,Gable
 6"POLYGON ((-122.4995951 37.9230744, -122.4997138 37.9230726, -122.4997147 37.9231069, -122.4997812 37.9231059, -122.4997844 37.9232311, -122.4996727 37.9232328, -122.4996732 37.9232531, -122.4995879 37.9232544, -122.4995842 37.9231057, -122.4995959 37.9231055, -122.4995951 37.9230744))",1,26.2,Gable
 7"POLYGON ((-122.4963758 37.9175472, -122.4963943 37.9175454, -122.4963881 37.9175066, -122.4964082 37.9175046, -122.4964121 37.9175289, -122.4964473 37.9175254, -122.4964431 37.9174995, -122.4964598 37.9174978, -122.4964653 37.9175318, -122.4965734 37.9175209, -122.4965892 37.9176185, -122.4965014 37.9176273, -122.4965027 37.9176355, -122.4963919 37.9176466, -122.4963758 37.9175472))",2,38.5,Flat
 8"POLYGON ((-122.5291925 37.9290674, -122.5290991 37.9290669, -122.5291003 37.9289088, -122.5292526 37.9289095, -122.5292519 37.9290096, -122.5291929 37.9290093, -122.5291925 37.9290674))",2,43.4,Flat
 9"POLYGON ((-122.5067624 37.924188, -122.5069005 37.9242765, -122.5068342 37.9243409, -122.5068209 37.9243324, -122.506798 37.9243546, -122.5068118 37.9243635, -122.5067734 37.9244008, -122.5066786 37.9243401, -122.5067076 37.9243118, -122.5066638 37.9242837, -122.5067624 37.924188))",1,23.9,Hip
10"POLYGON ((-122.5254005 37.9251584, -122.525388 37.9252686, -122.5253828 37.9253305, -122.5253321 37.9253278, -122.5253375 37.9252645, -122.5252778 37.9252614, -122.525287 37.9251524, -122.5254005 37.9251584))",1,31.6,Flat
11"POLYGON ((-122.5217461 37.9312052, -122.5216466 37.9313318, -122.5214937 37.931257, -122.5215329 37.9312072, -122.5215361 37.9312088, -122.521561 37.9311772, -122.5215984 37.9311955, -122.5216339 37.9311503, -122.5217461 37.9312052))",1,22.2,Gable

Warning

  1. To successfully run this example, you need to replace the text on line 6 “PROVIDE_YOUR_KEY” with your Google API key. Instructions on obtaining a Google API key can be found here: https://developers.google.com/maps/documentation/embed/get-api-key. BRAILS uses Maps Static API and Street View Static API to access satellite and street-level imagery, so please make sure to enable these APIs with your Google API key.

  2. Once the code is executed, it will create tmp folder in the directory it is executed. This folder will contain the pretrained BRAILS models (which may take a moment to download the first time you run the example) in “tmp/models” and images accessed from Google APIs in “tmp/images” folder. InventoryGenerator will download satellite images for the roof shapes and place them in “tmp/images/satellite” folder. It will download street-level images for calculating the building heights and number of stories and save them in the “tmp/images/street” folder. The folders for satellite and street-level imagery are required to run Example 2.

  3. For best results with BRAILS classification models, it is essential to retrain a pretrained model with data specific to the region for which inventory information is required. The procedure for retraining existing BRAILS modules is discussed in Example 3.

4.2. Example 2: Calling Individual Modules of BRAILS

This example demonstrates the use of specific modules within BRAILS to predict certain building attributes from a provided set of images. The code below assumes that the folders of images on which the inferences will be performed, i.e., “tmp/images/satellite” and “tmp/images/street”, are located in the directory where this code is executed. If this example is run after Example 1, these images will already be located in the specified directories.

The following code runs BRAILS roof shape and occupancy type prediction modules for satellite and street-level imagery located in “tmp/images/satellite” and “tmp/images/street” folders.

 1from brails.modules import PytorchRoofClassifier, PytorchOccupancyClassifier
 2import glob
 3
 4# Initialize a roof classifier:
 5roofModel = PytorchRoofClassifier()
 6
 7# Use the roof classifier to infer the roof class for each image contained in tmp/images/satellite/ folder:
 8imgs = glob.glob('tmp/images/satellite/*')
 9predictions = roofModel.predictMultipleImages(imgs)
10
11# Initialize an occupancy classifier:
12occupancyModel = PytorchOccupancyClassifier()
13
14# Use the occupancy classifier to infer the occupancy type for the building images located in tmp/images/street/ folder:
15imgs = glob.glob('tmp/images/street/*')
16predictions = occupancyModel.predictMultipleImages(imgs)

Once the code is executed, two CSV files will be created in the tmp folder, Occupancy_preds.csv, and roofType_preds.csv. These files contain the information deduced by each module for the input images. For example, the roofType_preds.csv file for the set of building images obtained after Example 1 results in the following:

 1image,prediction,probability
 2tmp/images/satellite/8.png,flat,0.7034066319465637
 3tmp/images/satellite/14.png,hipped,0.8674657344818115
 4tmp/images/satellite/17.png,flat,0.7297888994216919
 5tmp/images/satellite/19.png,gabled,0.9999415874481201
 6tmp/images/satellite/4.png,gabled,1.0
 7tmp/images/satellite/16.png,flat,1.0
 8tmp/images/satellite/12.png,flat,0.9999819993972778
 9tmp/images/satellite/11.png,hipped,0.9999932050704956
10tmp/images/satellite/10.png,flat,1.0
11tmp/images/satellite/3.png,gabled,0.8481845259666443

Warning

  1. This example assumes the inference images are stored in tmp/images/satellite and tmp/images/street folders. If you ran Example 1 beforehand, these folders should already be populated as expected.

  2. As mentioned in Example 1, for best results, it is essential to retrain a pretrained classification model with data specific to the region for which inventory information is required. The steps to retrain a BRAILS model are illustrated in Example 3.

4.3. Example 3: Retraining Existing Modules of BRAILS

This example shows the steps required to retrain an existing BRAILS module using a user-provided training dataset. The script below illustrates this process for BRAILS roof shape classifier module only, but the same steps are applicable to all other BRAILS modules. In this specific implementation, the roof classifier model is retrained for a learning rate (lr) of 0.001, batch size of 64 (batch_size), and the number of epochs of 5 (epochs). These input parameters are training hyperparameters that may depend on the application. At the minimum, retraining a deep learning module typically requires more epochs than in this example.

 1from brails.modules import PytorchRoofClassifier, PytorchOccupancyClassifier
 2import glob
 3
 4# Initialize a roof classifier:
 5roofModel = PytorchImageClassifier(modelName='transformer_rooftype_v1', imgDir='./roofType/')
 6
 7# Retrain the BRAILS roof classifier model using the training dataset in roofType folder:
 8roofModel.fine_tuning(lr=0.001, batch_size=64, epochs=5)
 9
10# Use the new roof classifier to infer the roof class for each image contained in tmp/images/satellite/ folder:
11imgs = glob.glob('tmp/images/satellite/*')
12predictions = roofModel.predictMultipleImages(imgs)

Warning

  1. This example assumes that the user has the training data stored in a folder name roofType in the directory where this code is executed. If the training data is stored elsewhere, please change the input for imgDir accordingly.

  2. BRAILS, by default, expects the training data folder to contain three subfolders named flat, gabled, and hipped, with the images for each category saved under their respective folder.