voxcity 0.6.17__tar.gz → 0.6.19__tar.gz

{voxcity-0.6.17 → voxcity-0.6.19}/PKG-INFO

@@ -1,8 +1,10 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: voxcity
-Version: 0.6.17
+Version: 0.6.19
 Summary: voxcity is an easy and one-stop tool to output 3d city models for microclimate simulation by integrating multiple geospatial open-data
 License: MIT
+License-File: AUTHORS.rst
+License-File: LICENSE
 Author: Kunihiko Fujiwara
 Author-email: fujiwara.kunihiko@takenaka.co.jp
 Maintainer: Kunihiko Fujiwara
@@ -27,6 +29,7 @@ Requires-Dist: ipyleaflet
 Requires-Dist: joblib
 Requires-Dist: lxml
 Requires-Dist: matplotlib
+Requires-Dist: netCDF4
 Requires-Dist: numba
 Requires-Dist: numpy
 Requires-Dist: osmnx
@@ -51,6 +54,7 @@ Requires-Dist: timezonefinder
 Requires-Dist: tqdm
 Requires-Dist: trimesh
 Requires-Dist: typer
+Requires-Dist: xarray
 Project-URL: bugs, https://github.com/kunifujiwara/voxcity/issues
 Project-URL: changelog, https://github.com/kunifujiwara/voxcity/blob/master/changelog.md
 Project-URL: homepage, https://github.com/kunifujiwara/voxcity
@@ -232,7 +236,7 @@ Generate voxel data grids and corresponding building geoJSON:
 from voxcity.generator import get_voxcity
 
 voxcity_grid, building_height_grid, building_min_height_grid, \
-building_id_grid, canopy_height_grid, land_cover_grid, dem_grid, \
+building_id_grid, canopy_height_grid, canopy_bottom_height_grid, land_cover_grid, dem_grid, \
 building_gdf = get_voxcity(
     rectangle_vertices,
     building_source,

{voxcity-0.6.17 → voxcity-0.6.19}/README.md

@@ -174,7 +174,7 @@ Generate voxel data grids and corresponding building geoJSON:
 from voxcity.generator import get_voxcity
 
 voxcity_grid, building_height_grid, building_min_height_grid, \
-building_id_grid, canopy_height_grid, land_cover_grid, dem_grid, \
+building_id_grid, canopy_height_grid, canopy_bottom_height_grid, land_cover_grid, dem_grid, \
 building_gdf = get_voxcity(
     rectangle_vertices,
     building_source,

{voxcity-0.6.17 → voxcity-0.6.19}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "voxcity"
-version = "0.6.17"
+version = "0.6.19"
 description = "voxcity is an easy and one-stop tool to output 3d city models for microclimate simulation by integrating multiple geospatial open-data"
 readme = "README.md"
 license = "MIT"
@@ -56,6 +56,8 @@ pyvista = "*"
 IPython = "*"
 lxml = "*"
 scikit-learn = "*"
+xarray = "*"
+netCDF4 = "*"
 
 [tool.poetry.group.dev.dependencies]
 coverage = "*"

{voxcity-0.6.17 → voxcity-0.6.19}/src/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-0.6.19/src/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)
+
+