voxcity.exporter.envimet
========================

.. py:module:: voxcity.exporter.envimet

.. autoapi-nested-parse::

   ENVI-met model file exporter module.

   This module provides functionality to export voxel city data to ENVI-met INX format.
   ENVI-met is a three-dimensional microclimate model designed to simulate surface-plant-air
   interactions in urban environments.

   Key Features:
       - Converts voxel grids to ENVI-met compatible format
       - Handles building heights, vegetation, materials, and terrain
       - Supports telescoping grid for vertical mesh refinement
       - Generates complete INX files with all required parameters
       - Creates plant database (EDB) files for 3D vegetation

   Main Functions:
       - prepare_grids: Processes input grids for ENVI-met format
       - create_xml_content: Generates INX file XML content
       - export_inx: Main function to export model to INX format
       - generate_edb_file: Creates plant database file
       - array_to_string: Helper functions for grid formatting

   Dependencies:
       - numpy: For array operations
       - datetime: For timestamp generation



Classes
-------

.. toctree::
   :hidden:

   /autoapi/voxcity/exporter/envimet/EnvimetExporter

.. autoapisummary::

   voxcity.exporter.envimet.EnvimetExporter


Functions
---------

.. autoapisummary::

   voxcity.exporter.envimet.export_inx
   voxcity.exporter.envimet.generate_edb_file
   voxcity.exporter.envimet.generate_lad_profile


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

.. py:function:: export_inx(city: voxcity.models.VoxCity, output_directory: str, file_basename: str = 'voxcity', land_cover_source: str | None = None, **kwargs)

   Export model data to ENVI-met INX file format.

   This is the main function for exporting voxel city data to ENVI-met format.
   It coordinates the entire export process from grid preparation to file saving.

   :param city: VoxCity instance to export
   :type city: VoxCity
   :param output_directory: Directory to save output
   :type output_directory: str
   :param file_basename: Base filename (without extension)
   :type file_basename: str
   :param land_cover_source: Optional override for land cover source; defaults to city.extras
   :type land_cover_source: str | None
   :param \*\*kwargs: Additional keyword arguments:
                      - envimet_mapping (dict): Custom mapping from land cover class indices
                        (1-based) to ENVI-met IDs. Each value is a dict with optional 'veg'
                        (simple plant ID) and/or 'mat' (soil profile ID) keys.
                        Tree vegetation (key 5 'veg') is ignored.
                        Example: ``{2: {'veg': '0200H1'}, 12: {'mat': '0200AR'}}``
                      - rooftop_vegetation (bool): If True, keep 1D vegetation (grass, shrubs)
                        on building cells (e.g. green roofs). Default False (remove them).
                      - Other kwargs are passed to create_xml_content().

   .. rubric:: Notes

   - Creates output directory if it doesn't exist
   - Handles grid preparation and transformation
   - Generates complete INX file with all required data
   - Uses standardized file naming convention


.. py:function:: generate_edb_file(**kwargs)

   Generate ENVI-met database file for 3D plants.

   Creates a plant database file (EDB) containing definitions for trees of
   different heights with customizable leaf area density profiles.

   :param \*\*kwargs: Keyword arguments:
                      - lad (float): Leaf area density in m²/m³ (default 1.0)
                      - trunk_height_ratio (float): Ratio of trunk height to total height
                        (default 11.76/19.98)
                      - output_dir (str): Directory to save the EDB file (default: current directory)

   .. rubric:: Notes

   - Generates plants for heights from 1-50m
   - Uses standardized plant IDs in format 'HxxW01'
   - Includes physical properties like wood density
   - Sets seasonal variation profiles
   - Creates complete ENVI-met plant database format


.. py:function:: generate_lad_profile(height, trunk_height_ratio, lad='1.00000')

   Generate leaf area density profile for a plant.

   Creates a vertical profile of leaf area density (LAD) values for ENVI-met
   plant definitions, accounting for trunk space and crown distribution.

   :param height: Total height of plant in meters
   :type height: int
   :param trunk_height_ratio: Ratio of trunk height to total height
   :type trunk_height_ratio: float
   :param lad: Leaf area density value as string (default '1.00000')
   :type lad: str

   :returns: LAD profile data formatted for ENVI-met EDB file
   :rtype: str

   .. rubric:: Notes

   - LAD values start above trunk height
   - Uses 5-space indentation for ENVI-met format
   - Profile follows format: "z-level,x,y,LAD"