voxcity.downloader.osm ====================== .. py:module:: voxcity.downloader.osm .. autoapi-nested-parse:: Module for downloading and processing OpenStreetMap data. This module provides functionality to download and process building footprints, land cover, and other geographic features from OpenStreetMap. It handles downloading data via the Overpass API, processing the responses, and converting them to standardized GeoJSON format with proper properties. The module includes functions for: - Converting OSM JSON to GeoJSON format - Processing building footprints with height information - Handling land cover classifications - Managing coordinate systems and projections - Processing roads and other geographic features Attributes ---------- .. autoapisummary:: voxcity.downloader.osm.OVERPASS_ENDPOINTS voxcity.downloader.osm.classification_mapping voxcity.downloader.osm.tag_osm_key_value_mapping Functions --------- .. autoapisummary:: voxcity.downloader.osm.load_gdf_from_openstreetmap voxcity.downloader.osm.load_land_cover_gdf_from_osm voxcity.downloader.osm.load_tree_gdf_from_osm Module Contents --------------- .. py:data:: OVERPASS_ENDPOINTS :value: ['https://overpass-api.de/api/interpreter', 'https://overpass.kumi.systems/api/interpreter',... .. py:function:: load_gdf_from_openstreetmap(rectangle_vertices, floor_height=3.0) Download and process building footprint data from OpenStreetMap. This function: 1. Downloads building data using the Overpass API 2. Processes complex relations and their members 3. Extracts height information and other properties 4. Converts features to a GeoDataFrame with standardized properties :param rectangle_vertices: List of (lon, lat) coordinates defining the bounding box :type rectangle_vertices: list :returns: GeoDataFrame containing building footprints with properties: - geometry: Polygon or MultiPolygon - height: Building height in meters - levels: Number of building levels - min_height: Minimum height (for elevated structures) - building_type: Type of building - And other OSM tags as properties :rtype: geopandas.GeoDataFrame .. py:data:: classification_mapping .. py:data:: tag_osm_key_value_mapping .. py:function:: load_land_cover_gdf_from_osm(rectangle_vertices_ori) Load and classify land cover data from OpenStreetMap. This function: 1. Downloads land cover features using the Overpass API 2. Classifies features based on OSM tags 3. Handles special cases like roads with width information 4. Projects geometries for accurate buffering 5. Creates a standardized GeoDataFrame with classifications :param rectangle_vertices_ori: List of (lon, lat) coordinates defining the area :type rectangle_vertices_ori: list :returns: GeoDataFrame with: - geometry: Polygon or MultiPolygon features - class: Land cover classification name - Additional properties from OSM tags :rtype: geopandas.GeoDataFrame .. py:function:: load_tree_gdf_from_osm(rectangle_vertices, default_top_height=10.0, default_trunk_height=4.0, default_crown_diameter=None, default_crown_ratio=0.6, include_polygons=True) Download and process individual tree data and tree land cover polygons from OpenStreetMap. This function downloads tree point data (natural=tree) and optionally tree land cover polygons (natural=wood, landuse=forest, natural=tree_row) from OpenStreetMap and creates a GeoDataFrame compatible with VoxCity's tree canopy processing. For individual trees, it extracts height and crown diameter information from OSM tags when available, or uses default values when not specified. For tree polygons (forests, woods), it assigns default height values and the polygon geometry is preserved for rasterization during canopy grid creation. OSM tags used for tree properties: - height, est_height: Tree height in meters - diameter_crown: Crown diameter in meters - circumference: Trunk circumference (used to estimate crown if diameter_crown missing) - genus, species: Tree species information (stored as properties) - leaf_type: broadleaved/needleleaved (stored as property) - leaf_cycle: deciduous/evergreen (stored as property) Crown diameter estimation priority (for point trees only): 1. Use diameter_crown tag if available 2. Estimate from circumference tag (trunk circumference × 15 / π) 3. Use default_crown_diameter if specified 4. Estimate from tree height (height × default_crown_ratio) :param rectangle_vertices: List of (lon, lat) coordinates defining the bounding box. Should be 4 vertices forming a rectangle. :type rectangle_vertices: list :param default_top_height: Default tree top height in meters when not specified in OSM. Defaults to 10.0 meters. :type default_top_height: float :param default_trunk_height: Default trunk height (height to bottom of canopy) in meters. This is the height where the canopy starts. Defaults to 4.0 meters. :type default_trunk_height: float :param default_crown_diameter: Default crown diameter in meters. If None, crown diameter is estimated from tree height using default_crown_ratio. Only used for Point geometries. :type default_crown_diameter: float, optional :param default_crown_ratio: Ratio of crown diameter to tree height, used when crown diameter cannot be determined from OSM tags and default_crown_diameter is None. Defaults to 0.6 (e.g., a 10m tall tree would have a 6m crown diameter). :type default_crown_ratio: float :param include_polygons: If True, also download tree land cover polygons (forests, woods, tree_rows). Defaults to True. Set to False to only get individual trees. :type include_polygons: bool :returns: GeoDataFrame containing tree features with columns: - geometry: Point or Polygon geometry (lon, lat) - geometry_type: 'point' for individual trees, 'polygon' for forest/wood areas - tree_id: Unique identifier for each feature - top_height: Height to the top of the tree canopy in meters - bottom_height: Height to the bottom of the canopy (trunk height) in meters - crown_diameter: Diameter of the tree crown in meters (0 for polygons) - genus: Tree genus if available - species: Tree species if available - leaf_type: Leaf type (broadleaved/needleleaved) if available - leaf_cycle: Leaf cycle (deciduous/evergreen) if available - osm_id: Original OSM element ID - osm_type: OSM element type ('node', 'way', 'relation') :rtype: geopandas.GeoDataFrame .. rubric:: Example >>> vertices = [(-73.99, 40.75), (-73.98, 40.75), (-73.98, 40.76), (-73.99, 40.76)] >>> # Get both individual trees and forest polygons >>> tree_gdf = load_tree_gdf_from_osm(vertices) >>> # Get only individual trees >>> tree_gdf = load_tree_gdf_from_osm(vertices, include_polygons=False) >>> # Customize defaults: 15m tall trees, 5m trunk >>> tree_gdf = load_tree_gdf_from_osm(vertices, default_top_height=15.0, ... default_trunk_height=5.0) .. note:: - Individual trees have Point geometry with crown_diameter for ellipsoid rendering - Tree polygons have Polygon geometry and are rasterized as flat canopy areas - Tree polygon types: natural=wood, landuse=forest, natural=tree_row - Crown diameter estimation from trunk circumference uses an empirical ratio - The function uses multiple Overpass API endpoints for reliability