cityImage.compute_3d_sight_lines#

cityImage.compute_3d_sight_lines(nodes_gdf, target_buildings_gdf, obstructions_buildings_gdf, simplified_target_buildings, edges_gdf, city_name, distance_along=200, min_observer_target_distance=300, height_relative_to_ground=False, sight_lines_chunk_size=500000, consolidate=False, consolidate_tolerance=0.0, num_workers=20)[source]#

Compute visible 3D sight lines between observer nodes and target buildings.

The workflow samples target points along building roofs, generates candidate observer-target lines, removes lines that are too short, filters 2D obstructions, and checks remaining candidate lines with PyVista ray tracing. Large candidate sets are processed in chunks and written temporarily to GeoPackage files before being merged.

Parameters:

  • nodes_gdf (GeoDataFrame) – Observer nodes. Required columns are geometry, x, y, nodeID, and z.

  • target_buildings_gdf (GeoDataFrame) – Buildings to use as visibility targets. Required columns are buildingID, geometry, height, and optionally base.

  • obstructions_buildings_gdf (GeoDataFrame) – Buildings to use as possible obstructions. Required columns are buildingID, geometry, height, and optionally base.

  • simplified_target_buildings (GeoDataFrame) – Optional simplified target outlines. When provided, detailed target buildings are mapped back to simplified geometries for final sight-line assignment.

  • edges_gdf (GeoDataFrame) – Network edges used only when consolidate=True.

  • city_name (str) – Prefix used for temporary chunk files.

  • distance_along (float) – Sampling distance along target-building roof edges.

  • min_observer_target_distance (float) – Minimum 2D distance allowed between observer and target.

  • height_relative_to_ground (bool, default False) – Whether building heights are already relative to local ground/base height.

  • sight_lines_chunk_size (int) – Maximum number of candidate sight lines processed per chunk.

  • consolidate (bool) – Whether to consolidate observer nodes before sight-line generation.

  • consolidate_tolerance (float) – Spatial tolerance used for node consolidation.

  • num_workers (int) – Number of parallel workers used for obstruction and mesh operations.

Returns:

Visible 3D sight lines. If no visible lines are found, an empty GeoDataFrame with the obstruction CRS is returned.

Return type:

geopandas.GeoDataFrame