voxcity.downloader.gba
======================

.. py:module:: voxcity.downloader.gba

.. autoapi-nested-parse::

   Downloader for Global Building Atlas (GBA) LOD1 polygons.

   This module downloads GeoParquet tiles from the Global Building Atlas (GBA)
   hosted at data.source.coop, selects tiles intersecting a user-specified
   rectangle, loads them into a GeoDataFrame, and filters features to the
   rectangle extent.

   Tile scheme:
   - Global 5x5-degree tiles named like: e010_n50_e015_n45.parquet
     - longitudes: e/w with 3-digit zero padding (e.g., e010, w060)
     - latitudes: n/s with 2-digit zero padding (e.g., n50, s25)
     - filename order: west_lon, north_lat, east_lon, south_lat

   Usage:
       gdf = load_gdf_from_gba(rectangle_vertices=[(lon1, lat1), (lon2, lat2), ...])

   Notes:
   - Output CRS is EPSG:4326.
   - Requires pyarrow or fastparquet for parquet reading via GeoPandas.



Functions
---------

.. autoapisummary::

   voxcity.downloader.gba.load_gdf_from_gba


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

.. py:function:: load_gdf_from_gba(rectangle_vertices: Sequence[Tuple[float, float]], base_url: str = 'https://data.source.coop/tge-labs/globalbuildingatlas-lod1', download_dir: Optional[str] = None, clip_to_rectangle: bool = False) -> Optional[geopandas.GeoDataFrame]

   Download GBA tiles intersecting a rectangle and return combined GeoDataFrame.

   :param rectangle_vertices: Sequence of (lon, lat) defining the area of interest.
   :param base_url: Base URL hosting GBA parquet tiles.
   :param download_dir: Optional directory to store downloaded tiles. If None, a
                        temporary directory is used and cleaned up by the OS later.
   :param clip_to_rectangle: If True, geometries are clipped to rectangle extent.

   :returns: 4326 geometry and an 'id' column, or None if no data.
   :rtype: GeoDataFrame with EPSG