Data Module

The data module provides functions for loading and processing geospatial data from various sources, with a focus on Overture Maps data.

Functions

Data Loading and Processing Module.

This module provides comprehensive functionality for loading and processing geospatial data from various sources, with specialized support for Overture Maps data. It handles data validation, coordinate reference system management, and geometric processing operations commonly needed for urban network analysis.

Functions:

Name	Description
load_overture_data	Load data from Overture Maps using the CLI tool and optionally save to GeoJSON files.
process_overture_segments	Process segments from Overture Maps to be split by connectors and extract barriers.

load_overture_data

load_overture_data(
    area,
    types=None,
    output_dir=".",
    prefix="",
    save_to_file=True,
    return_data=True,
    release=None,
    connect_timeout=None,
    request_timeout=None,
    use_stac=True,
)

Load data from Overture Maps using the CLI tool and optionally save to GeoJSON files.

This function downloads geospatial data from Overture Maps for a specified area and data types. It can save the data to GeoJSON files and/or return it as GeoDataFrames.

Parameters:

Name	Type	Description	Default
area	list[float] or Polygon	The area of interest. Can be either a bounding box as [min_lon, min_lat, max_lon, max_lat] or a Polygon geometry.	required
types	list[str]	List of Overture data types to download. If None, downloads all available types. Available types: Type Description address Represents a physical place through a series of attributes (street number, etc). bathymetry Derived vectorized bathymetric data products from ETOPO1 and GLOBathy. building The most basic form of a building feature; geometry is the outer footprint. building_part A single part of a building (e.g. 3D part); associated with a parent building. connector Point feature connecting segments in the transportation network. division Represents an official/non-official organization of people (country, city, etc). division_area Captures the shape of the land/maritime area belonging to a division. division_boundary Represents a shared border between two division features. infrastructure Features such as communication towers, lines, piers, and bridges. land Physical representations of land surfaces derived from OSM Coastlines. land_cover Derived from ESA WorldCover high-resolution optical Earth observation data. land_use Classifications of the human use of a section of land (from OSM landuse). place Points of interest: schools, businesses, hospitals, landmarks, etc. segment LineString feature representing paths for travel (road, rail, water). water Physical representations of inland and ocean marine surfaces. For more information, see the Overture Maps documentation.	None
output_dir	str	Directory where GeoJSON files will be saved.	"."
prefix	str	Prefix to add to output filenames.	""
save_to_file	bool	Whether to save downloaded data to GeoJSON files.	True
return_data	bool	Whether to return the data as GeoDataFrames.	True
release	str	Overture Maps release version to use (e.g., '2024-11-13.0'). If None, uses the default release from the CLI tool. Must be a valid release from the overturemaps library's ALL_RELEASES list.	None
connect_timeout	float	Socket connection timeout in seconds. If None, uses the AWS SDK default value (typically 1 second).	None
request_timeout	float	Socket read timeout in seconds (Windows and macOS only). If None, uses the AWS SDK default value (typically 3 seconds). This option is ignored on non-Windows, non-macOS systems.	None
use_stac	bool	Whether to use Overture's STAC-geoparquet catalog to speed up queries. If False, data will be read normally without the STAC optimization.	True

Returns:

Type	Description
dict[str, GeoDataFrame]	Dictionary mapping data type names to their corresponding GeoDataFrames.

Raises:

Type	Description
ValueError	If invalid data types are specified or if an invalid release version is provided.
CalledProcessError	If the Overture Maps CLI command fails.

See Also

process_overture_segments : Process segments from Overture Maps.

Examples:

>>> # Download building and segment data for a bounding box
>>> bbox = [-74.01, 40.70, -73.99, 40.72]  # Manhattan area
>>> data = load_overture_data(bbox, types=['building', 'segment'])
>>> buildings = data['building']
>>> segments = data['segment']

>>> # Download with a specific release version
>>> data = load_overture_data(bbox, types=['building'], release='2024-11-13.0')

>>> # Download with custom timeout settings
>>> data = load_overture_data(
...     bbox,
...     types=['building'],
...     connect_timeout=5.0,
...     request_timeout=10.0
... )

>>> # Download without STAC optimization
>>> data = load_overture_data(bbox, types=['building'], use_stac=False)

process_overture_segments

process_overture_segments(
    segments_gdf, get_barriers=True, connectors_gdf=None, threshold=1.0
)

Process segments from Overture Maps to be split by connectors and extract barriers.

This function processes road segments by splitting them at connector points and optionally generates barrier geometries based on level rules. It also performs endpoint clustering to snap nearby endpoints together.

Parameters:

Name	Type	Description	Default
segments_gdf	GeoDataFrame	GeoDataFrame containing road segments with LineString geometries. Expected to have 'connectors' and 'level_rules' columns.	required
get_barriers	bool	Whether to generate barrier geometries from level rules.	True
connectors_gdf	GeoDataFrame	GeoDataFrame containing connector information. If provided, segments will be split at connector positions.	None
threshold	float	Distance threshold for endpoint clustering in the same units as the CRS.	1.0

Returns:

Type	Description
GeoDataFrame	Processed segments with additional columns: - 'split_from', 'split_to': Split positions if segments were split - 'length': Length of each segment - 'barrier_geometry': Passable geometry if get_barriers=True

See Also

load_overture_data : Load data from Overture Maps.

Examples:

>>> # Process segments with connector splitting
>>> processed = process_overture_segments(
...     segments_gdf,
...     connectors_gdf=connectors_gdf,
...     threshold=1.0
... )
>>> # Access barrier geometries for routing
>>> barriers = processed['barrier_geometry']