Merge remote-tracking branch 'upstream/master'

README.md

@@ -1,4 +1,6 @@
-
+[![DOI](https://zenodo.org/badge/184673734.svg)](https://zenodo.org/badge/latestdoi/184673734)
+[![PyPi version](https://badgen.net/pypi/v/BRAILS/)](https://pypi.org/project/BRAILS/)
+[![PyPI download month](https://img.shields.io/pypi/dm/BRAILS.svg)](https://pypi.python.org/pypi/BRAILS/)
 
 ## What is BRAILS?
 
@@ -22,22 +24,34 @@ pip install BRAILS
 
 This example demonstrates how to use the ``InventoryGenerator`` method embedded in BRAILS to generate regional-level inventories. 
 
-The primary input to ``InventoryGenerator`` is location. ``InventoryGenerator`` accepts four different location input: 1) region name, 2) list of region names, 3) bounding box of a region, 4) A GeoJSON file containing building footprints.
+The primary input to ``InventoryGenerator`` is location. ``InventoryGenerator`` accepts four different ``location`` input types: 1) region name, 2) list of region names, 3) a tuple containing the coordinates for two opposite vertices of a bounding box for a region (e.g., ``(vert1lon,vert1lat,vert2lon,vert2lat)``), and a 4) GeoJSON file containing building footprints or location points.
+
+InventoryGenerator automatically detects building locations in a region by downloading footprint data for the ``location`` input. The three footprint data sources, ``fpSource``, included in BRAILS are i) OpenStreetMaps, ii) Microsoft Global Building Footprints dataset, and iii) FEMA USA Structures. The keywords for these sources are ``osm``, ``ms``, and ``usastr``, respectively.
 
-Please note that you will need a Google API Key to run ``InventoryGenerator``.
+``InventoryGenerator`` also allows inventory data to be imported from the National Structure Inventory or another user-specified file to create a baseline building inventory.
+
+Please note that to run the ``generate`` method of ``InventoryGenerator``, you will need a Google API Key.
 
 ```python
 #import InventoryGenerator:
 from brails.InventoryGenerator import InventoryGenerator
 
 # Initialize InventoryGenerator:
 invGenerator = InventoryGenerator(location='Berkeley, CA',
-                                  nbldgs=100, randomSelection=True,
-                                  GoogleAPIKey="")
+                                  fpSource='usastr', 
+                                  baselineInv='nsi',
+                                  lengthUnit='m',
+                                  outputFile='BaselineInvBerkeleyCA.geojson')
+
+# View a list of building attributes that can be obtained using BRAILS:
+invGenerator.enabled_attributes()
 
 # Run InventoryGenerator to generate an inventory for the entered location:
 # To run InventoryGenerator for all enabled attributes set attributes='all':
-invGenerator.generate(attributes=['numstories','roofshape','buildingheight'])
+invGenerator.generate(attributes=['numstories','roofshape','buildingheight'],
+                      GoogleAPIKey='ENTER-YOUR-API-KEY-HERE',
+                      nbldgs=100,
+                      outputFile='BldgInvBerkeleyCA.geojson')
 
 # View generated inventory:
 invGenerator.inventory
@@ -66,12 +80,12 @@ NHERI-SimCenter [email protected]
                   Stella X. Yu and
                   Ertugrul Taciroglu and
                   Kincho H. Law},
-  title        = {BRAILS Release v3.1.0},
-  month        = jan,
+  title        = {BRAILS Release v3.1.1},
+  month        = feb,
   year         = 2024,
   publisher    = {Zenodo},
-  version      = {v3.1.0},
-  doi          = {10.5281/zenodo.10448047},
-  url          = {https://doi.org/10.5281/zenodo.10448047}
+  version      = {v3.1.1},
+  doi          = {10.5281/zenodo.10606032},
+  url          = {https://doi.org/10.5281/zenodo.10606032}
 }
 ```

brails/EnabledAttributes.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2024 The Regents of the University of California
+#
+# This file is part of BRAILS.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# You should have received a copy of the BSD 3-Clause License along with
+# BRAILS. If not, see <http://www.opensource.org/licenses/>.
+#
+# Contributors:
+# Barbaros Cetiner
+#
+# Last updated:
+# 04-19-2024  
+
+def BldgAttributes() -> list:
+    attr = ['buildingheight','chimney','constype','erabuilt','garage',
+            'numstories','occupancy','repaircost','roofcover','roofeaveheight',
+            'roofshape','roofpitch','winarea']
+    return attr
+
+def BRAILStoR2D_BldgAttrMap() -> dict:
+    r2dHeaders = ['BuildingHeight','ChimneyExists','StructureType',
+                  'YearBuilt','GarageExists','NumberOfStories',
+                  'OccupancyClass','ReplacementCost','RoofCoverType',
+                  'RoofEaveHeight','RoofShape','RoofPitch','WindowAreaRatio']
+    brailsAttributes = BldgAttributes()
+    brails2r2dmap = {}
+    for ind,attr in enumerate(brailsAttributes):
+        brails2r2dmap[attr] = r2dHeaders[ind]
+    return brails2r2dmap