voxcity 0.4.6__py3-none-any.whl → 0.5.0__py3-none-any.whl

voxcity/downloader/citygml.py

@@ -0,0 +1,556 @@
+import requests
+import zipfile
+import io
+import os
+import numpy as np
+from urllib.parse import urlparse
+from pathlib import Path
+import lxml.etree as ET
+import geopandas as gpd
+from shapely.geometry import Polygon, Point, MultiPolygon
+import pandas as pd
+from tqdm import tqdm
+
+def download_and_extract_zip(url, extract_to='.'):
+    """
+    Download and extract a zip file from a URL
+    """
+    # Send a GET request to the URL
+    response = requests.get(url)
+
+    # Check if the request was successful
+    if response.status_code == 200:
+        # Extract the base name of the zip file from the URL
+        parsed_url = urlparse(url)
+        zip_filename = os.path.basename(parsed_url.path)
+        folder_name = os.path.splitext(zip_filename)[0]  # Remove the .zip extension
+
+        # Create the extraction directory
+        extraction_path = os.path.join(extract_to, folder_name)
+        os.makedirs(extraction_path, exist_ok=True)
+
+        # Create a BytesIO object from the response content
+        zip_file = io.BytesIO(response.content)
+
+        # Open the zip file
+        with zipfile.ZipFile(zip_file) as z:
+            # Extract all the contents of the zip file to the specified directory
+            z.extractall(extraction_path)
+            print(f"Extracted to {extraction_path}")
+    else:
+        print(f"Failed to download the file. Status code: {response.status_code}")
+
+    return extraction_path, folder_name
+
+
+def validate_coords(coords):
+    """
+    Validate that coordinates are not infinite or NaN
+    """
+    return all(not np.isinf(x) and not np.isnan(x) for coord in coords for x in coord)
+
+
+def swap_coordinates(polygon):
+    """
+    Swap coordinates in a polygon (lat/lon to lon/lat or vice versa)
+    """
+    if isinstance(polygon, MultiPolygon):
+        # Handle MultiPolygon objects
+        new_polygons = []
+        for geom in polygon.geoms:
+            coords = list(geom.exterior.coords)
+            swapped_coords = [(y, x) for x, y in coords]
+            new_polygons.append(Polygon(swapped_coords))
+        return MultiPolygon(new_polygons)
+    else:
+        # Handle regular Polygon objects
+        coords = list(polygon.exterior.coords)
+        swapped_coords = [(y, x) for x, y in coords]
+        return Polygon(swapped_coords)
+
+
+def extract_terrain_info(file_path, namespaces):
+    """
+    Extract terrain elevation information from a CityGML file
+    """
+    try:
+        tree = ET.parse(file_path)
+        root = tree.getroot()
+
+        terrain_elements = []
+
+        # Look for Relief features in the CityGML file
+        for relief in root.findall('.//dem:ReliefFeature', namespaces):
+            relief_id = relief.get('{http://www.opengis.net/gml}id')
+
+            # Extract TIN Relief components
+            for tin in relief.findall('.//dem:TINRelief', namespaces):
+                tin_id = tin.get('{http://www.opengis.net/gml}id')
+
+                # Extract triangulated surface
+                triangles = tin.findall('.//gml:Triangle', namespaces)
+                for i, triangle in enumerate(triangles):
+                    # Extract the coordinates of each triangle
+                    pos_lists = triangle.findall('.//gml:posList', namespaces)
+
+                    for pos_list in pos_lists:
+                        try:
+                            # Process the coordinates
+                            coords_text = pos_list.text.strip().split()
+                            coords = []
+                            elevations = []
+
+                            # Process coordinates in triplets (x, y, z)
+                            for j in range(0, len(coords_text), 3):
+                                if j + 2 < len(coords_text):
+                                    x = float(coords_text[j])
+                                    y = float(coords_text[j + 1])
+                                    z = float(coords_text[j + 2])  # Elevation
+
+                                    if not np.isinf(x) and not np.isinf(y) and not np.isinf(z):
+                                        coords.append((x, y))
+                                        elevations.append(z)
+
+                            if len(coords) >= 3 and validate_coords(coords):
+                                polygon = Polygon(coords)
+                                if polygon.is_valid:
+                                    # Calculate centroid for point representation
+                                    centroid = polygon.centroid
+                                    avg_elevation = np.mean(elevations)
+
+                                    terrain_elements.append({
+                                        'relief_id': relief_id,
+                                        'tin_id': tin_id,
+                                        'triangle_id': f"{tin_id}_tri_{i}",
+                                        'elevation': avg_elevation,
+                                        'geometry': centroid,
+                                        'polygon': polygon,
+                                        'source_file': Path(file_path).name
+                                    })
+                        except (ValueError, IndexError) as e:
+                            print(f"Error processing triangle in relief {relief_id}: {e}")
+                            continue
+
+            # Extract breaklines
+            for breakline in relief.findall('.//dem:breaklines', namespaces):
+                for line in breakline.findall('.//gml:LineString', namespaces):
+                    line_id = line.get('{http://www.opengis.net/gml}id')
+                    pos_list = line.find('.//gml:posList', namespaces)
+
+                    if pos_list is not None:
+                        try:
+                            coords_text = pos_list.text.strip().split()
+                            points = []
+                            elevations = []
+
+                            for j in range(0, len(coords_text), 3):
+                                if j + 2 < len(coords_text):
+                                    x = float(coords_text[j])
+                                    y = float(coords_text[j + 1])
+                                    z = float(coords_text[j + 2])
+
+                                    if not np.isinf(x) and not np.isinf(y) and not np.isinf(z):
+                                        points.append(Point(x, y))
+                                        elevations.append(z)
+
+                            for k, point in enumerate(points):
+                                if point.is_valid:
+                                    terrain_elements.append({
+                                        'relief_id': relief_id,
+                                        'breakline_id': line_id,
+                                        'point_id': f"{line_id}_pt_{k}",
+                                        'elevation': elevations[k],
+                                        'geometry': point,
+                                        'polygon': None,
+                                        'source_file': Path(file_path).name
+                                    })
+                        except (ValueError, IndexError) as e:
+                            print(f"Error processing breakline {line_id}: {e}")
+                            continue
+
+            # Extract mass points
+            for mass_point in relief.findall('.//dem:massPoint', namespaces):
+                for point in mass_point.findall('.//gml:Point', namespaces):
+                    point_id = point.get('{http://www.opengis.net/gml}id')
+                    pos = point.find('.//gml:pos', namespaces)
+
+                    if pos is not None:
+                        try:
+                            coords = pos.text.strip().split()
+                            if len(coords) >= 3:
+                                x = float(coords[0])
+                                y = float(coords[1])
+                                z = float(coords[2])
+
+                                if not np.isinf(x) and not np.isinf(y) and not np.isinf(z):
+                                    point_geom = Point(x, y)
+                                    if point_geom.is_valid:
+                                        terrain_elements.append({
+                                            'relief_id': relief_id,
+                                            'mass_point_id': point_id,
+                                            'elevation': z,
+                                            'geometry': point_geom,
+                                            'polygon': None,
+                                            'source_file': Path(file_path).name
+                                        })
+                        except (ValueError, IndexError) as e:
+                            print(f"Error processing mass point {point_id}: {e}")
+                            continue
+
+        print(f"Extracted {len(terrain_elements)} terrain elements from {Path(file_path).name}")
+        return terrain_elements
+
+    except Exception as e:
+        print(f"Error processing terrain in file {Path(file_path).name}: {e}")
+        return []
+
+def extract_vegetation_info(file_path, namespaces):
+    """
+    Extract vegetation features (PlantCover, SolitaryVegetationObject)
+    from a CityGML file, handling LOD0..LOD3 geometry and MultiSurface/CompositeSurface.
+    """
+    vegetation_elements = []
+
+    try:
+        tree = ET.parse(file_path)
+        root = tree.getroot()
+    except Exception as e:
+        print(f"Error parsing CityGML file {Path(file_path).name}: {e}")
+        return vegetation_elements
+
+    # ----------------------------------------------------------------------------
+    # Helper: parse all polygons from a <gml:MultiSurface> or <veg:lodXMultiSurface>
+    # ----------------------------------------------------------------------------
+    def parse_lod_multisurface(lod_elem):
+        """Return a Shapely (Multi)Polygon from gml:Polygon elements under lod_elem."""
+        polygons = []
+        # Find all Polygons (including nested in CompositeSurface)
+        for poly_node in lod_elem.findall('.//gml:Polygon', namespaces):
+            ring_node = poly_node.find('.//gml:exterior//gml:LinearRing//gml:posList', namespaces)
+            if ring_node is None or ring_node.text is None:
+                continue
+
+            # Parse coordinate text
+            coords_text = ring_node.text.strip().split()
+            coords = []
+            # Typically posList is in triplets: (x, y, z)
+            for i in range(0, len(coords_text), 3):
+                try:
+                    x = float(coords_text[i])
+                    y = float(coords_text[i+1])
+                    # z = float(coords_text[i+2])  # if you want z
+                    coords.append((x, y))
+                except:
+                    # Skip any parse error or incomplete coordinate
+                    pass
+
+            if len(coords) >= 3:
+                polygon = Polygon(coords)
+                if polygon.is_valid:
+                    polygons.append(polygon)
+
+        if not polygons:
+            return None
+        elif len(polygons) == 1:
+            return polygons[0]
+        else:
+            return MultiPolygon(polygons)
+
+    # ----------------------------------------------------------------------------
+    # Helper: retrieve geometry from all LOD tags
+    # ----------------------------------------------------------------------------
+    def get_veg_geometry(veg_elem):
+        """
+        Search for geometry under lod0Geometry, lod1Geometry, lod2Geometry,
+        lod3Geometry, lod4Geometry, as well as lod0MultiSurface ... lod3MultiSurface, etc.
+        Return a Shapely geometry (Polygon or MultiPolygon) if found.
+        """
+        geometry_lods = [
+            "lod0Geometry", "lod1Geometry", "lod2Geometry", "lod3Geometry", "lod4Geometry",
+            "lod0MultiSurface", "lod1MultiSurface", "lod2MultiSurface", "lod3MultiSurface", "lod4MultiSurface"
+        ]
+
+        for lod_tag in geometry_lods:
+            # e.g. .//veg:lod3Geometry
+            lod_elem = veg_elem.find(f'.//veg:{lod_tag}', namespaces)
+            if lod_elem is not None:
+                geom = parse_lod_multisurface(lod_elem)
+                if geom is not None:
+                    return geom
+
+        return None
+
+    # ----------------------------------------------------------------------------
+    # 1) PlantCover
+    # ----------------------------------------------------------------------------
+    for plant_cover in root.findall('.//veg:PlantCover', namespaces):
+        cover_id = plant_cover.get('{http://www.opengis.net/gml}id')
+        # averageHeight (if present)
+        avg_height_elem = plant_cover.find('.//veg:averageHeight', namespaces)
+        if avg_height_elem is not None and avg_height_elem.text:
+            try:
+                vegetation_height = float(avg_height_elem.text)
+            except:
+                vegetation_height = None
+        else:
+            vegetation_height = None
+
+        # parse geometry from LOD0..LOD3
+        geometry = get_veg_geometry(plant_cover)
+
+        if geometry is not None and not geometry.is_empty:
+            vegetation_elements.append({
+                'object_type': 'PlantCover',
+                'vegetation_id': cover_id,
+                'height': vegetation_height,
+                'geometry': geometry,
+                'source_file': Path(file_path).name
+            })
+
+    # ----------------------------------------------------------------------------
+    # 2) SolitaryVegetationObject
+    # ----------------------------------------------------------------------------
+    for solitary in root.findall('.//veg:SolitaryVegetationObject', namespaces):
+        veg_id = solitary.get('{http://www.opengis.net/gml}id')
+        height_elem = solitary.find('.//veg:height', namespaces)
+        if height_elem is not None and height_elem.text:
+            try:
+                veg_height = float(height_elem.text)
+            except:
+                veg_height = None
+        else:
+            veg_height = None
+
+        geometry = get_veg_geometry(solitary)
+        if geometry is not None and not geometry.is_empty:
+            vegetation_elements.append({
+                'object_type': 'SolitaryVegetationObject',
+                'vegetation_id': veg_id,
+                'height': veg_height,
+                'geometry': geometry,
+                'source_file': Path(file_path).name
+            })
+
+    if vegetation_elements:
+        print(f"Extracted {len(vegetation_elements)} vegetation objects from {Path(file_path).name}")
+    return vegetation_elements
+
+def process_citygml_file(file_path):
+    """
+    Process a CityGML file to extract building, terrain, and vegetation information
+    """
+    buildings = []
+    terrain_elements = []
+    vegetation_elements = []
+
+    # Namespaces (now includes 'veg')
+    namespaces = {
+        'core': 'http://www.opengis.net/citygml/2.0',
+        'bldg': 'http://www.opengis.net/citygml/building/2.0',
+        'gml': 'http://www.opengis.net/gml',
+        'uro': 'https://www.geospatial.jp/iur/uro/3.0',
+        'dem': 'http://www.opengis.net/citygml/relief/2.0',
+        'veg': 'http://www.opengis.net/citygml/vegetation/2.0'
+    }
+
+    try:
+        # Parse the file once at the start (optional; if you want to share 'root' among sub-extractors)
+        tree = ET.parse(file_path)
+        root = tree.getroot()
+
+        # --- Extract Building Info (existing approach) ---
+        for building in root.findall('.//bldg:Building', namespaces):
+            building_id = building.get('{http://www.opengis.net/gml}id')
+            measured_height = building.find('.//bldg:measuredHeight', namespaces)
+            height = float(measured_height.text) if measured_height is not None else None
+
+            # Extract the footprint (LOD0)
+            lod0_roof_edge = building.find('.//bldg:lod0RoofEdge//gml:posList', namespaces)
+            if lod0_roof_edge is not None:
+                try:
+                    pos_list = lod0_roof_edge.text.strip().split()
+                    coords = []
+                    for i in range(0, len(pos_list), 3):
+                        if i + 2 < len(pos_list):
+                            lon = float(pos_list[i])
+                            lat = float(pos_list[i + 1])
+                            elevation = float(pos_list[i + 2])  # z value
+                            if not np.isinf(lon) and not np.isinf(lat):
+                                coords.append((lon, lat))
+
+                    if len(coords) >= 3 and validate_coords(coords):
+                        polygon = Polygon(coords)
+                        if polygon.is_valid:
+                            buildings.append({
+                                'building_id': building_id,
+                                'height': height,
+                                'ground_elevation': elevation,  # Add ground elevation if relevant
+                                'geometry': polygon,
+                                'source_file': Path(file_path).name
+                            })
+                except (ValueError, IndexError) as e:
+                    print(f"Error processing building {building_id} in file {Path(file_path).name}: {e}")
+
+        # --- Extract Terrain Info (existing function) ---
+        terrain_elements = extract_terrain_info(file_path, namespaces)
+
+        # --- Extract Vegetation Info (new function) ---
+        vegetation_elements = extract_vegetation_info(file_path, namespaces)
+
+        print(f"Processed {Path(file_path).name}: "
+              f"{len(buildings)} buildings, {len(terrain_elements)} terrain elements, "
+              f"{len(vegetation_elements)} vegetation objects")
+
+    except Exception as e:
+        print(f"Error processing file {Path(file_path).name}: {e}")
+
+    return buildings, terrain_elements, vegetation_elements
+
+def load_plateau_with_terrain(url, base_dir):
+    """
+    Load PLATEAU data, extracting Buildings, Terrain, and Vegetation data from CityGML.
+    """
+    # 1) Download & unzip
+    citygml_path, foldername = download_and_extract_zip(url, extract_to=base_dir)
+
+    # 2) Identify CityGML files in typical folder structure
+    try:
+        citygml_dir = os.path.join(citygml_path, 'udx')
+        if not os.path.exists(citygml_dir):
+            citygml_dir = os.path.join(citygml_path, foldername, 'udx')
+
+        bldg_dir = os.path.join(citygml_dir, 'bldg')
+        dem_dir = os.path.join(citygml_dir, 'dem')
+
+        # NEW: check for vegetation folder
+        veg_dir = os.path.join(citygml_dir, 'veg')
+
+        citygml_files = []
+
+        # If there's a building folder, gather .gml from there
+        if os.path.exists(bldg_dir):
+            citygml_files += [
+                os.path.join(bldg_dir, f) for f in os.listdir(bldg_dir) if f.endswith('.gml')
+            ]
+        else:
+            # If no 'bldg' folder, look directly in 'udx'
+            citygml_files += [
+                os.path.join(citygml_dir, f) for f in os.listdir(citygml_dir) if f.endswith('.gml')
+            ]
+
+        # Also gather DEM .gml (terrain)
+        if os.path.exists(dem_dir):
+            citygml_files += [
+                os.path.join(dem_dir, f) for f in os.listdir(dem_dir) if f.endswith('.gml')
+            ]
+
+        # ADD THIS: gather VEG .gml (vegetation)
+        if os.path.exists(veg_dir):
+            citygml_files += [
+                os.path.join(veg_dir, f) for f in os.listdir(veg_dir) if f.endswith('.gml')
+            ]
+
+        total_files = len(citygml_files)
+        print(f"Found {total_files} CityGML files to process")
+
+    except Exception as e:
+        print(f"Error finding CityGML files: {e}")
+        return None, None, None
+
+    all_buildings = []
+    all_terrain = []
+    all_vegetation = []
+
+    # 3) Process each CityGML
+    for file_path in tqdm(citygml_files, desc="Processing CityGML files"):
+        buildings, terrain_elements, vegetation_elements = process_citygml_file(file_path)
+        all_buildings.extend(buildings)
+        all_terrain.extend(terrain_elements)
+        all_vegetation.extend(vegetation_elements)
+
+    # 4) Create GeoDataFrame for Buildings
+    if all_buildings:
+        gdf_buildings = gpd.GeoDataFrame(all_buildings, geometry='geometry')
+        gdf_buildings.set_crs(epsg=6697, inplace=True)
+
+        # Swap coords from (lon, lat) to (lat, lon) if needed
+        swapped_geometries = [swap_coordinates(geom) for geom in gdf_buildings.geometry]
+        gdf_buildings_swapped = gpd.GeoDataFrame(
+            {
+                'building_id': gdf_buildings['building_id'],
+                'height': gdf_buildings['height'],
+                'ground_elevation': gdf_buildings['ground_elevation'],
+                'source_file': gdf_buildings['source_file'],
+                'geometry': swapped_geometries
+            },
+            crs='EPSG:6697'
+        )
+
+        # Save
+        gdf_buildings_swapped['id'] = gdf_buildings_swapped.index
+        gdf_buildings_swapped.to_file('all_buildings_with_elevation.geojson', driver='GeoJSON')
+        print(f"\nBuildings saved to all_buildings_with_elevation.geojson")
+    else:
+        gdf_buildings_swapped = None
+
+    # 5) Create GeoDataFrame for Terrain
+    if all_terrain:
+        gdf_terrain = gpd.GeoDataFrame(all_terrain, geometry='geometry')
+        gdf_terrain.set_crs(epsg=6697, inplace=True)
+
+        swapped_geometries = []
+        for geom in gdf_terrain.geometry:
+            if isinstance(geom, (Polygon, MultiPolygon)):
+                swapped_geometries.append(swap_coordinates(geom))
+            elif isinstance(geom, Point):
+                swapped_geometries.append(Point(geom.y, geom.x))
+            else:
+                swapped_geometries.append(geom)
+
+        terrain_data = {
+            'relief_id': gdf_terrain.get('relief_id', ''),
+            'tin_id': gdf_terrain.get('tin_id', ''),
+            'triangle_id': gdf_terrain.get('triangle_id', ''),
+            'breakline_id': gdf_terrain.get('breakline_id', ''),
+            'mass_point_id': gdf_terrain.get('mass_point_id', ''),
+            'point_id': gdf_terrain.get('point_id', ''),
+            'elevation': gdf_terrain['elevation'],
+            'source_file': gdf_terrain['source_file'],
+            'geometry': swapped_geometries
+        }
+
+        gdf_terrain_swapped = gpd.GeoDataFrame(terrain_data, geometry='geometry', crs='EPSG:6697')
+        gdf_terrain_swapped.to_file('terrain_elevation.geojson', driver='GeoJSON')
+        print(f"Terrain saved to terrain_elevation.geojson")
+    else:
+        gdf_terrain_swapped = None
+
+    # 6) Create GeoDataFrame for Vegetation
+    if all_vegetation:
+        gdf_veg = gpd.GeoDataFrame(all_vegetation, geometry='geometry')
+        gdf_veg.set_crs(epsg=6697, inplace=True)
+
+        swapped_geometries = []
+        for geom in gdf_veg.geometry:
+            if isinstance(geom, (Polygon, MultiPolygon)):
+                swapped_geometries.append(swap_coordinates(geom))
+            elif isinstance(geom, Point):
+                swapped_geometries.append(Point(geom.y, geom.x))
+            else:
+                swapped_geometries.append(geom)
+
+        vegetation_data = {
+            'object_type':    gdf_veg.get('object_type', ''),
+            'vegetation_id':  gdf_veg.get('vegetation_id', ''),
+            'height':         gdf_veg.get('height', None),
+            'avg_elevation':  gdf_veg.get('avg_elevation', None),  # Use .get() with a default
+            'source_file':    gdf_veg.get('source_file', ''),
+            'geometry':       swapped_geometries
+        }
+        gdf_vegetation_swapped = gpd.GeoDataFrame(vegetation_data, geometry='geometry', crs='EPSG:6697')
+        gdf_vegetation_swapped.to_file('vegetation_elevation.geojson', driver='GeoJSON')
+        print(f"Vegetation saved to vegetation_elevation.geojson")
+    else:
+        gdf_vegetation_swapped = None
+
+    return gdf_buildings_swapped, gdf_terrain_swapped, gdf_vegetation_swapped

voxcity/generator.py

@@ -24,6 +24,7 @@ from .downloader.oemj import save_oemj_as_geotiff
 from .downloader.omt import load_gdf_from_openmaptiles
 from .downloader.eubucco import load_gdf_from_eubucco
 from .downloader.overture import load_gdf_from_overture
+from .downloader.citygml import load_plateau_with_terrain
 from .downloader.gee import (
     initialize_earth_engine,
     get_roi,
@@ -691,6 +692,125 @@ def get_voxcity(rectangle_vertices, building_source, land_cover_source, canopy_h
 
     return voxcity_grid, building_height_grid, building_min_height_grid, building_id_grid, canopy_height_grid, land_cover_grid, dem_grid, building_gdf
 
+def get_voxcity_CityGML(rectangle_vertices, url_citygml, land_cover_source, canopy_height_source, meshsize, **kwargs):
+    """Main function to generate a complete voxel city model.
+
+    Args:
+        rectangle_vertices: List of coordinates defining the area of interest
+        building_source: Source for building height data (e.g. 'OSM', 'EUBUCCO')
+        land_cover_source: Source for land cover data (e.g. 'ESA', 'ESRI') 
+        canopy_height_source: Source for tree canopy height data
+        dem_source: Source for digital elevation model data ('Flat' or other source)
+        meshsize: Size of each grid cell in meters
+        **kwargs: Additional keyword arguments including:
+            - output_dir: Directory to save output files (default: 'output')
+            - min_canopy_height: Minimum height threshold for tree canopy
+            - remove_perimeter_object: Factor to remove objects near perimeter
+            - mapvis: Whether to visualize grids on map
+            - voxelvis: Whether to visualize 3D voxel model
+            - voxelvis_img_save_path: Path to save 3D visualization
+
+    Returns:
+        tuple containing:
+            - voxcity_grid: 3D voxel grid of the complete city model
+            - building_height_grid: 2D grid of building heights
+            - building_min_height_grid: 2D grid of minimum building heights
+            - building_id_grid: 2D grid of building IDs
+            - canopy_height_grid: 2D grid of tree canopy heights
+            - land_cover_grid: 2D grid of land cover classifications
+            - dem_grid: 2D grid of ground elevation
+            - building_geojson: GeoJSON of building footprints and metadata
+    """
+    # Create output directory if it doesn't exist
+    output_dir = kwargs.get("output_dir", "output")
+    os.makedirs(output_dir, exist_ok=True)
+        
+    # Remove 'output_dir' from kwargs to prevent duplication
+    kwargs.pop('output_dir', None)
+
+    # get all required gdfs    
+    building_gdf, terrain_gdf, vegetation_gdf = load_plateau_with_terrain(url_citygml, base_dir=output_dir)
+
+    land_cover_grid = get_land_cover_grid(rectangle_vertices, meshsize, land_cover_source, output_dir, **kwargs)        
+
+    # building_height_grid, building_min_height_grid, building_id_grid, building_gdf = get_building_height_grid(rectangle_vertices, meshsize, building_source, output_dir, **kwargs)
+    building_height_grid, building_min_height_grid, building_id_grid, filtered_buildings = create_building_height_grid_from_gdf_polygon(buildings_gdf, meshsize, rectangle_vertices, **kwargs)
+
+    # Visualize grid if requested
+    grid_vis = kwargs.get("gridvis", True)    
+    if grid_vis:
+        building_height_grid_nan = building_height_grid.copy()
+        building_height_grid_nan[building_height_grid_nan == 0] = np.nan
+        visualize_numerical_grid(np.flipud(building_height_grid_nan), meshsize, "building height (m)", cmap='viridis', label='Value')
+    
+    # Save building data to GeoJSON
+    if not building_gdf.empty:
+        save_path = f"{output_dir}/building.gpkg"
+        building_gdf.to_file(save_path, driver='GPKG')
+    
+    # Get canopy height data
+    if canopy_height_source == "Static":
+        # Create canopy height grid with same shape as land cover grid
+        canopy_height_grid_comp = np.zeros_like(land_cover_grid, dtype=float)
+        
+        # Set default static height for trees (20 meters is a typical average tree height)
+        static_tree_height = kwargs.get("static_tree_height", 10.0)
+        tree_mask = (land_cover_grid == 4)
+        
+        # Set static height for tree cells
+        canopy_height_grid_comp[tree_mask] = static_tree_height
+    else:
+        canopy_height_grid_comp = get_canopy_height_grid(rectangle_vertices, meshsize, canopy_height_source, output_dir, **kwargs)
+    
+    canopy_height_grid = create_vegetation_height_grid_from_gdf_polygon(vegetation_gdf, meshsize, rectangle_vertices)
+    mask = (canopy_height_grid == 0) & (canopy_height_grid_comp != 0)
+    canopy_height_grid[mask] = canopy_height_grid_comp[mask]
+    
+    # Handle DEM - either flat or from source
+    if kwargs.pop('flat_dem', None):
+        dem_grid = np.zeros_like(land_cover_grid)
+    else:
+        dem_grid = create_dem_grid_from_gdf_polygon(terrain_gdf, meshsize, rectangle_vertices)
+        
+        # Visualize grid if requested
+        grid_vis = kwargs.get("gridvis", True)    
+        if grid_vis:
+            visualize_numerical_grid(np.flipud(dem_grid), meshsize, title='Digital Elevation Model', cmap='terrain', label='Elevation (m)')
+        
+
+    # Apply minimum canopy height threshold if specified
+    min_canopy_height = kwargs.get("min_canopy_height")
+    if min_canopy_height is not None:
+        canopy_height_grid[canopy_height_grid < kwargs["min_canopy_height"]] = 0        
+
+    # Remove objects near perimeter if specified
+    remove_perimeter_object = kwargs.get("remove_perimeter_object")
+    if (remove_perimeter_object is not None) and (remove_perimeter_object > 0):
+        # Calculate perimeter width based on grid dimensions
+        w_peri = int(remove_perimeter_object * building_height_grid.shape[0] + 0.5)
+        h_peri = int(remove_perimeter_object * building_height_grid.shape[1] + 0.5)
+        
+        # Clear canopy heights in perimeter
+        canopy_height_grid[:w_peri, :] = canopy_height_grid[-w_peri:, :] = canopy_height_grid[:, :h_peri] = canopy_height_grid[:, -h_peri:] = 0
+
+        # Find building IDs in perimeter regions
+        ids1 = np.unique(building_id_grid[:w_peri, :][building_id_grid[:w_peri, :] > 0])
+        ids2 = np.unique(building_id_grid[-w_peri:, :][building_id_grid[-w_peri:, :] > 0])
+        ids3 = np.unique(building_id_grid[:, :h_peri][building_id_grid[:, :h_peri] > 0])
+        ids4 = np.unique(building_id_grid[:, -h_peri:][building_id_grid[:, -h_peri:] > 0])
+        remove_ids = np.concatenate((ids1, ids2, ids3, ids4))
+        
+        # Remove buildings in perimeter
+        for remove_id in remove_ids:
+            positions = np.where(building_id_grid == remove_id)
+            building_height_grid[positions] = 0
+            building_min_height_grid[positions] = [[] for _ in range(len(building_min_height_grid[positions]))]    
+
+    # Generate 3D voxel grid
+    voxcity_grid = create_3d_voxel(building_height_grid, building_min_height_grid, building_id_grid, land_cover_grid, dem_grid, canopy_height_grid, meshsize, land_cover_source)
+
+    return voxcity_grid, building_height_grid, building_min_height_grid, building_id_grid, canopy_height_grid, land_cover_grid, dem_grid, building_gdf
+
 def replace_nan_in_nested(arr, replace_value=10.0):
     """Replace NaN values in a nested array structure with a specified value.
 

voxcity/geoprocessor/grid.py

@@ -1013,4 +1013,253 @@ def grid_to_point_geodataframe(grid_ori, rectangle_vertices, meshsize):
         'value': values
     }, crs=CRS.from_epsg(4326))
     
-    return gdf
+    return gdf
+
+def create_vegetation_height_grid_from_gdf_polygon(veg_gdf, mesh_size, polygon):
+    """
+    Create a vegetation height grid from a GeoDataFrame of vegetation polygons/objects
+    within the bounding box of a given polygon, at a specified mesh spacing.
+    Cells that intersect one or more vegetation polygons receive the
+    (by default) maximum vegetation height among intersecting polygons.
+    Cells that do not intersect any vegetation are set to 0.
+
+    Args:
+        veg_gdf (GeoDataFrame): A GeoDataFrame containing vegetation features
+                                (usually polygons) with a 'height' column
+                                (or a similarly named attribute). Must be in
+                                EPSG:4326 or reprojectable to it.
+        mesh_size (float):      Desired grid spacing in meters.
+        polygon (list or Polygon):
+          - If a list of (lon, lat) coords, will be converted to a shapely Polygon
+            in EPSG:4326.
+          - If a shapely Polygon, it must be in or reprojectable to EPSG:4326.
+
+    Returns:
+        np.ndarray: 2D array of vegetation height values covering the bounding box
+                    of the polygon. The array is indexed [row, col] from top row
+                    (north) to bottom row (south). Cells with no intersecting
+                    vegetation are set to 0.
+    """
+    # ------------------------------------------------------------------------
+    # 1. Ensure veg_gdf is in WGS84 (EPSG:4326)
+    # ------------------------------------------------------------------------
+    if veg_gdf.crs is None:
+        warnings.warn("veg_gdf has no CRS. Assuming EPSG:4326. "
+                      "If this is incorrect, please set the correct CRS and re-run.")
+        veg_gdf = veg_gdf.set_crs(epsg=4326)
+    else:
+        if veg_gdf.crs.to_epsg() != 4326:
+            veg_gdf = veg_gdf.to_crs(epsg=4326)
+
+    # Must have a 'height' column (or change to your column name)
+    if 'height' not in veg_gdf.columns:
+        raise ValueError("Vegetation GeoDataFrame must have a 'height' column.")
+
+    # ------------------------------------------------------------------------
+    # 2. Convert input polygon to shapely Polygon in WGS84
+    # ------------------------------------------------------------------------
+    if isinstance(polygon, list):
+        poly = Polygon(polygon)
+    elif isinstance(polygon, Polygon):
+        poly = polygon
+    else:
+        raise ValueError("polygon must be a list of (lon, lat) or a shapely Polygon.")
+
+    # ------------------------------------------------------------------------
+    # 3. Compute bounding box & grid dimensions
+    # ------------------------------------------------------------------------
+    left, bottom, right, top = poly.bounds
+    geod = Geod(ellps="WGS84")
+
+    # Horizontal (width) distance in meters
+    _, _, width_m = geod.inv(left, bottom, right, bottom)
+    # Vertical (height) distance in meters
+    _, _, height_m = geod.inv(left, bottom, left, top)
+
+    # Number of cells horizontally and vertically
+    num_cells_x = int(width_m / mesh_size + 0.5)
+    num_cells_y = int(height_m / mesh_size + 0.5)
+
+    if num_cells_x < 1 or num_cells_y < 1:
+        warnings.warn("Polygon bounding box is smaller than mesh_size; returning empty array.")
+        return np.array([])
+
+    # ------------------------------------------------------------------------
+    # 4. Generate the grid (cell centers) covering the bounding box
+    # ------------------------------------------------------------------------
+    xs = np.linspace(left, right, num_cells_x)
+    ys = np.linspace(top, bottom, num_cells_y)  # top→bottom
+    X, Y = np.meshgrid(xs, ys)
+
+    # Flatten these for convenience
+    xs_flat = X.ravel()
+    ys_flat = Y.ravel()
+
+    # Create cell-center points as a GeoDataFrame
+    grid_points = gpd.GeoDataFrame(
+        geometry=[Point(lon, lat) for lon, lat in zip(xs_flat, ys_flat)],
+        crs="EPSG:4326"
+    )
+
+    # ------------------------------------------------------------------------
+    # 5. Spatial join (INTERSECTION) to find which vegetation objects each cell intersects
+    #    - We only fill the cell if the point is actually inside (or intersects) a vegetation polygon
+    #      If your data is more consistent with "contains" or "within", adjust the predicate accordingly.
+    # ------------------------------------------------------------------------
+    # NOTE:
+    #   * If your vegetation is polygons, "predicate='intersects'" or "contains"
+    #     can be used. Typically we check whether the cell center is inside the polygon.
+    #   * If your vegetation is a point layer, you might do "predicate='within'"
+    #     or similar. Adjust as needed.
+    #
+    # We'll do a left join so that unmatched cells remain in the result with NaN values.
+    # Then we group by the index of the original grid_points to handle multiple intersects.
+    # The 'index_right' is from the vegetation layer.
+    # ------------------------------------------------------------------------
+
+    joined = gpd.sjoin(
+        grid_points,
+        veg_gdf[['height', 'geometry']],
+        how='left',
+        predicate='intersects'
+    )
+
+    # Because one cell (row in grid_points) can intersect multiple polygons,
+    # we need to aggregate them. We'll take the *maximum* height by default.
+    joined_agg = (
+        joined.groupby(joined.index)   # group by the index from grid_points
+              .agg({'height': 'max'})  # or 'mean' if you prefer an average
+    )
+
+    # joined_agg is now a DataFrame with the same index as grid_points.
+    # If a row didn't intersect any polygon, 'height' is NaN.
+
+    # ------------------------------------------------------------------------
+    # 6. Build the 2D height array, initializing with zeros
+    # ------------------------------------------------------------------------
+    veg_grid = np.zeros((num_cells_y, num_cells_x), dtype=float)
+
+    # The row, col in the final array corresponds to how we built 'grid_points':
+    #   row = i // num_cells_x
+    #   col = i % num_cells_x
+    for i, row_data in joined_agg.iterrows():
+        if not np.isnan(row_data['height']):  # Only set values for cells with vegetation
+            row_idx = i // num_cells_x
+            col_idx = i % num_cells_x
+            veg_grid[row_idx, col_idx] = row_data['height']
+
+    # Result: row=0 is the top-most row, row=-1 is bottom.
+    return np.flipud(veg_grid)
+
+def create_dem_grid_from_gdf_polygon(terrain_gdf, mesh_size, polygon):
+    """
+    Create a height grid from a terrain GeoDataFrame within the bounding box
+    of the given polygon, using nearest-neighbor sampling of elevations.
+    Edges of the bounding box will also receive a nearest elevation,
+    so there should be no NaNs around edges if data coverage is sufficient.
+
+    Args:
+        terrain_gdf (GeoDataFrame): A GeoDataFrame containing terrain features
+                                    (points or centroids) with an 'elevation' column.
+                                    Must be in EPSG:4326 or reprojectable to it.
+        mesh_size (float):          Desired grid spacing in meters.
+        polygon (list or Polygon):  Polygon specifying the region of interest.
+                                    - If list of (lon, lat), will be made into a Polygon.
+                                    - If a shapely Polygon, must be in WGS84 (EPSG:4326)
+                                      or reprojected to it.
+
+    Returns:
+        np.ndarray: 2D array of height values covering the bounding box of the polygon,
+                    from top row (north) to bottom row (south). Any location not
+                    matched by terrain_gdf data remains NaN, but edges will not
+                    automatically be NaN if terrain coverage exists.
+    """
+
+    # ------------------------------------------------------------------------
+    # 1. Ensure terrain_gdf is in WGS84 (EPSG:4326)
+    # ------------------------------------------------------------------------
+    if terrain_gdf.crs is None:
+        warnings.warn("terrain_gdf has no CRS. Assuming EPSG:4326. "
+                      "If this is incorrect, please set the correct CRS and re-run.")
+        terrain_gdf = terrain_gdf.set_crs(epsg=4326)
+    else:
+        # Reproject if needed
+        if terrain_gdf.crs.to_epsg() != 4326:
+            terrain_gdf = terrain_gdf.to_crs(epsg=4326)
+
+    # Convert input polygon to shapely Polygon in WGS84
+    if isinstance(polygon, list):
+        poly = Polygon(polygon)  # assume coords are (lon, lat) in EPSG:4326
+    elif isinstance(polygon, Polygon):
+        poly = polygon
+    else:
+        raise ValueError("`polygon` must be a list of (lon, lat) or a shapely Polygon.")
+
+    # ------------------------------------------------------------------------
+    # 2. Compute bounding box and number of grid cells
+    # ------------------------------------------------------------------------
+    left, bottom, right, top = poly.bounds
+    geod = Geod(ellps="WGS84")
+
+    # Geodesic distances in meters
+    _, _, width_m = geod.inv(left, bottom, right, bottom)
+    _, _, height_m = geod.inv(left, bottom, left, top)
+
+    # Number of cells in X and Y directions
+    num_cells_x = int(width_m / mesh_size + 0.5)
+    num_cells_y = int(height_m / mesh_size + 0.5)
+
+    if num_cells_x < 1 or num_cells_y < 1:
+        warnings.warn("Polygon bounding box is smaller than mesh_size; returning empty array.")
+        return np.array([])
+
+    # ------------------------------------------------------------------------
+    # 3. Generate grid points covering the bounding box
+    #    (all points, not just inside the polygon)
+    # ------------------------------------------------------------------------
+    xs = np.linspace(left, right, num_cells_x)
+    ys = np.linspace(top, bottom, num_cells_y)  # top->bottom
+    X, Y = np.meshgrid(xs, ys)
+
+    # Flatten for convenience
+    xs_flat = X.ravel()
+    ys_flat = Y.ravel()
+
+    # Create GeoDataFrame of all bounding-box points
+    grid_points = gpd.GeoDataFrame(
+        geometry=[Point(lon, lat) for lon, lat in zip(xs_flat, ys_flat)],
+        crs="EPSG:4326"
+    )
+
+    # ------------------------------------------------------------------------
+    # 4. Nearest-neighbor join from terrain_gdf to grid points
+    # ------------------------------------------------------------------------
+    if 'elevation' not in terrain_gdf.columns:
+        raise ValueError("terrain_gdf must have an 'elevation' column.")
+
+    # Nearest spatial join (requires GeoPandas >= 0.10)
+    # This will assign each grid point the nearest terrain_gdf elevation.
+    grid_points_elev = gpd.sjoin_nearest(
+        grid_points,
+        terrain_gdf[['elevation', 'geometry']],
+        how="left",
+        distance_col="dist_to_terrain"
+    )
+
+    # ------------------------------------------------------------------------
+    # 5. Build the final 2D height array
+    #    (rows: top->bottom, columns: left->right)
+    # ------------------------------------------------------------------------
+    dem_grid = np.full((num_cells_y, num_cells_x), np.nan, dtype=float)
+
+    # The index mapping of grid_points_elev is the same as grid_points, so:
+    # row = i // num_cells_x, col = i % num_cells_x
+    for i, elevation_val in zip(grid_points_elev.index, grid_points_elev['elevation']):
+        row = i // num_cells_x
+        col = i % num_cells_x
+        dem_grid[row, col] = elevation_val  # could be NaN if no data
+
+    # By default, row=0 is the "north/top" row, row=-1 is "south/bottom" row.
+    # If you prefer the bottom row as index=0, you'd do: np.flipud(dem_grid)
+
+    return np.flipud(dem_grid)

{voxcity-0.4.6.dist-info → voxcity-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: voxcity
-Version: 0.4.6
+Version: 0.5.0
 Summary: voxcity is an easy and one-stop tool to output 3d city models for microclimate simulation by integrating multiple geospatial open-data
 Author-email: Kunihiko Fujiwara <kunihiko@nus.edu.sg>
 Maintainer-email: Kunihiko Fujiwara <kunihiko@nus.edu.sg>
@@ -53,11 +53,13 @@ Requires-Dist: joblib
 Requires-Dist: trimesh
 Requires-Dist: pyvista
 Requires-Dist: IPython
+Requires-Dist: lxml
 Provides-Extra: dev
 Requires-Dist: coverage; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
 
 [![PyPi version](https://img.shields.io/pypi/v/voxcity.svg)](https://pypi.python.org/pypi/voxcity)
 [![Python versions](https://img.shields.io/pypi/pyversions/voxcity.svg)](https://pypi.org/project/voxcity/)
@@ -66,6 +68,9 @@ Requires-Dist: ruff; extra == "dev"
 [![Downloads](https://pepy.tech/badge/voxcity)](https://pepy.tech/project/voxcity)
 <!-- [![License: CC BY-SA 4.0](https://licensebuttons.net/l/by-sa/4.0/80x15.png)](https://creativecommons.org/licenses/by-sa/4.0/) -->
 
+<p align="center">
+  Tutorial preview: <a href="https://colab.research.google.com/drive/1Lofd3RawKMr6QuUsamGaF48u2MN0hfrP?usp=sharing">[Google Colab]</a>
+</p>
 
 # VoxCity
 

{voxcity-0.4.6.dist-info → voxcity-0.5.0.dist-info}/RECORD

@@ -1,6 +1,7 @@
 voxcity/__init__.py,sha256=el9v3gfybHOF_GUYPeSOqN0-vCrTW0eU1mcvi0sEfeU,252
-voxcity/generator.py,sha256=0RKWcWKfwFs2xcepyEDLMQdHqGhAGlpPwhNe6UJTRuI,35348
+voxcity/generator.py,sha256=bHDNH2lmAq7iCLMIFMatSpI8LhM_NGNy8MjfiICZZyc,42101
 voxcity/downloader/__init__.py,sha256=OgGcGxOXF4tjcEL6DhOnt13DYPTvOigUelp5xIpTqM0,171
+voxcity/downloader/citygml.py,sha256=phGxEz829mDGXEugs8rTQzARQy-_JyqfcDLMijR4DoM,24467
 voxcity/downloader/eubucco.py,sha256=XCkkdEPNuWdrnuxzL80Ext37WsgiCiZGueb-aQV5rvI,14476
 voxcity/downloader/gee.py,sha256=hEN5OvQAltORYnrlPbmYcDequ6lKLmwyTbNaCZ81Vj8,16089
 voxcity/downloader/mbfp.py,sha256=pGJuXXLRuRedlORXfg8WlgAVwmKI30jxki9t-v5NejY,3972
@@ -15,7 +16,7 @@ voxcity/exporter/magicavoxel.py,sha256=Fsv7yGRXeKmp82xcG3rOb0t_HtoqltNq2tHl08xVl
 voxcity/exporter/obj.py,sha256=0RBFPMKGRH6uNmCLIwAoYFko1bOZKtTSwg7QnoPMud0,21593
 voxcity/geoprocessor/__init_.py,sha256=JzPVhhttxBWvaZ0IGX2w7OWL5bCo_TIvpHefWeNXruA,133
 voxcity/geoprocessor/draw.py,sha256=8Em2NvazFpYfFJUqG9LofNXaxdghKLL_rNuztmPwn8Q,13911
-voxcity/geoprocessor/grid.py,sha256=ZZgnrvfinIGd4dLODoA3G0yru7XfR_LXph65PDRIj_Y,44428
+voxcity/geoprocessor/grid.py,sha256=g1go8vvv2q4epnkZIN6CvWieSqxFWtLEYqX5CPw6vUo,56340
 voxcity/geoprocessor/mesh.py,sha256=r3cRPLgpbhjwgESBemHWWJ5pEWl2KdkRhID6mdLhios,11171
 voxcity/geoprocessor/network.py,sha256=opb_kpUCAxDd1qtrWPStqR5reYZtVe96XxazNSen7Lk,18851
 voxcity/geoprocessor/polygon.py,sha256=8Vb2AbkpKYhq1kk2hQMc-gitmUo9pFIe910v4p1vP2g,37772
@@ -29,9 +30,9 @@ voxcity/utils/lc.py,sha256=RwPd-VY3POV3gTrBhM7TubgGb9MCd3nVah_G8iUEF7k,11562
 voxcity/utils/material.py,sha256=Vt3IID5Ft54HNJcEC4zi31BCPqi_687X3CSp7rXaRVY,5907
 voxcity/utils/visualization.py,sha256=SF8W7sqvBl3sZbB5noWCY9ic2D34Gq01VZYJ9NDNZ4Y,85237
 voxcity/utils/weather.py,sha256=CFPtoqRTajwMRswswDChwQ3BW1cGsnA3orgWHgz7Ehg,26304
-voxcity-0.4.6.dist-info/AUTHORS.rst,sha256=m82vkI5QokEGdcHof2OxK39lf81w1P58kG9ZNNAKS9U,175
-voxcity-0.4.6.dist-info/LICENSE,sha256=-hGliOFiwUrUSoZiB5WF90xXGqinKyqiDI2t6hrnam8,1087
-voxcity-0.4.6.dist-info/METADATA,sha256=66WS05QBtRe4bEiH8XwLKTUTcMU1A83n0VrBl4nMMG4,25527
-voxcity-0.4.6.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
-voxcity-0.4.6.dist-info/top_level.txt,sha256=00b2U-LKfDllt6RL1R33MXie5MvxzUFye0NGD96t_8I,8
-voxcity-0.4.6.dist-info/RECORD,,
+voxcity-0.5.0.dist-info/licenses/AUTHORS.rst,sha256=m82vkI5QokEGdcHof2OxK39lf81w1P58kG9ZNNAKS9U,175
+voxcity-0.5.0.dist-info/licenses/LICENSE,sha256=s_jE1Df1nTPL4A_5GCGic5Zwex0CVaPKcAmSilxJPPE,1089
+voxcity-0.5.0.dist-info/METADATA,sha256=sAc1kbwrv22VVTNU3wwPvj3IlOpqrnwMs1ANOdZr3v0,25733
+voxcity-0.5.0.dist-info/WHEEL,sha256=1tXe9gY0PYatrMPMDd6jXqjfpz_B-Wqm32CPfRC58XU,91
+voxcity-0.5.0.dist-info/top_level.txt,sha256=00b2U-LKfDllt6RL1R33MXie5MvxzUFye0NGD96t_8I,8
+voxcity-0.5.0.dist-info/RECORD,,

{voxcity-0.4.6.dist-info → voxcity-0.5.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (76.0.0)
+Generator: setuptools (77.0.3)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{voxcity-0.4.6.dist-info → voxcity-0.5.0.dist-info/licenses}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022, winstonyym
+Copyright (c) 2025, kunifujiwara
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal