fimeval 0.1.57__tar.gz → 0.1.58__tar.gz

{fimeval-0.1.57 → fimeval-0.1.58}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fimeval
-Version: 0.1.57
+Version: 0.1.58
 Summary: A Framework for Automatic Evaluation of Flood Inundation Mapping Predictions Evaluation
 Author: Surface Dynamics Modeling Lab
 Author-email: Supath Dhital <sdhital@crimson.ua.edu>, Dipshika Devi <ddevi@ua.edu>
@@ -720,11 +720,15 @@ fimeval/
 ├── docs/                       # Documentation (contains 'FIMserv' Tool usage sample codes)
 │   └── sampledata/              # Contains the sample data to demonstrate how this frameworks works    
 │   └── fimeval_usage.ipynb            #Sample code usage of the Evaluation framework
+│   └── fimbench_usage.ipynb           #Sample code usage of the FIMbench Query and getting benchmark dataset
 ├── Images/                       # have sample images for documentation       
 ├── src/
-│   └── fimeval/         
+│   └── fimeval/    
+│       ├──BenchFIMQuery/   #Module to interact with the extensive FIMdatabase, hosted in AWS S3
+│       │   └── access_benchfim.py   #Different classes to query right benchmark FIM for any given location and set of filter
+│       │   └── utilis.py   #Support utility      
 │       ├──BuildingFootprint/ # Contains the evaluation of model predicted FIM with microsoft building footprint
-│       │   └── microsoftBF.py 
+│       │   └── arcgis_API.py   #seamless integration of building footprint in evaluation through ArcGIS REST API
 │       │   └── evaluationwithBF.py       
 │       └── ContingencyMap/      # Contains all the metrics calculation and contingency map generation
 │       │   ├── evaluationFIM.py # main evaluation moodule 
@@ -732,14 +736,14 @@ fimeval/
 │       │   └── metrics.py  # metrics calculation module
 │       │   └── plotevaluationmetrics.py  # use to vizualize the different performance metrics
 │       │   └── printcontingency.py  # prints the contingency map to quickly generate the Map layout
-│       │   └── PWBs3.py  # module which helps to get permanent water bodies from s3 bucket
+│       │   └── water_bodies.py  # module which to get permanent water bodies from s3 bucket and ArcGIS REST API
 │       └── utilis.py   #Includes the resampling and reprojection of FIMs
 └── tests/                  # Includes test cases for different functionality
 ```
 The graphical representation of fimeval pipeline can be summarized as follows in **```Figure 1```**. Here, it will show all the steps incorporated within the ```fimeval``` during packaging and all functionality are interconnected to each other, resulting the automation of the framework.
 
 <div align="center">
-  <img width="900" alt="image" src="./Images/flowchart.jpg">
+  <img width="800" alt="image" src="./Images/flowchart.jpg">
 </div>
 Figure 1: Flowchart showing the entire framework pipeline.
 
@@ -781,7 +785,7 @@ main_dir = Path('./path/to/main/dir')
 ```
 
 #### **Permanent Water Bodies (PWB)**
-This framework uses PWB to first to delineate the PWB in the FIM and assign into different class so that the evaluation will be more fair. For the Contiguous United States (CONUS), the PWB is already integrated within the framework however, if user have more accurate PWB or using fimeval for outside US they can initialize and use PWB within fimeval framework. Currently it is using PWB publicly hosted by ESRI: https://hub.arcgis.com/datasets/esri::usa-detailed-water-bodies/about
+This framework uses PWB to first to delineate the PWB in the FIM and assign into different class so that the evaluation will be more fair. For the Contiguous United States (CONUS), the PWB is already integrated within the framework however, if user have more accurate PWB or using fimeval for outside US they can initialize and use PWB within fimeval framework. Currently it is using PWB publicly hosted by ESRI through REST API: https://hub.arcgis.com/datasets/esri::usa-detailed-water-bodies/about
 
 If user have more precise PWB, they can input their own PWB boundary as .shp and .gpkg format and need to assign the shapefile of the PWB and define directory as,
 ```bash
@@ -826,7 +830,7 @@ Table 1: Modules in `fimeval` are in order of execution.
 | `EvaluateFIM` | It runs all the evaluation of FIM between B-FIM and M-FIMs. | `main_dir`: Main directory containing the case study folders, <br> `method_name`: How users wants to evaluate their FIM, <br> `outpur_dir`: Output directory where all the results and the intermidiate files will be saved for further calculation, <br>  *`PWB_dir`*: The permanenet water bodies vectory file directory if user wants to user their own boundary, <br> *`target_crs`*: this fimeval framework needs the floodmaps to be in projected CRS so define the projected CRS in epsg code format, <br> *`target_resolution`*: sometime if the benchmark is very high resolution than candidate FIMs, it needs heavy computational time, so user can define the resolution if there FIMs are in different spatial resolution, else it will use the coarser resolution among all FIMS within that case. |The outputs includes generated files in TIFF, SHP, CSV, and PNG formats, all stored within the output folder. Users can visualize the TIFF files using any geospatial platform. The TIFF files consist of the binary Benchmark-FIM (Benchmark.tif), Model-FIM (Candidate.tif), and Agreement-FIM (Contingency.tif). The shp files contain the boundary of the generated flood extent.|
 | `PlotContingencyMap` | For better understanding, It will print the agreement maps derived in first step. | `main_dir`, `method_name`, `output_dir` : Based on the those arguments, once all the evaluation is done, it will dynamically get the corresponding contingency raster for printing.| This prints the contingency map showing different class of evaluation (TP, FP, no data, PWB etc). The outputs look like- Figure 4 first row.|
 | `PlotEvaluationMetrics` | For quick understanding of the evaluation metrics, to plot bar of evaluation scores. | `main_dir`, `method_name`, `output_dir` : Based on the those arguments, once all the evaluation is done, it will dynamically get the corresponding file for printing based on all those info.| This prints the bar plots which includes different performance metrics calculated by EvaluateFIM module. The outputs look like- Figure 4 second row.|
-| `EvaluationWithBuildingFootprint` | For Building Footprint Analysis, user can specify shapefile of building footprints as .shp or .gpkg format. By default it consider global Microsoft building footprint dataset. Those data are hosted in Google Earth Engine (GEE) so, It pops up to authenticate the GEE account, please allow it and it will download the data based on evaluation boundary and evaluation is done. | `main_dir`, `method_name`, `output_dir`: Those arguments are as it is, same as all other modules. <br> *`building_footprint`*: If user wants to use their own building footprint file then pass the directory here, *`country`*: It is the 3 letter based country ISO code (eg. 'USA', NEP' etc), for the building data automation using GEE based on the evaluation extent, *`shapefile_dir`*: this is the directory of user defined AOI if user is working with their own boundary and automatic Building footprint download and evaluation, *`geeprojectID`*: this is the google earth engine google cloud project ID, which helps to access the GEE data and resources to work with building footprint download and process. | It will calculate the different metrics (e.g. TP, FP, CSI, F1, Accuracy etc) based on hit and miss of building on different M-FIM and B-FIM. Those all metrics will be saved as CSV format in `output_dir` and finally using that info it prints the counts of building foorpint in each FIMs as well as scenario on the evaluation end via bar plot.|
+| `EvaluationWithBuildingFootprint` | For Building Footprint Analysis, user can specify shapefile of building footprints as .shp or .gpkg format. By default it consider global Microsoft building footprint dataset hosted in ArcGIS Online. It is seamlessly integrated within framework through ArcGIS REST API. | `main_dir`, `method_name`, `output_dir`: Those arguments are as it is, same as all other modules. <br> *`building_footprint`*: If user wants to use their own building footprint file then pass the directory here, *`shapefile_dir`*: this is the directory of user defined AOI if user is working with their own boundary and automatic Building footprint download and evaluation,| It will calculate the different metrics (e.g. TP, FP, CSI, F1, Accuracy etc) based on hit and miss of building on different M-FIM and B-FIM. Those all metrics will be saved as CSV format in `output_dir` and finally using that info it prints the counts of building foorpint in each FIMs as well as scenario on the evaluation end via bar plot.|
 
 <p align="center">
   <img src="./Images/methodsresults_combined.jpg" width="750" />
@@ -909,7 +913,9 @@ pip install fimeval
 | ![alt text](https://ciroh.ua.edu/wp-content/uploads/2022/08/CIROHLogo_200x200.png) | Funding for this project was provided by the National Oceanic & Atmospheric Administration (NOAA), awarded to the Cooperative Institute for Research to Operations in Hydrology (CIROH) through the NOAA Cooperative Agreement with The University of Alabama.
 
 ### For More Information
+
 Contact <a href="https://geography.ua.edu/people/sagy-cohen/" target="_blank">Sagy Cohen</a>
  (sagy.cohen@ua.edu)
+ Supath Dhital, (sdhital@crimson.ua.edu)
  Dipsikha Devi, (ddevi@ua.edu)
-Supath Dhital, (sdhital@crimson.ua.edu)
+

{fimeval-0.1.57 → fimeval-0.1.58}/README.md

@@ -30,11 +30,15 @@ fimeval/
 ├── docs/                       # Documentation (contains 'FIMserv' Tool usage sample codes)
 │   └── sampledata/              # Contains the sample data to demonstrate how this frameworks works    
 │   └── fimeval_usage.ipynb            #Sample code usage of the Evaluation framework
+│   └── fimbench_usage.ipynb           #Sample code usage of the FIMbench Query and getting benchmark dataset
 ├── Images/                       # have sample images for documentation       
 ├── src/
-│   └── fimeval/         
+│   └── fimeval/    
+│       ├──BenchFIMQuery/   #Module to interact with the extensive FIMdatabase, hosted in AWS S3
+│       │   └── access_benchfim.py   #Different classes to query right benchmark FIM for any given location and set of filter
+│       │   └── utilis.py   #Support utility      
 │       ├──BuildingFootprint/ # Contains the evaluation of model predicted FIM with microsoft building footprint
-│       │   └── microsoftBF.py 
+│       │   └── arcgis_API.py   #seamless integration of building footprint in evaluation through ArcGIS REST API
 │       │   └── evaluationwithBF.py       
 │       └── ContingencyMap/      # Contains all the metrics calculation and contingency map generation
 │       │   ├── evaluationFIM.py # main evaluation moodule 
@@ -42,14 +46,14 @@ fimeval/
 │       │   └── metrics.py  # metrics calculation module
 │       │   └── plotevaluationmetrics.py  # use to vizualize the different performance metrics
 │       │   └── printcontingency.py  # prints the contingency map to quickly generate the Map layout
-│       │   └── PWBs3.py  # module which helps to get permanent water bodies from s3 bucket
+│       │   └── water_bodies.py  # module which to get permanent water bodies from s3 bucket and ArcGIS REST API
 │       └── utilis.py   #Includes the resampling and reprojection of FIMs
 └── tests/                  # Includes test cases for different functionality
 ```
 The graphical representation of fimeval pipeline can be summarized as follows in **```Figure 1```**. Here, it will show all the steps incorporated within the ```fimeval``` during packaging and all functionality are interconnected to each other, resulting the automation of the framework.
 
 <div align="center">
-  <img width="900" alt="image" src="./Images/flowchart.jpg">
+  <img width="800" alt="image" src="./Images/flowchart.jpg">
 </div>
 Figure 1: Flowchart showing the entire framework pipeline.
 
@@ -91,7 +95,7 @@ main_dir = Path('./path/to/main/dir')
 ```
 
 #### **Permanent Water Bodies (PWB)**
-This framework uses PWB to first to delineate the PWB in the FIM and assign into different class so that the evaluation will be more fair. For the Contiguous United States (CONUS), the PWB is already integrated within the framework however, if user have more accurate PWB or using fimeval for outside US they can initialize and use PWB within fimeval framework. Currently it is using PWB publicly hosted by ESRI: https://hub.arcgis.com/datasets/esri::usa-detailed-water-bodies/about
+This framework uses PWB to first to delineate the PWB in the FIM and assign into different class so that the evaluation will be more fair. For the Contiguous United States (CONUS), the PWB is already integrated within the framework however, if user have more accurate PWB or using fimeval for outside US they can initialize and use PWB within fimeval framework. Currently it is using PWB publicly hosted by ESRI through REST API: https://hub.arcgis.com/datasets/esri::usa-detailed-water-bodies/about
 
 If user have more precise PWB, they can input their own PWB boundary as .shp and .gpkg format and need to assign the shapefile of the PWB and define directory as,
 ```bash
@@ -136,7 +140,7 @@ Table 1: Modules in `fimeval` are in order of execution.
 | `EvaluateFIM` | It runs all the evaluation of FIM between B-FIM and M-FIMs. | `main_dir`: Main directory containing the case study folders, <br> `method_name`: How users wants to evaluate their FIM, <br> `outpur_dir`: Output directory where all the results and the intermidiate files will be saved for further calculation, <br>  *`PWB_dir`*: The permanenet water bodies vectory file directory if user wants to user their own boundary, <br> *`target_crs`*: this fimeval framework needs the floodmaps to be in projected CRS so define the projected CRS in epsg code format, <br> *`target_resolution`*: sometime if the benchmark is very high resolution than candidate FIMs, it needs heavy computational time, so user can define the resolution if there FIMs are in different spatial resolution, else it will use the coarser resolution among all FIMS within that case. |The outputs includes generated files in TIFF, SHP, CSV, and PNG formats, all stored within the output folder. Users can visualize the TIFF files using any geospatial platform. The TIFF files consist of the binary Benchmark-FIM (Benchmark.tif), Model-FIM (Candidate.tif), and Agreement-FIM (Contingency.tif). The shp files contain the boundary of the generated flood extent.|
 | `PlotContingencyMap` | For better understanding, It will print the agreement maps derived in first step. | `main_dir`, `method_name`, `output_dir` : Based on the those arguments, once all the evaluation is done, it will dynamically get the corresponding contingency raster for printing.| This prints the contingency map showing different class of evaluation (TP, FP, no data, PWB etc). The outputs look like- Figure 4 first row.|
 | `PlotEvaluationMetrics` | For quick understanding of the evaluation metrics, to plot bar of evaluation scores. | `main_dir`, `method_name`, `output_dir` : Based on the those arguments, once all the evaluation is done, it will dynamically get the corresponding file for printing based on all those info.| This prints the bar plots which includes different performance metrics calculated by EvaluateFIM module. The outputs look like- Figure 4 second row.|
-| `EvaluationWithBuildingFootprint` | For Building Footprint Analysis, user can specify shapefile of building footprints as .shp or .gpkg format. By default it consider global Microsoft building footprint dataset. Those data are hosted in Google Earth Engine (GEE) so, It pops up to authenticate the GEE account, please allow it and it will download the data based on evaluation boundary and evaluation is done. | `main_dir`, `method_name`, `output_dir`: Those arguments are as it is, same as all other modules. <br> *`building_footprint`*: If user wants to use their own building footprint file then pass the directory here, *`country`*: It is the 3 letter based country ISO code (eg. 'USA', NEP' etc), for the building data automation using GEE based on the evaluation extent, *`shapefile_dir`*: this is the directory of user defined AOI if user is working with their own boundary and automatic Building footprint download and evaluation, *`geeprojectID`*: this is the google earth engine google cloud project ID, which helps to access the GEE data and resources to work with building footprint download and process. | It will calculate the different metrics (e.g. TP, FP, CSI, F1, Accuracy etc) based on hit and miss of building on different M-FIM and B-FIM. Those all metrics will be saved as CSV format in `output_dir` and finally using that info it prints the counts of building foorpint in each FIMs as well as scenario on the evaluation end via bar plot.|
+| `EvaluationWithBuildingFootprint` | For Building Footprint Analysis, user can specify shapefile of building footprints as .shp or .gpkg format. By default it consider global Microsoft building footprint dataset hosted in ArcGIS Online. It is seamlessly integrated within framework through ArcGIS REST API. | `main_dir`, `method_name`, `output_dir`: Those arguments are as it is, same as all other modules. <br> *`building_footprint`*: If user wants to use their own building footprint file then pass the directory here, *`shapefile_dir`*: this is the directory of user defined AOI if user is working with their own boundary and automatic Building footprint download and evaluation,| It will calculate the different metrics (e.g. TP, FP, CSI, F1, Accuracy etc) based on hit and miss of building on different M-FIM and B-FIM. Those all metrics will be saved as CSV format in `output_dir` and finally using that info it prints the counts of building foorpint in each FIMs as well as scenario on the evaluation end via bar plot.|
 
 <p align="center">
   <img src="./Images/methodsresults_combined.jpg" width="750" />
@@ -219,7 +223,9 @@ pip install fimeval
 | ![alt text](https://ciroh.ua.edu/wp-content/uploads/2022/08/CIROHLogo_200x200.png) | Funding for this project was provided by the National Oceanic & Atmospheric Administration (NOAA), awarded to the Cooperative Institute for Research to Operations in Hydrology (CIROH) through the NOAA Cooperative Agreement with The University of Alabama.
 
 ### For More Information
+
 Contact <a href="https://geography.ua.edu/people/sagy-cohen/" target="_blank">Sagy Cohen</a>
  (sagy.cohen@ua.edu)
+ Supath Dhital, (sdhital@crimson.ua.edu)
  Dipsikha Devi, (ddevi@ua.edu)
-Supath Dhital, (sdhital@crimson.ua.edu)
+

{fimeval-0.1.57 → fimeval-0.1.58}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fimeval"
-version = "0.1.57"
+version = "0.1.58"
 description = "A Framework for Automatic Evaluation of Flood Inundation Mapping Predictions Evaluation"
 readme = "README.md"
 requires-python = ">=3.10"

{fimeval-0.1.57 → fimeval-0.1.58}/src/fimeval/BenchFIMQuery/__init__.py

@@ -2,4 +2,4 @@ from .access_benchfim import benchFIMquery
 
 __all__ = [
     "benchFIMquery",
-]
+]

{fimeval-0.1.57 → fimeval-0.1.58}/src/fimeval/BenchFIMQuery/access_benchfim.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 from typing import Optional, Dict, Any, List, Tuple
 from pathlib import Path
 import os
-import json 
+import json
 
 import rasterio
 from rasterio.warp import transform_bounds
@@ -24,13 +24,15 @@ from .utilis import (
     _to_hour_or_none,
     _record_day,
     _record_hour_or_none,
-    _pretty_date_for_print, 
+    _pretty_date_for_print,
+    _ensure_local_gpkg,
 )
 
 # Preferred area CRSs for area calculations
-AREA_CRS_US = "EPSG:5070"   # for CONUS
+AREA_CRS_US = "EPSG:5070"  # for CONUS
 AREA_CRS_GLOBAL = "EPSG:6933"  # WGS 84 / NSIDC EASE-Grid 2.0 Global (equal-area) for rest of world: in future if the data is added into the catalog.
 
+
 # Helper: pretty-print container so that print(response) shows the structured text.
 # If "printable" is empty (e.g., download=True), nothing is printed.
 class PrettyDict(dict):
@@ -40,6 +42,7 @@ class PrettyDict(dict):
             return txt
         # Empty string when we do not want anything printed (e.g., download=True)
         return ""
+
     __repr__ = __str__
 
 
@@ -106,7 +109,8 @@ def _record_bbox_polygon(rec: Dict[str, Any]) -> Polygon:
     minx, miny, maxx, maxy = _get_record_bbox_xy(rec)
     return box(minx, miny, maxx, maxy)
 
-#Return AOI polygon in WGS84 from a raster file --> this will be useful when user have model predicted raster and looking for the benchmrk FIM into the database
+
+# Return AOI polygon in WGS84 from a raster file --> this will be useful when user have model predicted raster and looking for the benchmrk FIM into the database
 def _raster_aoi_polygon_wgs84(path: str) -> Polygon:
     with rasterio.open(path) as ds:
         if ds.crs is None:
@@ -117,24 +121,29 @@ def _raster_aoi_polygon_wgs84(path: str) -> Polygon:
         )
     return box(minx, miny, maxx, maxy)
 
-#Return AOI polygon in WGS84 from a vector file --> this will be useful when user have model predicted vector and looking for the benchmrk FIM into the database
+
+# Return AOI polygon in WGS84 from a vector file --> this will be useful when user have model predicted vector and looking for the benchmrk FIM into the database
 def _vector_aoi_polygon_wgs84(path: str) -> Polygon:
     gdf = gpd.read_file(path)
     if gdf.empty:
         raise ValueError(f"Vector file {path} contains no features.")
     if gdf.crs is None:
-        raise ValueError(f"Vector file {path} has no CRS; cannot derive WGS84 geometry.")
+        raise ValueError(
+            f"Vector file {path} has no CRS; cannot derive WGS84 geometry."
+        )
     gdf = gdf.to_crs("EPSG:4326")
     geom = unary_union(gdf.geometry)
     if geom.is_empty:
         raise ValueError(f"Vector file {path} has empty geometry after union.")
     return geom
 
+
 def _ensure_dir(path: str | Path) -> Path:
     p = Path(path)
     p.mkdir(parents=True, exist_ok=True)
     return p
 
+
 # benchmark FIM filtering by date
 def _filter_by_date_exact(
     records: List[Dict[str, Any]],
@@ -167,7 +176,8 @@ def _filter_by_date_exact(
                 out.append(r)
     return out
 
-#Filter available benchmark FIMs by date range
+
+# Filter available benchmark FIMs by date range
 def _filter_by_date_range(
     records: List[Dict[str, Any]],
     start_date: Optional[str],
@@ -191,6 +201,7 @@ def _filter_by_date_range(
         out.append(r)
     return out
 
+
 # Dynamic area CRS selection and overlap stats
 def _pick_area_crs_for_bounds(bounds: Tuple[float, float, float, float]) -> str:
     """
@@ -219,7 +230,8 @@ def _pick_area_crs_for_bounds(bounds: Tuple[float, float, float, float]) -> str:
         return AREA_CRS_US
     return AREA_CRS_GLOBAL
 
-#Compute the area overlap statistics between user passed AOI/raster and benchmark AOI
+
+# Compute the area overlap statistics between user passed AOI/raster and benchmark AOI
 def _compute_area_overlap_stats(
     aoi_geom: Polygon,
     benchmark_geom: Polygon,
@@ -280,6 +292,7 @@ def _aoi_context_str(
         return ", ".join(parts)
     # fall back to the non-AOI context from utils
     from .utilis import _context_str as _ctx
+
     return _ctx(
         huc8=huc8,
         date_input=date_input,
@@ -288,15 +301,28 @@ def _aoi_context_str(
         end_date=end_date,
     )
 
+def _display_raster_name(rec: Dict[str, Any]) -> str:
+    tif_url = rec.get("tif_url")
+    if isinstance(tif_url, str) and tif_url.strip():
+        # drop querystring if any
+        tif_url = tif_url.split("?", 1)[0]
+        return os.path.basename(tif_url)
+
+    # fallback: last path token of id
+    rid = rec.get("id")
+    if isinstance(rid, str) and rid.strip():
+        return rid.strip().split("/")[-1] + ".tif"
+
+    return "NA"
 
 # Build a single printable block, optionally with overlap appended
-def _format_block_with_overlap(rec: Dict[str, Any],
-                               pct: Optional[float],
-                               km2: Optional[float]) -> str:
-    tier = rec.get("tier") or rec.get("quality") or "Unknown"
+def _format_block_with_overlap(
+    rec: Dict[str, Any], pct: Optional[float], km2: Optional[float]
+) -> str:
+    tier = rec.get("tier") or rec.get("HWM") or rec.get("quality") or "Unknown"
     res = rec.get("resolution_m")
     res_txt = f"{res}m" if res is not None else "NA"
-    fname = rec.get("file_name") or "NA"
+    fname = _display_raster_name(rec)
 
     lines = [f"Data Tier: {tier}"]
 
@@ -307,22 +333,27 @@ def _format_block_with_overlap(rec: Dict[str, Any],
         date_str = _pretty_date_for_print(rec)
         lines.append(f"Benchmark FIM date: {date_str}")
 
-    lines.extend([
-        f"Spatial Resolution: {res_txt}",
-        f"Raster Filename in DB: {fname}",
-    ])
+    lines.extend(
+        [
+            f"Spatial Resolution: {res_txt}",
+            f"Raster Filename in DB: {fname}",
+        ]
+    )
 
     if pct is not None and km2 is not None:
-        lines.append(f"Overlap with respect to benchmark FIM: {pct:.1f}% / {km2:.2f} km²")
+        lines.append(
+            f"Overlap with respect to benchmark FIM: {pct:.1f}% / {km2:.2f} km²"
+        )
 
     return "\n".join(lines)
 
-#For Tier-4- adding synthetic event year while reflecting the outcomes
+
+# For Tier-4- adding synthetic event year while reflecting the outcomes
 def _is_synthetic_tier(rec: Dict[str, Any]) -> bool:
     """Return True when the record is a synthetic (Tier_4) event."""
     tier = str(rec.get("tier") or rec.get("quality") or "").lower()
     return "tier_4" in tier or tier.strip() == "4"
-    
+
 
 def _return_period_text(rec: Dict[str, Any]) -> str:
     """
@@ -344,13 +375,19 @@ def _return_period_text(rec: Dict[str, Any]) -> str:
     except Exception:
         return f"{rp} synthetic flow"
 
-#helpers to read AOI GPKG geometry directly
+
+# helpers to read AOI GPKG geometry directly
 def _storage_options_for_uri(uri: str) -> Optional[Dict[str, Any]]:
     if isinstance(uri, str) and uri.startswith("s3://"):
-        anon = str(os.environ.get("AWS_NO_SIGN_REQUEST", "")).upper() in {"YES", "TRUE", "1"}
+        anon = str(os.environ.get("AWS_NO_SIGN_REQUEST", "")).upper() in {
+            "YES",
+            "TRUE",
+            "1",
+        }
         return {"anon": anon}
     return None
 
+
 def _gpkg_urls_from_record(rec: Dict[str, Any]) -> List[str]:
     urls: List[str] = []
     for key in ("aoi_gpkg", "aoi_gpkg_url", "gpkg_url"):
@@ -382,23 +419,36 @@ def _gpkg_urls_from_record(rec: Dict[str, Any]) -> List[str]:
     return out
 
 def _read_benchmark_aoi_union_geom(rec: Dict[str, Any]) -> Optional[Polygon]:
-    # Read and union AOI geometries referenced by the record (kept permissive)
+    # Read and union AOI geometries referenced by the record
     urls = _gpkg_urls_from_record(rec)
     if not urls:
         return None
+
     geoms: List[Polygon] = []
     for uri in urls:
         try:
             storage_opts = _storage_options_for_uri(uri)
-            gdf = gpd.read_file(uri, storage_options=storage_opts) if storage_opts else gpd.read_file(uri)
+
+            uri_to_read = _ensure_local_gpkg(uri)
+
+            gdf = (
+                gpd.read_file(uri_to_read, storage_options=storage_opts)
+                if storage_opts
+                else gpd.read_file(uri_to_read)
+            )
             if gdf.empty:
                 continue
-            gdf = gdf.to_crs("EPSG:4326") if gdf.crs else gdf.set_crs("EPSG:4326", allow_override=True)
+            gdf = (
+                gdf.to_crs("EPSG:4326")
+                if gdf.crs
+                else gdf.set_crs("EPSG:4326", allow_override=True)
+            )
             u = unary_union(gdf.geometry)
             if not u.is_empty:
                 geoms.append(u)
-        except Exception:
+        except Exception as e:
             continue
+
     if not geoms:
         return None
     uall = unary_union(geoms)
@@ -419,6 +469,7 @@ class benchFIMquery:
       into a local directory
     - or, as a special-case, fetch a specific benchmark by its filename.
     """
+
     def __init__(self, catalog: Optional[Dict[str, Any]] = None) -> None:
         """
         Create a new service.
@@ -510,12 +561,14 @@ class benchFIMquery:
             )
 
         if download and not out_dir:
-            return PrettyDict({
-                "status": "error",
-                "message": "When download=True, you must provide out_dir.",
-                "matches": [],
-                "printable": "",
-            })
+            return PrettyDict(
+                {
+                    "status": "error",
+                    "message": "When download=True, you must provide out_dir.",
+                    "matches": [],
+                    "printable": "",
+                }
+            )
 
         # Direct filename-only workflow (no AOI, no dates)
         if (
@@ -535,9 +588,7 @@ class benchFIMquery:
                 ]
                 if not candidates:
                     candidates = [
-                        r
-                        for r in recs
-                        if str(r.get("file_name", "")).strip() == fname
+                        r for r in recs if str(r.get("file_name", "")).strip() == fname
                     ]
             else:
                 candidates = [
@@ -545,39 +596,41 @@ class benchFIMquery:
                 ]
 
             if not candidates:
-                return PrettyDict({
-                    "status": "not_found",
-                    "message": f"File name {fname!r} not found in catalog.",
-                    "matches": [],
-                    "printable": "",
-                })
+                return PrettyDict(
+                    {
+                        "status": "not_found",
+                        "message": f"File name {fname!r} not found in catalog.",
+                        "matches": [],
+                        "printable": "",
+                    }
+                )
 
             target = candidates[0]
             out_dir_path = _ensure_dir(out_dir)
             dl = download_fim_assets(target, str(out_dir_path))
 
-            return PrettyDict({
-                "status": "ok",
-                "message": f"Downloaded benchmark FIM '{fname}' to '{out_dir_path}'.",
-                "matches": [
-                    {
-                        "record": target,
-                        "bbox_intersects": False,
-                        "intersection_area_pct": None,
-                        "intersection_area_km2": None,
-                        "downloads": dl,
-                    }
-                ],
-                "printable": "",
-            })
+            return PrettyDict(
+                {
+                    "status": "ok",
+                    "message": f"Downloaded benchmark FIM '{fname}' to '{out_dir_path}'.",
+                    "matches": [
+                        {
+                            "record": target,
+                            "bbox_intersects": False,
+                            "intersection_area_pct": None,
+                            "intersection_area_km2": None,
+                            "downloads": dl,
+                        }
+                    ],
+                    "printable": "",
+                }
+            )
 
         # AOI-based workflows
         records = self.records
         if huc8:
             huc8_str = str(huc8).strip()
-            records = [
-                r for r in records if str(r.get("huc8", "")).strip() == huc8_str
-            ]
+            records = [r for r in records if str(r.get("huc8", "")).strip() == huc8_str]
 
         # Date filters
         if event_date:
@@ -586,12 +639,14 @@ class benchFIMquery:
             records = _filter_by_date_range(records, start_date, end_date)
 
         if not records:
-            return PrettyDict({
-                "status": "not_found",
-                "message": "No catalog records match the provided filters.",
-                "matches": [],
-                "printable": "",
-            })
+            return PrettyDict(
+                {
+                    "status": "not_found",
+                    "message": "No catalog records match the provided filters.",
+                    "matches": [],
+                    "printable": "",
+                }
+            )
 
         # If no AOI is provided at all
         if aoi_geom is None:
@@ -615,14 +670,14 @@ class benchFIMquery:
                 end_date=end_date,
                 file_name=file_name,
             )
-            printable = format_records_for_print([m["record"] for m in matches], context=ctx)
+            printable = format_records_for_print(
+                [m["record"] for m in matches], context=ctx
+            )
 
             if download:
                 out_dir_path = _ensure_dir(out_dir)
                 for m in matches:
-                    m["downloads"] = download_fim_assets(
-                        m["record"], str(out_dir_path)
-                    )
+                    m["downloads"] = download_fim_assets(m["record"], str(out_dir_path))
                 msg = (
                     f"Downloaded {len(matches)} benchmark record(s) "
                     f"to '{out_dir_path}'."
@@ -633,12 +688,14 @@ class benchFIMquery:
                     f"for the provided filters."
                 )
 
-            return PrettyDict({
-                "status": "ok",
-                "message": msg,
-                "matches": matches,
-                "printable": "" if download else printable,
-            })
+            return PrettyDict(
+                {
+                    "status": "ok",
+                    "message": msg,
+                    "matches": matches,
+                    "printable": "" if download else printable,
+                }
+            )
 
         # AOI is present: intersect with bbox
         intersecting: List[Dict[str, Any]] = []
@@ -652,12 +709,14 @@ class benchFIMquery:
             intersecting.append(r)
 
         if not intersecting:
-            return PrettyDict({
-                "status": "not_found",
-                "message": "No benchmark FIM bbox intersects the provided AOI.",
-                "matches": [],
-                "printable": "",
-            })
+            return PrettyDict(
+                {
+                    "status": "not_found",
+                    "message": "No benchmark FIM bbox intersects the provided AOI.",
+                    "matches": [],
+                    "printable": "",
+                }
+            )
 
         out_matches: List[Dict[str, Any]] = []
         out_dir_path = _ensure_dir(out_dir) if (download and out_dir) else None
@@ -725,12 +784,14 @@ class benchFIMquery:
                     blocks.append(_format_block_with_overlap(rec, None, None))
             printable = header + "\n\n".join(blocks)
 
-        return PrettyDict({
-            "status": "ok",
-            "message": msg,
-            "matches": out_matches,
-            "printable": printable,
-        })
+        return PrettyDict(
+            {
+                "status": "ok",
+                "message": msg,
+                "matches": out_matches,
+                "printable": printable,
+            }
+        )
 
     def __call__(
         self,
@@ -758,4 +819,6 @@ class benchFIMquery:
             download=download,
             out_dir=out_dir,
         )
-benchFIMquery = benchFIMquery()
+
+
+benchFIMquery = benchFIMquery()