voxcity.downloader.eubucco
==========================

.. py:module:: voxcity.downloader.eubucco

.. autoapi-nested-parse::

   Module for downloading and processing building data from the EUBUCCO dataset.

   This module provides functionality to download, extract, filter and convert building footprint data
   from the EUBUCCO (European Building Characteristics) dataset. It handles downloading zipped GeoPackage
   files, extracting building geometries and heights, and converting them to GeoJSON format.

   The module supports:
   - Downloading building data for specific European countries
   - Extracting and processing GeoPackage files
   - Converting coordinates between different coordinate reference systems (CRS)
   - Filtering buildings by geographic area
   - Handling building height data and confidence values
   - Converting to standardized GeoJSON format

   Key functions:
   - filter_and_convert_gdf_to_geojson_eubucco(): Filters and converts GeoPackage data to GeoJSON
   - download_extract_open_gpkg_from_eubucco(): Downloads and extracts EUBUCCO data
   - get_gdf_from_eubucco(): Gets GeoDataFrame from EUBUCCO for a specific area
   - load_gdf_from_eubucco(): Main interface for loading EUBUCCO building data

   Dependencies:
   - shapely: For geometric operations
   - fiona: For reading GeoPackage files
   - geopandas: For GeoDataFrame operations
   - requests: For downloading data



Functions
---------

.. autoapisummary::

   voxcity.downloader.eubucco.get_gdf_from_eubucco
   voxcity.downloader.eubucco.load_gdf_from_eubucco


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

.. py:function:: get_gdf_from_eubucco(rectangle_vertices, country_links, output_dir, file_name)

   Downloads, extracts, filters, and converts GeoPackage data to GeoJSON based on the rectangle vertices.

   This function:
   1. Determines the target country based on input coordinates
   2. Downloads and extracts EUBUCCO data for that country
   3. Reads the GeoPackage into a GeoDataFrame
   4. Ensures correct coordinate reference system
   5. Assigns unique IDs to buildings

   Parameters:
   - rectangle_vertices (list of tuples): List of (longitude, latitude) tuples defining the area of interest
   - country_links (dict): Dictionary mapping country names to their respective GeoPackage URLs
   - output_dir (str): Directory to save downloaded and processed files
   - file_name (str): Name for the output GeoJSON file

   Returns:
   - geopandas.GeoDataFrame: DataFrame containing building geometries and properties
       or None if the target area has no EUBUCCO data

   Notes:
   - Automatically transforms coordinates to WGS84 (EPSG:4326) if needed
   - Assigns sequential IDs to buildings starting from 0
   - Logs errors if target area is not covered by EUBUCCO


.. py:function:: load_gdf_from_eubucco(rectangle_vertices, output_dir)

   Downloads EUBUCCO data and loads it as GeoJSON.

   This function serves as the main interface for loading EUBUCCO building data.
   It handles the complete workflow from downloading to processing the data.

   Parameters:
   - rectangle_vertices (list of tuples): List of (longitude, latitude) tuples defining the area
       The first vertex is used to determine which country's data to download
   - output_dir (str): Directory to save intermediate and output files
       Creates a subdirectory 'EUBUCCO_raw' for raw downloaded data

   Returns:
   - geopandas.GeoDataFrame: DataFrame containing:
       - geometry: Building footprint polygons
       - height: Building heights in meters
       - id: Unique identifier for each building
       or None if the target area has no EUBUCCO data

   Notes:
   - Output is always in WGS84 (EPSG:4326) coordinate system
   - Building heights are in meters
   - Buildings without height data are assigned a height of -1.0
   - The function automatically determines the appropriate country dataset