voxcity.downloader.mbfp
=======================

.. py:module:: voxcity.downloader.mbfp

.. autoapi-nested-parse::

   Module for downloading and processing Microsoft Building Footprints data.

   This module provides functionality to download building footprint data from Microsoft's
   open dataset, which contains building polygons extracted from satellite imagery using
   AI. It handles downloading quadkey-based data files and converting them to GeoJSON format.

   The data is organized using quadkeys, which are hierarchical spatial indexing strings
   that identify tiles on the map at different zoom levels. Each quadkey corresponds to
   a specific geographic area and zoom level.

   Key Features:
   - Downloads building footprint data from Microsoft's global buildings dataset
   - Handles quadkey-based spatial queries
   - Converts compressed data files to GeoJSON format
   - Supports rectangular region queries using vertex coordinates



Functions
---------

.. autoapisummary::

   voxcity.downloader.mbfp.get_mbfp_gdf


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

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

   Download and process building footprint data for a rectangular region.

   This function takes a list of coordinates defining a rectangular region and:
   1. Downloads the necessary building footprint data files covering the region
   2. Loads and combines the GeoJSON data from all relevant files
   3. Processes the data to ensure consistent coordinate ordering
   4. Assigns unique sequential IDs to each building

   :param output_dir: Directory path where downloaded files will be saved
   :type output_dir: str
   :param rectangle_vertices: List of (lon, lat) tuples defining the rectangle corners.
                              The coordinates should define a bounding box of the
                              area of interest.
   :type rectangle_vertices: list

   :returns:

             GeoDataFrame containing building footprints with columns:
                 - geometry: Building polygon geometries
                 - id: Sequential unique identifier for each building
   :rtype: geopandas.GeoDataFrame

   .. note::

      - Files are downloaded only if not already present in the output directory
      - Coordinates in the input vertices should be in (longitude, latitude) order
      - The function handles cases where some vertices might not have available data