voxcity.exporter.envimet

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

EnvimetExporter

Exporter adapter to write a VoxCity model to ENVI-met INX format.

Functions

export_inx(city, output_directory[, file_basename, ...])

Export model data to ENVI-met INX file format.

generate_edb_file(**kwargs)

Generate ENVI-met database file for 3D plants.

generate_lad_profile(height, trunk_height_ratio[, lad])

Generate leaf area density profile for a plant.

Module Contents

voxcity.exporter.envimet.export_inx(city: voxcity.models.VoxCity, output_directory: str, file_basename: str = 'voxcity', land_cover_source: str | None = None, **kwargs)[source]

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.

Parameters:

  • city (VoxCity) – VoxCity instance to export

  • output_directory (str) – Directory to save output

  • file_basename (str) – Base filename (without extension)

  • land_cover_source (str | None) – Optional override for land cover source; defaults to city.extras

  • **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().

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

voxcity.exporter.envimet.generate_edb_file(**kwargs)[source]

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.

Parameters:

**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)

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

voxcity.exporter.envimet.generate_lad_profile(height, trunk_height_ratio, lad='1.00000')[source]

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.

Parameters:

  • height (int) – Total height of plant in meters

  • trunk_height_ratio (float) – Ratio of trunk height to total height

  • lad (str) – Leaf area density value as string (default ‘1.00000’)

Returns:

LAD profile data formatted for ENVI-met EDB file

Return type:

str

Notes

  • LAD values start above trunk height

  • Uses 5-space indentation for ENVI-met format

  • Profile follows format: “z-level,x,y,LAD”