Merge pull request #48 from bacetiner/master

Updated example scripts for BRAILS++

brails/filters/filter.py

@@ -1,43 +1,86 @@
-from abc import ABC, abstractmethod
-from brails.types.image_set import ImageSet
+# 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:
+# Frank McKenna
+# Barbaros Cetiner
+#
+# Last updated:
+# 11-06-2024
 
 """
-This module defines abstract filter class
+This module defines abstract filter class.
 
 .. autosummary::
 
     Filter
 """
 
+from abc import ABC, abstractmethod
+from brails.types.image_set import ImageSet
+
+
 class Filter(ABC):
     """
-    Abstract base class representing a class that filters an ImageSet
+    Abstract base class for filtering an ImageSet.
 
-      Methods:
-         __init__(dict): Constructor
-         get_footprints(location): An abstract method to return the footprint given a location
+    Methods:
+        filter(images, dir_path): Filters the ImageSet based on specific
+            criteria.
     """
 
-
     def __init__(self, input_data: dict):
+        """
+        Initialize the Filter with the provided input.
+
+        Args:
+            input_data (dict): Configuration or parameters required for
+                filtering.
+        """
         self.input_data = input_data
-    
+
     @abstractmethod
-    def filter(self, images: ImageSet, dir_path: str) ->ImageSet:
+    def filter(self, images: ImageSet, dir_path: str) -> ImageSet:
         """
-        An abstract class that must be implemented by subclasses.
+        Abstract class that must be implemented by subclasses.
 
         This method will be used by the caller to obtain a filtered ImageSet
+        and save the output in a specified directory.
 
         Args:
-              image_set (ImageSet):
-                   The input ImageSet to be filtered
-              dir_path
-                   The path to output dir where filtered images are to be placed        
+            images (ImageSet): The ImageSet to filter.
+            dir_path (str): Path to the output directory for filtered images.
 
         Returns:
-              ImageSet:
-                    The filtered set of images
-
+            ImageSet: The filtered set of images.
         """
-        pass

examples/footprint/brails_footprint.py

@@ -1,72 +1,97 @@
-# Written: fmk 4/23
-# License: BSD-2
+# 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:
+# Frank McKenna
+# Barbaros Cetiner
+#
+# Last updated:
+# 11-06-2024
 
 """
- Purpose: Testing Importer and get_footprints methods
-"""
-
-import sys
+Example demonstrating BRAILS' automated footprint downloading capabilities.
 
-sys.path.insert(1, "../../")
-
-from brails.utils.utils import Importer
+ Purpose: Testing 1) get_class method of Importer
+                  2) get_footprints method of OSM_FootprintScraper,
+                        MS_FootprintScraper, and USA_FootprintScraper modules
+                  3) get_random_sample of AssetInventory
+"""
 
-# create an Import to get the classes
+from brails import Importer
 
+# create an Importer object to fetch BRAILS++ classes:
 importer = Importer()
 
-#
-# specify the BoundaryRegion
-#
-
+# Specify the BoundaryRegion:
 
-region_data = {"type": "locationName", "data": "Tiburon, CA"}
-region_boundary_class = importer.get_class("RegionBoundary")
+region_data = {'type': 'locationName', 'data': 'Tiburon, CA'}
+region_boundary_class = importer.get_class('RegionBoundary')
 region_boundary_object = region_boundary_class(region_data)
 
-#
-# Get Footprints using OSM
-#
+# Get Footprints using OSM:
+print('Trying OSM_FootprintsScraper...')
 
-print("Trying OSM_FootprintsScraper ...")
-
-osm_class = importer.get_class("OSM_FootprintScraper")
-osm_data = {"length": "ft"}
+osm_class = importer.get_class('OSM_FootprintScraper')
+osm_data = {'length': 'ft'}
 instance1 = osm_class(osm_data)
 osm_inventory = instance1.get_footprints(region_boundary_object)
 
-print("num assets OSM", len(osm_inventory.inventory))
+print('Number of assets in OSM', len(osm_inventory.inventory))
 
-#
-# Get Footprints using Microsofts Database
-#
 
-print("Trying Microsoft Footprint Database ...")
-ms_class = importer.get_class("MS_FootprintScraper")
-ms_data = {"length": "ft"}
-instance3 = ms_class(ms_data)
-ms_inventory = instance3.get_footprints(region_boundary_object)
+# Get Footprints using Microsoft Footprints Database:
+print('Trying Microsoft Footprint Database...')
+ms_class = importer.get_class('MS_FootprintScraper')
+ms_data = {'length': 'ft'}
+instance2 = ms_class(ms_data)
+ms_inventory = instance2.get_footprints(region_boundary_object)
 
-print("num assets Microsoft", len(ms_inventory.inventory))
+print('Number of assets in Microsoft Footprint Database',
+      len(ms_inventory.inventory))
 
 
-#
-# Get Footprints using USA Structures
-#
-
+# Get Footprints using USA Structures data:
+print('Trying USA_FootprintsScraper...')
+usa_class = importer.get_class('USA_FootprintScraper')
+usa_data = {'length': 'ft'}
+instance3 = usa_class(usa_data)
+usa_inventory = instance3.get_footprints(region_boundary_object)
 
-print("Trying USA_FootprintsScraper ...")
-usa_class = importer.get_class("USA_FootprintScraper")
-usa_data = {"length": "ft"}
-instance2 = usa_class(usa_data)
-usa_inventory = instance2.get_footprints(region_boundary_object)
+print('Number of assets in USA Structures', len(usa_inventory.inventory))
 
-print("num assets USA", len(usa_inventory.inventory))
-
-#
-# Test obtaining a smaller subset of random values,
-#    method used as we will not always want to get all the images
-#
 
-small_inventory = usa_inventory.get_random_sample(4, 200)
-print("num assets USA subset", len(small_inventory.inventory))
+# Obtain a smaller subset of random values, as we will not always want to get
+# all the images:
+print('\nGetting a subset of the USA footprints...')
+small_inventory = usa_inventory.get_random_sample(10, 200)
+print('Number of assets in the subset', len(small_inventory.inventory))

examples/image_downloads/brails_download_images.py

@@ -36,7 +36,7 @@
 # Barbaros Cetiner
 #
 # Last updated:
-# 10-24-2024
+# 11-06-2024
 
 """
 Example showcasing BRAILS' image downloading capabilities.
@@ -60,7 +60,9 @@
 if os.path.exists(API_KEY_DIR):
     with open(API_KEY_DIR, 'r', encoding='utf-8') as file:
         api_key = file.readline().strip()  # Read first line & strip whitespace
-
+else:
+    raise FileNotFoundError('API key file not found. Please ensure the file'
+                            f' exists at: {API_KEY_DIR}')
 
 # Create the importer:
 importer = Importer()