voxcity.generator.api
=====================

.. py:module:: voxcity.generator.api


Functions
---------

.. autoapisummary::

   voxcity.generator.api.auto_select_data_sources
   voxcity.generator.api.get_voxcity
   voxcity.generator.api.get_voxcity_CityGML


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

.. py:function:: auto_select_data_sources(rectangle_vertices)

   Automatically choose data sources for buildings, land cover, canopy height, and DEM
   based on the target area's location.

   Rules (heuristic, partially inferred from latest availability):
   - Buildings (base): 'OpenStreetMap'.
   - Buildings (complementary):
       * USA, Europe, Australia -> 'Microsoft Building Footprints'
       * England -> 'England 1m DSM - DTM' (height from DSM-DTM)
       * Netherlands -> 'Netherlands 0.5m DSM - DTM' (height from DSM-DTM)
       * Africa, South Asia, SE Asia, Latin America & Caribbean -> 'Open Building 2.5D Temporal'
       * Otherwise -> 'None'
   - Land cover: USA -> 'Urbanwatch'; Japan -> 'OpenEarthMapJapan'; otherwise 'OpenStreetMap'.
     (If OSM is insufficient, consider 'ESA WorldCover' manually.)
   - Canopy height: 'High Resolution 1m Global Canopy Height Maps'.
   - DEM: High-resolution where available (USA, England, Australia, France, Netherlands), else 'FABDEM'.

   Returns a dict with keys: building_source, building_complementary_source,
   land_cover_source, canopy_height_source, dem_source.


.. py:function:: get_voxcity(rectangle_vertices, meshsize, building_source=None, land_cover_source=None, canopy_height_source=None, dem_source=None, building_complementary_source=None, building_gdf=None, terrain_gdf=None, **kwargs)

   Generate a VoxCity model with automatic or custom data source selection.

   This function supports both auto mode and custom mode:
   - Auto mode: When sources are not specified (None), they are automatically selected based on location
   - Custom mode: When sources are explicitly specified, they are used as-is
   - Hybrid mode: Specify some sources and auto-select others

   :param rectangle_vertices: List of (lon, lat) tuples defining the area of interest
   :param meshsize: Grid resolution in meters (required)
   :param building_source: Building base source (default: auto-selected based on location)
   :param land_cover_source: Land cover source (default: auto-selected based on location)
   :param canopy_height_source: Canopy height source (default: auto-selected based on location)
   :param dem_source: Digital elevation model source (default: auto-selected based on location)
   :param building_complementary_source: Building complementary source (default: auto-selected based on location)
   :param building_gdf: Optional pre-loaded building GeoDataFrame
   :param terrain_gdf: Optional pre-loaded terrain GeoDataFrame
   :param \*\*kwargs: Additional options for building, land cover, canopy, DEM, visualization, and I/O.
                      Performance options include:
                      - parallel_download: bool, if True downloads run concurrently (default: False)
                      I/O options include:
                      - output_dir: Directory for intermediate/downloaded data (default: "output")
                      - save_path: Full file path to save the VoxCity object (overrides output_dir default)
                      - save_voxcity_data / save_voxctiy_data: bool flag to enable saving (default: True)

   :returns: VoxCity object containing the generated 3D city model


.. py:function:: get_voxcity_CityGML(rectangle_vertices, land_cover_source, canopy_height_source, meshsize, url_citygml=None, citygml_path=None, **kwargs)