voxcity.exporter.netcdf
=======================

.. py:module:: voxcity.exporter.netcdf

.. autoapi-nested-parse::

   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)

   .. rubric:: 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
-------

.. toctree::
   :hidden:

   /autoapi/voxcity/exporter/netcdf/NetCDFExporter

.. autoapisummary::

   voxcity.exporter.netcdf.NetCDFExporter


Functions
---------

.. autoapisummary::

   voxcity.exporter.netcdf.voxel_to_xarray_dataset
   voxcity.exporter.netcdf.save_voxel_netcdf


Module Contents
---------------

.. py:function:: voxel_to_xarray_dataset(voxcity_grid: numpy.ndarray, voxel_size_m: float, rectangle_vertices: Optional[Sequence[Tuple[float, float]]] = None, extra_attrs: Optional[Mapping[str, Any]] = None) -> xarray.Dataset

   Create an xarray Dataset from a VoxCity voxel grid.

   :param voxcity_grid: 3D numpy array with shape (rows, cols, levels) as returned by
                        `get_voxcity` (first element of the returned tuple).
   :param voxel_size_m: Voxel size (mesh size) in meters.
   :param rectangle_vertices: Optional polygon vertices defining the area of interest in
                              longitude/latitude pairs, typically the same list passed to
                              `get_voxcity`.
   :param 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.
   :rtype: xr.Dataset


.. py:function:: save_voxel_netcdf(voxcity_grid: numpy.ndarray, output_path: str | pathlib.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.

   :param voxcity_grid: 3D numpy array (rows, cols, levels) of voxel values.
   :param output_path: Path to the NetCDF file to be written. Parent directories will be
                       created as needed.
   :param voxel_size_m: Voxel size in meters.
   :param rectangle_vertices: Optional list of (lon, lat) pairs defining the area of interest.
                              Stored as dataset metadata only.
   :param extra_attrs: Optional additional global attributes to embed in the dataset.
   :param 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.
   :rtype: str