brails.scrapers.usgs_data_scrapers.usgs_elevation_scraper module

This module defines classes associated with scraping USGS 3DEP elevation data.

USGSElevationScraper([input_dict])

A class to get elevation data using the USGS Elevation Point Query Service.

class brails.scrapers.usgs_data_scrapers.usgs_elevation_scraper.USGSElevationScraper(input_dict=None)

Bases: AssetDataAugmenter

A class to get elevation data using the USGS Elevation Point Query Service.

This class provides functionality to fetch elevation data for individual coordinates, assets (which may consist of multiple coordinates), and geographic regions. It supports multiple elevation data aggregation modes such as centroid elevation, average, min, max, median, and standard deviation of elevations across asset coordinates. Elevation data is retrieved from the USGS service and can be converted to desired length units.

The class is designed to work efficiently by fetching data in parallel and includes support for sampling random points within polygonal region boundaries for broader elevation analysis.

For a discussion of accuracy please visit: https://www.usgs.gov/faqs/how-accurate-are-elevations-generated-elevation-point-query-service-national-map

Parameters:

• units (dict) – Dictionary specifying units of measurement for length (e.g., ‘ft’, ‘m’), parsed from the input configuration or set to defaults.

• inventory (AssetInventory) – The asset inventory instance containing assets with coordinates and features to be augmented with elevation data.

static fetch_all_elevations(coords)

Fetch elevations in parallel for a list of (x, y) coordinate pairs.

Fetch elevation data in parallel for a list of (x, y) coordinate pairs using the USGS Elevation service.

Parameters:

coords (Iterable[Tuple[float, float]]) – An iterable of (x, y) coordinate pairs.

Returns:

A list of result dictionaries, each containing elevation data.

Return type:

List[Dict[str, Any]]

Example

>>> from brails import Importer
>>> importer = Importer()
>>>
>>> coords = [
>>>     (-94.7977, 29.3013),
>>>     (-118.2437, 34.0522),
>>>     (-71.0589, 42.3601)
>>> ]
>>> scraper = importer.get_class('USGSElevationScraper')
>>> results = scraper.fetch_all_elevations(coords)
Downloading USGS elevation data: 100%|██████████| 3/3
[00:00<00:00,  4.11it/s]
>>> for r in results:
>>>     print(r)
{'x': -94.7977, 'y': 29.3013, 'elevation': 5.5912666815452}
{'x': -118.2437, 'y': 34.0522, 'elevation': 284.5500426357848}
{'x': -71.0589, 'y': 42.3601, 'elevation': 33.22253183411836}

static get_elevation_usgs(x, y)

Get elevation data for a coordinate using USGS Elevation Point Service.

This method sends a request to the USGS service using the provided geographic coordinates and returns a dictionary containing the longitude, latitude, and elevation (in feet). If the request fails or the elevation value is unavailable, the elevation is returned as None.

Parameters:

• x (float) – Longitude in decimal degrees (WGS84).

• y (float) – Latitude in decimal degrees (WGS84).

Returns:

Dictionary with keys:

• 'x' (float): Longitude

• 'y' (float): Latitude

• 'elevation' (float or None): Elevation in feet

Return type:

dict

Example

>>> from brails import Importer
>>> importer = Importer()
>>> scraper = importer.get_class('USGSElevationScraper')
>>> result = scraper.get_elevation_usgs(-94.7977, 29.3013)
>>> print(result)
{'x': -94.7977, 'y': 29.3013, 'elevation': 5.5912666815452}

get_region_elevation_data(region, num_points=2000, seed=None)

Sample elevation data within a region boundary.

Parameters:

• region – RegionBoundary object with a get_boundary() method.

• num_points (int) – Total number of points to sample within the region boundary. Defaults to 2000

• seed (int, optional) – Random seed for reproducibility. Default is None.

Returns:

An inventory of sampled points with elevation values stored in each asset’s features.

Return type:

AssetInventory

Example

This example demonstrates how to get elevation maps using the USGSElevationScraper in BRAILS++ and save them in GeoJSON format.

>>> from brails import Importer
>>>
>>> importer = Importer()
>>> region_data = {
>>>     'type': 'locationName',
>>>     'data': 'Fort Myers Beach, FL'
>>> }
>>> region_boundary_class = importer.get_class('RegionBoundary')
>>> region_boundary_object = region_boundary_class(region_data)
>>>
>>> scraper = importer.get_class('USGSElevationScraper')()
No length unit specified. Using default: 'ft'.
No weight unit specified. Using default: 'lb'.
>>> elevation_data = scraper.get_region_elevation_data(
>>>     region=region_boundary_object,
>>>     num_points=5000
>>> )
Searching for Fort Myers Beach, FL...
Found Fort Myers Beach, Lee County, Florida, 33931, United States
Downloading USGS elevation data: 100%|██████████| 5000/5000
[00:44<00:00, 45.42it/s]
>>> _ = elevation_data.write_to_geojson(
>>>         'FtMyersElevationMap.geojson'
>>> )
Wrote 5000 assets to /home/bacetiner/FtMyersElevationMap.geojson

populate_feature(input_inventory)

Compute elevation features for assets in the provided AssetInventory.

Based on the specified modes, this method fetches elevation data either at the centroid of each asset or for all coordinates, then computes summary statistics (e.g., average, min, max, median, stddev).

All elevation values are converted from feet to the target length unit before being stored under the features dictionary of each asset.

Parameters:

asset_inventory (AssetInventory) – The inventory of assets to process for elevation data.

Returns:

The modified inventory with added elevation features.

Return type:

AssetInventory

Example

Import the Importer class:

>>> from brails import Importer
>>>
>>> importer = Importer()

The following code block, will create a building inventory using the OvertureMapsScraper. Our sample inventory contains two buildings randomly sampled from Galveston, TX.

>>> region_data = {"type": "locationName", "data": 'Galveston, TX'}
>>> region_boundary_class = importer.get_class('RegionBoundary')
>>> region_boundary_object = region_boundary_class(region_data)
>>> overture_maps_scraper = importer.get_class(
>>>     'OvertureMapsFootprintScraper'
>>> )()
No length unit specified. Using default: 'ft'.
No weight unit specified. Using default: 'lb'.
'overtureRelease' not defined in input. Falling back to latest
release: 2025-08-20.1
>>> inventory = overture_maps_scraper.get_footprints(
...     region_boundary_object
... )
Searching for Galveston, TX...
Found Galveston County, Texas, United States
Reading dataset batches: 352it [00:40,  8.69it/s]
Reading dataset batches: 22it [00:03,  7.20it/s]
Finding the assets within the specified area...
Found a total of 163881 assets within the specified area.
>>> subsampled_inventory = inventory.get_random_sample(2)
>>> subsampled_inventory.print_info()
Inventory stored in:  dict
Key:  20049 Asset:
            Coordinates:  [[-95.1681703, 29.4071135],
[-95.168116, 29.4071755], [-95.1681829, 29.40722],
[-95.1682373, 29.4071579], [-95.1681703, 29.4071135]]
            Features:  {'version': 3, 'sources':
'dataset: Microsoft ML Buildings,
update_time: 2022-03-25T00:00:00.000Z',
'has_parts': False, 'is_underground': False,
'overture_id': 'b590fbec-f369-4097-8288-75d8d6da9513',
'type': 'building'}
Key:  68756 Asset:
    Coordinates:  [[-94.9926423, 29.3883931],
[-94.9928071, 29.3883895], [-94.992804, 29.3882821],
[-94.9926392, 29.3882857], [-94.9926423, 29.3883931]]
    Features:  {'version': 3, 'sources':
'dataset: Microsoft ML Buildings, update_time:
2022-03-25T00:00:00.000Z', 'height': 10.57, 'has_parts': False,
'is_underground': False, 'overture_id':
'd095e4b8-0bbb-4184-b7f7-c4e855863085', 'type': 'building'}

Populate elevation features:

>>> usgs_elev_scraper = importer.get_class('USGSElevationScraper')(
>>>     {'length': 'm', 'modes': ['centroid', 'min', 'max']}
>>> )
No weight unit specified. Using default: 'lb'.
>>> updated_inventory = usgs_elev_scraper.populate_feature(
>>>     subsampled_inventory
>>> )
Downloading USGS elevation data: 100%|██████████| 10/10
[00:00<00:00, 14.57it/s]

Access the computed elevation features:

>>> subsampled_inventory.print_info()
Inventory stored in:  dict
Key:  20049 Asset:
            Coordinates:  [[-95.1681703, 29.4071135],
[-95.168116, 29.4071755], [-95.1681829, 29.40722],
[-95.1682373, 29.4071579], [-95.1681703, 29.4071135]]
            Features:  {'version': 3, 'sources':
'dataset: Microsoft ML Buildings,
update_time: 2022-03-25T00:00:00.000Z',
'has_parts': False, 'is_underground': False,
'overture_id': 'b590fbec-f369-4097-8288-75d8d6da9513',
'type': 'building', 'centroid_elevation': 8.66,
'min_elevation': 8.56, 'max_elevation': 8.68}}
Key:  68756 Asset:
    Coordinates:  [[-94.9926423, 29.3883931],
[-94.9928071, 29.3883895], [-94.992804, 29.3882821],
[-94.9926392, 29.3882857], [-94.9926423, 29.3883931]]
    Features:  {'version': 3, 'sources':
'dataset: Microsoft ML Buildings, update_time:
2022-03-25T00:00:00.000Z', 'height': 10.57, 'has_parts': False,
'is_underground': False, 'overture_id':
'd095e4b8-0bbb-4184-b7f7-c4e855863085', 'type': 'building',
'centroid_elevation': 5.22, 'min_elevation': 5.08,
'max_elevation': 5.39}}

static supported_asset_elevation_modes(print_modes=True)

Return the set of supported elevation modes.

Parameters:

print_modes (bool, optional) – If True, prints the supported modes. Defaults to True.

Returns:

A set containing the supported elevation mode keys.

Return type:

Set[str]

Example

Import the USGSElevationScraper class:

>>> from brails import Importer
>>>
>>> importer = Importer()
>>> scraper = importer.get_class('USGSElevationScraper')()
No length unit specified. Using default: 'ft'.
No weight unit specified. Using default: 'lb'.

Call the supported_asset_elevation_modes method to print and save the supported elevation modes in a set named modes:

>>> modes = scraper.supported_asset_elevation_modes()
Supported modes: all, average, centroid, max, median, min, stddev
>>> print(modes)
{'stddev', 'centroid', 'max', 'min', 'median', 'average', 'all'}

Call the method without printing the supported modes:

>>> modes_only = scraper.supported_asset_elevation_modes(
>>>     print_modes=False
>>> )
>>> print(modes_only)
{'stddev', 'centroid', 'max', 'min', 'median', 'average', 'all'}