voxcity 0.6.16__py3-none-any.whl → 0.6.18__py3-none-any.whl

voxcity/downloader/osm.py

@@ -370,7 +370,7 @@ def create_rings_from_ways(way_ids, ways, nodes):
     
     return rings
 
-def load_gdf_from_openstreetmap(rectangle_vertices):
+def load_gdf_from_openstreetmap(rectangle_vertices, floor_height=3.0):
     """Download and process building footprint data from OpenStreetMap.
     
     This function:
@@ -471,7 +471,7 @@ def load_gdf_from_openstreetmap(rectangle_vertices):
         """
         return [coord for coord in geometry]  # Keep original order since already (lon, lat)
     
-    def get_height_from_properties(properties):
+    def get_height_from_properties(properties, floor_height=3.0):
         """Helper function to extract height from properties.
         
         Args:
@@ -487,9 +487,25 @@ def load_gdf_from_openstreetmap(rectangle_vertices):
             except ValueError:
                 pass
         
+        # Infer from floors when available
+        floors_candidates = [
+            properties.get('building:levels'),
+            properties.get('levels'),
+            properties.get('num_floors')
+        ]
+        for floors in floors_candidates:
+            if floors is None:
+                continue
+            try:
+                floors_val = float(floors)
+                if floors_val > 0:
+                    return float(floor_height) * floors_val
+            except ValueError:
+                continue
+        
         return 0  # Default height if no valid height found
     
-    def extract_properties(element):
+    def extract_properties(element, floor_height=3.0):
         """Helper function to extract and process properties from an element.
         
         Args:
@@ -501,7 +517,7 @@ def load_gdf_from_openstreetmap(rectangle_vertices):
         properties = element.get('tags', {})
         
         # Get height (now using the helper function)
-        height = get_height_from_properties(properties)
+        height = get_height_from_properties(properties, floor_height=floor_height)
             
         # Get min_height and min_level
         min_height = properties.get('min_height', '0')
@@ -526,7 +542,7 @@ def load_gdf_from_openstreetmap(rectangle_vertices):
             "is_inner": False,
             "levels": levels,
             "height_source": "explicit" if properties.get('height') or properties.get('building:height') 
-                               else "levels" if levels is not None 
+                               else "levels" if (levels is not None) or (properties.get('num_floors') is not None)
                                else "default",
             "min_level": min_level if min_level != '0' else None,
             "building": properties.get('building', 'no'),
@@ -584,13 +600,13 @@ def load_gdf_from_openstreetmap(rectangle_vertices):
         if element['type'] == 'way':
             if 'geometry' in element:
                 coords = [(node['lon'], node['lat']) for node in element['geometry']]
-                properties = extract_properties(element)
+                properties = extract_properties(element, floor_height=floor_height)
                 feature = create_polygon_feature(coords, properties)
                 if feature:
                     features.append(feature)
                     
         elif element['type'] == 'relation':
-            properties = extract_properties(element)
+            properties = extract_properties(element, floor_height=floor_height)
             
             # Process each member of the relation
             for member in element['members']:

voxcity/downloader/overture.py

@@ -254,7 +254,7 @@ def join_gdfs_vertically(gdf1, gdf2):
     
     return combined_gdf
 
-def load_gdf_from_overture(rectangle_vertices):
+def load_gdf_from_overture(rectangle_vertices, floor_height=3.0):
     """
     Download and process building footprint data from Overture Maps.
     
@@ -287,6 +287,31 @@ def load_gdf_from_overture(rectangle_vertices):
     # Combine both datasets into a single comprehensive building dataset
     joined_building_gdf = join_gdfs_vertically(building_gdf, building_part_gdf)
 
+    # Ensure numeric height and infer from floors when missing
+    try:
+        joined_building_gdf['height'] = pd.to_numeric(joined_building_gdf.get('height', None), errors='coerce')
+    except Exception:
+        # Create height column if missing
+        joined_building_gdf['height'] = None
+        joined_building_gdf['height'] = pd.to_numeric(joined_building_gdf['height'], errors='coerce')
+
+    # Combine possible floors columns (first non-null among candidates)
+    floors_candidates = []
+    for col in ['building:levels', 'levels', 'num_floors', 'floors']:
+        if col in joined_building_gdf.columns:
+            floors_candidates.append(pd.to_numeric(joined_building_gdf[col], errors='coerce'))
+    if floors_candidates:
+        floors_series = floors_candidates[0]
+        for s in floors_candidates[1:]:
+            floors_series = floors_series.combine_first(s)
+        # Infer height where height is NaN/<=0 and floors > 0
+        mask_missing_height = (~joined_building_gdf['height'].notna()) | (joined_building_gdf['height'] <= 0)
+        if isinstance(floor_height, (int, float)):
+            inferred = floors_series * float(floor_height)
+        else:
+            inferred = floors_series * 3.0
+        joined_building_gdf.loc[mask_missing_height & (floors_series > 0), 'height'] = inferred
+
     # Assign sequential IDs based on the final dataset index
     joined_building_gdf['id'] = joined_building_gdf.index
 

voxcity/exporter/__init__.py

@@ -1,4 +1,5 @@
 from .envimet import *
 from .magicavoxel import *
 from .obj import *
-from .cityles import *
+from .cityles import *
+from .netcdf import *

voxcity/exporter/netcdf.py

@@ -0,0 +1,211 @@
+"""
+NetCDF export utilities for VoxCity.
+
+This module provides functions to convert a 3D voxel grid produced by
+`voxcity.generator.get_voxcity` into a NetCDF file for portable storage
+and downstream analysis.
+
+The voxel values follow VoxCity conventions (see generator.create_3d_voxel):
+- -3: built structures (buildings)
+- -2: vegetation canopy
+- -1: subsurface/underground
+- >= 1: ground-surface land cover code (offset by +1 from source classes)
+
+Notes
+-----
+- This writer prefers xarray for NetCDF export. If xarray is not installed,
+  a clear error is raised with installation hints.
+- Coordinates are stored as index-based distances in meters from the grid
+  origin along the y, x, and z axes. Geographic metadata such as the
+  `rectangle_vertices` and `meshsize_m` are stored as global attributes to
+  avoid making assumptions about map projection or geodesic conversions.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Mapping, MutableMapping, Optional, Sequence, Tuple
+import json
+
+import numpy as np
+
+try:  # xarray is the preferred backend for NetCDF writing
+    import xarray as xr  # type: ignore
+    XR_AVAILABLE = True
+except Exception:  # pragma: no cover - optional dependency
+    XR_AVAILABLE = False
+
+__all__ = [
+    "voxel_to_xarray_dataset",
+    "save_voxel_netcdf",
+]
+
+
+def _ensure_parent_dir(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def voxel_to_xarray_dataset(
+    voxcity_grid: np.ndarray,
+    voxel_size_m: float,
+    rectangle_vertices: Optional[Sequence[Tuple[float, float]]] = None,
+    extra_attrs: Optional[Mapping[str, Any]] = None,
+) -> "xr.Dataset":
+    """Create an xarray Dataset from a VoxCity voxel grid.
+
+    Parameters
+    ----------
+    voxcity_grid
+        3D numpy array with shape (rows, cols, levels) as returned by
+        `get_voxcity` (first element of the returned tuple).
+    voxel_size_m
+        Voxel size (mesh size) in meters.
+    rectangle_vertices
+        Optional polygon vertices defining the area of interest in
+        longitude/latitude pairs, typically the same list passed to
+        `get_voxcity`.
+    extra_attrs
+        Optional mapping of additional global attributes to store in the
+        dataset.
+
+    Returns
+    -------
+    xr.Dataset
+        Dataset containing one DataArray named "voxels" with dims (y, x, z)
+        and coordinate variables in meters from origin.
+    """
+    if not XR_AVAILABLE:  # pragma: no cover - optional dependency
+        raise ImportError(
+            "xarray is required to export NetCDF. Install with: \n"
+            "  pip install xarray netCDF4\n"
+            "or: \n"
+            "  pip install xarray h5netcdf"
+        )
+
+    if voxcity_grid.ndim != 3:
+        raise ValueError(
+            f"voxcity_grid must be 3D (rows, cols, levels); got shape={voxcity_grid.shape}"
+        )
+
+    rows, cols, levels = voxcity_grid.shape
+
+    # Coordinate vectors in meters relative to the grid origin
+    # y increases with row index, x increases with column index
+    y_m = np.arange(rows, dtype=float) * float(voxel_size_m)
+    x_m = np.arange(cols, dtype=float) * float(voxel_size_m)
+    z_m = np.arange(levels, dtype=float) * float(voxel_size_m)
+
+    ds_attrs: MutableMapping[str, Any] = {
+        "title": "VoxCity voxel grid",
+        "institution": "VoxCity",
+        "source": "voxcity.generator.create_3d_voxel",
+        "Conventions": "CF-1.10 (partial)",
+        # NetCDF attributes must be basic types; serialize complex structures as strings
+        "vox_value_meanings": [
+            "-3: building",
+            "-2: vegetation_canopy",
+            "-1: subsurface",
+            ">=1: surface_land_cover_code (offset +1)",
+        ],
+        "meshsize_m": float(voxel_size_m),
+        # Store vertices as JSON string for portability
+        "rectangle_vertices_lonlat_json": (
+            json.dumps([[float(v[0]), float(v[1])] for v in rectangle_vertices])
+            if rectangle_vertices is not None else ""
+        ),
+        "vertical_reference": "z=0 corresponds to min(DEM) as used in voxel construction",
+    }
+    if extra_attrs:
+        ds_attrs.update(dict(extra_attrs))
+
+    da = xr.DataArray(
+        voxcity_grid,
+        dims=("y", "x", "z"),
+        coords={
+            "y": ("y", y_m, {"units": "m", "long_name": "row_distance_from_origin"}),
+            "x": ("x", x_m, {"units": "m", "long_name": "col_distance_from_origin"}),
+            "z": ("z", z_m, {"units": "m", "positive": "up", "long_name": "height_above_vertical_origin"}),
+        },
+        name="voxels",
+        attrs={
+            "units": "category",
+            "description": "VoxCity voxel values; see global attribute 'vox_value_meanings'",
+        },
+    )
+
+    ds = xr.Dataset({"voxels": da}, attrs=ds_attrs)
+    return ds
+
+
+def save_voxel_netcdf(
+    voxcity_grid: np.ndarray,
+    output_path: str | Path,
+    voxel_size_m: float,
+    rectangle_vertices: Optional[Sequence[Tuple[float, float]]] = None,
+    extra_attrs: Optional[Mapping[str, Any]] = None,
+    engine: Optional[str] = None,
+) -> str:
+    """Save a VoxCity voxel grid to a NetCDF file.
+
+    Parameters
+    ----------
+    voxcity_grid
+        3D numpy array (rows, cols, levels) of voxel values.
+    output_path
+        Path to the NetCDF file to be written. Parent directories will be
+        created as needed.
+    voxel_size_m
+        Voxel size in meters.
+    rectangle_vertices
+        Optional list of (lon, lat) pairs defining the area of interest.
+        Stored as dataset metadata only.
+    extra_attrs
+        Optional additional global attributes to embed in the dataset.
+    engine
+        Optional xarray engine, e.g., "netcdf4" or "h5netcdf". If not provided,
+        xarray will choose a default; on failure we retry alternate engines.
+
+    Returns
+    -------
+    str
+        The string path to the written NetCDF file.
+    """
+    if not XR_AVAILABLE:  # pragma: no cover - optional dependency
+        raise ImportError(
+            "xarray is required to export NetCDF. Install with: \n"
+            "  pip install xarray netCDF4\n"
+            "or: \n"
+            "  pip install xarray h5netcdf"
+        )
+
+    path = Path(output_path)
+    _ensure_parent_dir(path)
+
+    ds = voxel_to_xarray_dataset(
+        voxcity_grid=voxcity_grid,
+        voxel_size_m=voxel_size_m,
+        rectangle_vertices=rectangle_vertices,
+        extra_attrs=extra_attrs,
+    )
+
+    # Attempt to save with the requested or default engine; on failure, try a fallback
+    tried_engines = []
+    try:
+        ds.to_netcdf(path, engine=engine)  # type: ignore[call-arg]
+    except Exception as e_first:  # pragma: no cover - I/O backend dependent
+        tried_engines.append(engine or "default")
+        for fallback in ("netcdf4", "h5netcdf"):
+            try:
+                ds.to_netcdf(path, engine=fallback)  # type: ignore[call-arg]
+                break
+            except Exception:
+                tried_engines.append(fallback)
+        else:
+            raise RuntimeError(
+                f"Failed to write NetCDF using engines: {tried_engines}. "
+                f"Original error: {e_first}"
+            )
+
+    return str(path)
+
+