voxcity.geoprocessor.conversion
===============================

.. py:module:: voxcity.geoprocessor.conversion

.. autoapi-nested-parse::

   Conversion utilities between GeoJSON-like features and GeoPandas GeoDataFrames,
   plus helpers to filter and transform geometries for export.



Functions
---------

.. autoapisummary::

   voxcity.geoprocessor.conversion.filter_and_convert_gdf_to_geojson
   voxcity.geoprocessor.conversion.geojson_to_gdf
   voxcity.geoprocessor.conversion.gdf_to_geojson_dicts


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

.. py:function:: filter_and_convert_gdf_to_geojson(gdf, rectangle_vertices)

   Filter a GeoDataFrame by a bounding rectangle and convert to GeoJSON format.

   This function performs spatial filtering on a GeoDataFrame using a bounding rectangle,
   and converts the filtered data to GeoJSON format. It handles both Polygon and MultiPolygon
   geometries, splitting MultiPolygons into separate Polygon features.

   :param gdf: Input GeoDataFrame containing building data
               Must have 'geometry' and 'height' columns
               Any CRS is accepted, will be converted to WGS84 if needed
   :type gdf: GeoDataFrame
   :param rectangle_vertices: List of (lon, lat) tuples defining the bounding rectangle
                              Must be in WGS84 (EPSG:4326) coordinate system
                              Must form a valid rectangle (4 vertices, clockwise or counterclockwise)
   :type rectangle_vertices: list

   :returns:

             List of GeoJSON features within the bounding rectangle
                 Each feature contains:
                 - geometry: Polygon coordinates in WGS84
                 - properties: Dictionary with 'height', 'confidence', and 'id'
                 - type: Always "Feature"
   :rtype: list

   Memory Optimization:
       - Uses spatial indexing for efficient filtering
       - Downcasts numeric columns to save memory
       - Cleans up intermediate data structures
       - Splits MultiPolygons into separate features


.. py:function:: geojson_to_gdf(geojson_data, id_col='id')

   Convert a list of GeoJSON-like dict features into a GeoDataFrame.

   This function takes a list of GeoJSON feature dictionaries (Fiona-like format)
   and converts them into a GeoDataFrame, handling geometry conversion and property
   extraction. It ensures each feature has a unique identifier.


.. py:function:: gdf_to_geojson_dicts(gdf, id_col='id')

   Convert a GeoDataFrame to a list of dicts similar to GeoJSON features.