voxcity.exporter.netcdf

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.

Classes

NetCDFExporter

Exporter adapter to write a VoxCity voxel grid to NetCDF.

Functions

voxel_to_xarray_dataset(→ xarray.Dataset)

Create an xarray Dataset from a VoxCity voxel grid.

save_voxel_netcdf(→ str)

Save a VoxCity voxel grid to a NetCDF file.

Module Contents

voxcity.exporter.netcdf.voxel_to_xarray_dataset(voxcity_grid: numpy.ndarray, voxel_size_m: float, rectangle_vertices: Sequence[Tuple[float, float]] | None = None, extra_attrs: Mapping[str, Any] | None = None) → xarray.Dataset[source]

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:

Dataset containing one DataArray named “voxels” with dims (y, x, z) and coordinate variables in meters from origin.

Return type:

xr.Dataset

voxcity.exporter.netcdf.save_voxel_netcdf(voxcity_grid: numpy.ndarray, output_path: str | pathlib.Path, voxel_size_m: float, rectangle_vertices: Sequence[Tuple[float, float]] | None = None, extra_attrs: Mapping[str, Any] | None = None, engine: str | None = None) → str[source]

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:

The string path to the written NetCDF file.

Return type:

str