voxcity.geoprocessor

Submodules

• voxcity.geoprocessor.conversion
• voxcity.geoprocessor.draw
• voxcity.geoprocessor.heights
• voxcity.geoprocessor.io
• voxcity.geoprocessor.merge_utils
• voxcity.geoprocessor.mesh
• voxcity.geoprocessor.network
• voxcity.geoprocessor.overlap
• voxcity.geoprocessor.raster
• voxcity.geoprocessor.selection
• voxcity.geoprocessor.surface_meta
• voxcity.geoprocessor.utils

Attributes

SELECTABLE_KINDS

Functions

filter_and_convert_gdf_to_geojson(gdf, rectangle_vertices)	Filter a GeoDataFrame by a bounding rectangle and convert to GeoJSON format.
geojson_to_gdf(geojson_data[, id_col])	Convert a list of GeoJSON-like dict features into a GeoDataFrame.
gdf_to_geojson_dicts(gdf[, id_col])	Convert a GeoDataFrame to a list of dicts similar to GeoJSON features.
get_gdf_from_gpkg(gpkg_path, rectangle_vertices)	Read a GeoPackage file and convert it to a GeoDataFrame with consistent CRS.
load_gdf_from_multiple_gz(file_paths)	Load GeoJSON features from multiple gzipped files into a single GeoDataFrame.
extract_building_heights_from_gdf(→ geopandas.GeoDataFrame)	Extract building heights from one GeoDataFrame and apply them to another based on spatial overlap.
extract_building_heights_from_geotiff(geotiff_path, gdf)	Extract building heights from a GeoTIFF raster for building footprints in a GeoDataFrame.
complement_building_heights_from_gdf(gdf_0, gdf_1[, ...])	Vectorized approach with GeoPandas to compute weighted heights and add non-intersecting buildings.
filter_buildings(geojson_data, plotting_box)	Filter building features that intersect with a given bounding box.
find_building_containing_point(building_gdf, target_point)	Find building IDs that contain a given point in their footprint.
get_buildings_in_drawn_polygon(building_gdf, ...[, ...])	Find buildings that intersect with or are contained within user-drawn polygons.
process_building_footprints_by_overlap(filtered_gdf[, ...])	Merge overlapping buildings based on area overlap ratio, assigning the ID of the larger building
merge_gdfs_with_id_conflict_resolution(gdf_1, gdf_2[, ...])	Merge two GeoDataFrames while resolving ID conflicts by modifying IDs in the second GeoDataFrame.
attach_surface_face_meta(→ Any)	Attach surface face metadata to a mesh in-place.
compute_face_areas(→ numpy.ndarray)	Return the area of each triangular face of mesh as a float32 array.
surface_zone_mask(→ numpy.ndarray)	Return a boolean mask of faces selected by the given selectors.
classify_surface_faces(→ list[dict])	Classify each face of a mesh and return metadata dicts for each face.
make_surface_face_key(→ str)	Create a unique identifier for a surface face.
classify_surface_kind(→ str)	Classify surface kind based on normal vector.
wall_orientation(→ Optional[str])	Determine wall orientation (N/E/S/W) from normal vector.

Package Contents

voxcity.geoprocessor.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.

Parameters:

• gdf (GeoDataFrame) – Input GeoDataFrame containing building data Must have ‘geometry’ and ‘height’ columns Any CRS is accepted, will be converted to WGS84 if needed

• rectangle_vertices (list) – 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)

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”

Return type:

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

voxcity.geoprocessor.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.

voxcity.geoprocessor.gdf_to_geojson_dicts(gdf, id_col='id')

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

voxcity.geoprocessor.get_gdf_from_gpkg(gpkg_path, rectangle_vertices)

Read a GeoPackage file and convert it to a GeoDataFrame with consistent CRS.

Note: rectangle_vertices is currently unused but kept for signature compatibility.

voxcity.geoprocessor.load_gdf_from_multiple_gz(file_paths)

Load GeoJSON features from multiple gzipped files into a single GeoDataFrame. Each line in each file must be a single GeoJSON Feature.

voxcity.geoprocessor.extract_building_heights_from_gdf(gdf_0: geopandas.GeoDataFrame, gdf_1: geopandas.GeoDataFrame) → geopandas.GeoDataFrame

Extract building heights from one GeoDataFrame and apply them to another based on spatial overlap.

voxcity.geoprocessor.extract_building_heights_from_geotiff(geotiff_path, gdf)

Extract building heights from a GeoTIFF raster for building footprints in a GeoDataFrame.

voxcity.geoprocessor.complement_building_heights_from_gdf(gdf_0, gdf_1, primary_id='id', ref_id='id')

Vectorized approach with GeoPandas to compute weighted heights and add non-intersecting buildings. Returns a single combined GeoDataFrame.

voxcity.geoprocessor.filter_buildings(geojson_data, plotting_box)

Filter building features that intersect with a given bounding box.

voxcity.geoprocessor.find_building_containing_point(building_gdf, target_point)

Find building IDs that contain a given point in their footprint.

voxcity.geoprocessor.get_buildings_in_drawn_polygon(building_gdf, drawn_polygons, operation='within')

Find buildings that intersect with or are contained within user-drawn polygons.

voxcity.geoprocessor.process_building_footprints_by_overlap(filtered_gdf, overlap_threshold=0.5)

Merge overlapping buildings based on area overlap ratio, assigning the ID of the larger building to smaller overlapping ones.

voxcity.geoprocessor.merge_gdfs_with_id_conflict_resolution(gdf_1, gdf_2, id_columns=['id', 'building_id'])

Merge two GeoDataFrames while resolving ID conflicts by modifying IDs in the second GeoDataFrame.

voxcity.geoprocessor.attach_surface_face_meta(mesh: Any, reference_mesh: Any = None) → Any

Attach surface face metadata to a mesh in-place.

Idempotent — safe to call multiple times. If reference_mesh is provided and has matching face topology, copy its keys directly.

Stores mesh.metadata[“surface_face_meta”] as list of dicts and version 1.

voxcity.geoprocessor.compute_face_areas(mesh: Any) → numpy.ndarray

Return the area of each triangular face of mesh as a float32 array.

Assumes triangular faces (mesh.faces shape (n_faces, 3)). Voxcity’s create_voxel_mesh produces triangulated output, so this fits the existing pipeline. If a future mesh source produces quads, triangulate first.

voxcity.geoprocessor.surface_zone_mask(face_meta: Sequence[Any], selectors: Sequence[Any]) → numpy.ndarray

Return a boolean mask of faces selected by the given selectors.

Accepts both dict and object selectors, handles both snake_case and camelCase keys. Skips selectors with unknown/missing building_id gracefully.

voxcity.geoprocessor.classify_surface_faces(mesh: Any) → list[dict]

Classify each face of a mesh and return metadata dicts for each face.

Returns a list of dicts with keys: face_key, building_id, surface_kind, orientation.

voxcity.geoprocessor.make_surface_face_key(building_id: int, centroid: Sequence[float], normal: Sequence[float], face_index: int) → str

Create a unique identifier for a surface face.

voxcity.geoprocessor.classify_surface_kind(normal: Sequence[float]) → str

Classify surface kind based on normal vector.

voxcity.geoprocessor.wall_orientation(normal: Sequence[float]) → str | None

Determine wall orientation (N/E/S/W) from normal vector.

voxcity.geoprocessor.SELECTABLE_KINDS