voxcity.simulator_gpu.visibility.integration¶

VoxCity Integration Module for simulator_gpu.visibility

This module provides utilities for loading VoxCity models and using them with the GPU-accelerated visibility analysis tools.

This module emulates the voxcity.simulator.visibility API using Taichi GPU acceleration.

VoxCity models contain: - 3D voxel grids with building, tree, and ground information - Land cover classification codes - Building heights and IDs - Tree canopy data

API Compatibility:: The functions in this module match the voxcity.simulator.visibility API: - get_view_index() - same signature as voxcity.simulator.visibility.get_view_index - get_sky_view_factor_map() - same signature as voxcity.simulator.visibility.get_sky_view_factor_map - get_surface_view_factor() - same signature as voxcity.simulator.visibility.get_surface_view_factor - get_landmark_visibility_map() - same signature as voxcity.simulator.visibility.get_landmark_visibility_map - get_surface_landmark_visibility() - same signature as voxcity.simulator.visibility.get_surface_landmark_visibility - mark_building_by_id() - same as voxcity.simulator.visibility.mark_building_by_id

Attributes¶

`VOXCITY_GROUND_CODE`
`VOXCITY_TREE_CODE`
`VOXCITY_BUILDING_CODE`
`GREEN_VIEW_CODES`

Functions¶

`clear_visibility_cache`()	Clear the cached Domain and workspace fields.
`reset_visibility_taichi_cache`()	Reset Taichi runtime and clear all visibility caches.
`create_domain_from_voxcity`(...)	Create a Domain object from a VoxCity model.
`get_view_index_gpu`(→ numpy.ndarray)	GPU-accelerated View Index calculation for VoxCity.
`get_view_index`(voxcity[, mode, hit_values, ...])	GPU-accelerated View Index calculation for VoxCity.
`get_sky_view_factor_map`(voxcity[, show_plot])	GPU-accelerated Sky View Factor calculation for VoxCity.
`get_surface_view_factor`(voxcity[, mode])	GPU-accelerated Surface View Factor calculation for VoxCity.
`get_landmark_visibility_map`(voxcity[, building_gdf])	GPU-accelerated Landmark Visibility Map calculation for VoxCity.
`get_surface_landmark_visibility`(voxcity[, building_gdf])	GPU-accelerated Surface Landmark Visibility calculation for VoxCity.
`get_sky_view_factor_map_gpu`(→ numpy.ndarray)	GPU-accelerated Sky View Factor calculation for VoxCity.
`get_landmark_visibility_map_gpu`(→ Tuple[numpy.ndarray, ...)	GPU-accelerated Landmark Visibility calculation for VoxCity.

Module Contents¶

voxcity.simulator_gpu.visibility.integration.VOXCITY_GROUND_CODE = -1¶

voxcity.simulator_gpu.visibility.integration.VOXCITY_TREE_CODE = -2¶

voxcity.simulator_gpu.visibility.integration.VOXCITY_BUILDING_CODE = -3¶

voxcity.simulator_gpu.visibility.integration.GREEN_VIEW_CODES¶

voxcity.simulator_gpu.visibility.integration.clear_visibility_cache()¶: Clear the cached Domain and workspace fields.

voxcity.simulator_gpu.visibility.integration.reset_visibility_taichi_cache()¶

Reset Taichi runtime and clear all visibility caches.

Call this function when you encounter: - CUDA_ERROR_OUT_OF_MEMORY errors - TaichiRuntimeError: FieldsBuilder finalized

After calling this, the next visibility calculation will create fresh Taichi fields.

voxcity.simulator_gpu.visibility.integration.create_domain_from_voxcity(voxcity) → voxcity.simulator_gpu.domain.Domain¶

Create a Domain object from a VoxCity model.

Parameters:: voxcity – VoxCity object with voxels attribute
Returns:: Domain object configured for view analysis

voxcity.simulator_gpu.visibility.integration.get_view_index_gpu(voxcity, mode: str = None, hit_values: Tuple[int, Ellipsis] = None, inclusion_mode: bool = True, view_point_height: float = 1.5, n_azimuth: int = 120, n_elevation: int = 20, elevation_min_degrees: float = -30.0, elevation_max_degrees: float = 30.0, ray_sampling: str = 'grid', n_rays: int = None, tree_k: float = 0.5, tree_lad: float = 1.0, show_plot: bool = False, computation_mask: numpy.ndarray = None, **kwargs) → numpy.ndarray¶

GPU-accelerated View Index calculation for VoxCity.

This function emulates voxcity.simulator.visibility.view.get_view_index using Taichi GPU acceleration.

Parameters:

voxcity – VoxCity object
mode – Predefined mode (‘green’, ‘sky’, or None for custom)
hit_values – Target voxel values to count as visible
inclusion_mode – If True, count hits on targets; if False, count non-blocked rays
view_point_height – Observer height above ground (meters)
n_azimuth – Number of azimuthal divisions
n_elevation – Number of elevation divisions
elevation_min_degrees – Minimum viewing angle
elevation_max_degrees – Maximum viewing angle
ray_sampling – ‘grid’ or ‘fibonacci’
n_rays – Total rays for fibonacci sampling
tree_k – Tree extinction coefficient
tree_lad – Leaf area density
show_plot – Whether to display a matplotlib plot
**kwargs – Additional parameters

Returns:

2D array of view index values

voxcity.simulator_gpu.visibility.integration.get_view_index(voxcity, mode=None, hit_values=None, inclusion_mode=True, fast_path=True, **kwargs)¶

GPU-accelerated View Index calculation for VoxCity.

This function matches the signature of voxcity.simulator.visibility.get_view_index using Taichi GPU acceleration.

Parameters:

voxcity – VoxCity object
mode – Predefined mode (‘green’, ‘sky’, or None for custom)
hit_values – Target voxel values to count as visible
inclusion_mode – If True, count hits on targets; if False, count non-blocked rays
**kwargs – Additional parameters including: - view_point_height (float): Observer height above ground (default: 1.5) - N_azimuth (int): Number of azimuthal divisions (default: 120) - N_elevation (int): Number of elevation divisions (default: 20) - elevation_min_degrees (float): Minimum viewing angle (default: -30) - elevation_max_degrees (float): Maximum viewing angle (default: 30) - ray_sampling (str): ‘grid’ or ‘fibonacci’ (default: ‘grid’) - N_rays (int): Total rays for fibonacci sampling - tree_k (float): Tree extinction coefficient (default: 0.5) - tree_lad (float): Leaf area density (default: 1.0) - colormap (str): Matplotlib colormap name (default: ‘viridis’) - vmin, vmax (float): Colormap limits (default: 0.0, 1.0) - obj_export (bool): Whether to export OBJ file (default: False)

Returns:

2D array of view index values

voxcity.simulator_gpu.visibility.integration.get_sky_view_factor_map(voxcity, show_plot=False, **kwargs)¶

GPU-accelerated Sky View Factor calculation for VoxCity.

This function matches the signature of voxcity.simulator.visibility.get_sky_view_factor_map using Taichi GPU acceleration.

Parameters:

voxcity – VoxCity object
show_plot – Whether to display a matplotlib plot
**kwargs – Additional parameters including: - view_point_height (float): Observer height above ground (default: 1.5) - N_azimuth (int): Number of azimuthal divisions (default: 120) - N_elevation (int): Number of elevation divisions (default: 20) - tree_k (float): Tree extinction coefficient (default: 0.6) - tree_lad (float): Leaf area density (default: 1.0) - colormap (str): Matplotlib colormap name (default: ‘BuPu_r’)

Returns:

2D array of SVF values

voxcity.simulator_gpu.visibility.integration.get_surface_view_factor(voxcity, mode=None, **kwargs)¶

GPU-accelerated Surface View Factor calculation for VoxCity.

This function matches the signature of voxcity.simulator.visibility.get_surface_view_factor using Taichi GPU acceleration.

Computes view factors for building surface faces by tracing rays from face centers through the voxel domain.

Parameters:

voxcity – VoxCity object
**kwargs – Additional parameters including: - value_name (str): Name for the metadata field (default: ‘view_factor_values’) - colormap (str): Matplotlib colormap name (default: ‘BuPu_r’) - vmin, vmax (float): Colormap limits (default: 0.0, 1.0) - N_azimuth (int): Number of azimuthal divisions (default: 120) - N_elevation (int): Number of elevation divisions (default: 20) - ray_sampling (str): ‘grid’ or ‘fibonacci’ (default: ‘grid’) - tree_k (float): Tree extinction coefficient (default: 0.6) - tree_lad (float): Leaf area density (default: 1.0) - target_values (tuple): Target voxel values (default: (0,)) - inclusion_mode (bool): Inclusion vs exclusion mode (default: False) - building_class_id (int): Building class ID for mesh extraction (default: -3) - target_selectors (list): Optional surface selectors limiting computed faces - reference_mesh: Optional reference mesh used to reuse surface metadata - progress_report (bool): Show progress (default: False) - obj_export (bool): Export mesh to OBJ (default: False)

Returns:

Trimesh object with view factor values in metadata

voxcity.simulator_gpu.visibility.integration.get_landmark_visibility_map(voxcity, building_gdf=None, **kwargs)¶

GPU-accelerated Landmark Visibility Map calculation for VoxCity.

This function matches the signature of voxcity.simulator.visibility.get_landmark_visibility_map using Taichi GPU acceleration.

Parameters:

voxcity – VoxCity object
building_gdf – GeoDataFrame of buildings (optional, will use voxcity.extras[‘building_gdf’])
**kwargs – Additional parameters including: - view_point_height (float): Observer height above ground (default: 1.5) - colormap (str): Matplotlib colormap name (default: ‘viridis’) - landmark_building_ids (list): List of building IDs to mark as landmarks - landmark_polygon: Polygon to select landmark buildings - tree_k (float): Tree extinction coefficient (default: 0.6) - tree_lad (float): Leaf area density (default: 1.0) - obj_export (bool): Export results to OBJ (default: False)

Returns:

Tuple of (visibility_map, modified_voxel_data)

voxcity.simulator_gpu.visibility.integration.get_surface_landmark_visibility(voxcity, building_gdf=None, **kwargs)¶

GPU-accelerated Surface Landmark Visibility calculation for VoxCity.

This function matches the signature of voxcity.simulator.visibility.get_surface_landmark_visibility using Taichi GPU acceleration.

Computes landmark visibility for building surface faces.

Parameters:

voxcity – VoxCity object
building_gdf – GeoDataFrame of buildings
**kwargs – Additional parameters including: - landmark_building_ids (list): List of building IDs to mark as landmarks - landmark_polygon: Polygon to select landmark buildings - tree_k (float): Tree extinction coefficient (default: 0.6) - tree_lad (float): Leaf area density (default: 1.0) - building_class_id (int): Building class ID (default: -3) - progress_report (bool): Show progress (default: False) - colormap (str): Matplotlib colormap name (default: ‘RdYlGn’) - obj_export (bool): Export mesh to OBJ (default: False)

Returns:

Tuple of (building_mesh with visibility, modified_voxel_data)

voxcity.simulator_gpu.visibility.integration.get_sky_view_factor_map_gpu(voxcity, view_point_height: float = 1.5, n_azimuth: int = 120, n_elevation: int = 20, tree_k: float = 0.6, tree_lad: float = 1.0, show_plot: bool = False, **kwargs) → numpy.ndarray¶

GPU-accelerated Sky View Factor calculation for VoxCity.

Legacy function - use get_sky_view_factor_map() for VoxCity API compatibility.

Parameters:

voxcity – VoxCity object
view_point_height – Observer height above ground (meters)
n_azimuth – Number of azimuthal divisions
n_elevation – Number of elevation divisions
tree_k – Tree extinction coefficient
tree_lad – Leaf area density
show_plot – Whether to display a matplotlib plot
**kwargs – Additional parameters

Returns:

2D array of SVF values

voxcity.simulator_gpu.visibility.integration.get_landmark_visibility_map_gpu(voxcity, building_gdf=None, landmark_building_ids: List[int] = None, view_point_height: float = 1.5, tree_k: float = 0.6, tree_lad: float = 1.0, show_plot: bool = False, **kwargs) → Tuple[numpy.ndarray, numpy.ndarray]¶

GPU-accelerated Landmark Visibility calculation for VoxCity.

Legacy function - use get_landmark_visibility_map() for VoxCity API compatibility.

Parameters:

voxcity – VoxCity object
building_gdf – GeoDataFrame of buildings (optional)
landmark_building_ids – List of building IDs to mark as landmarks
view_point_height – Observer height above ground (meters)
tree_k – Tree extinction coefficient
tree_lad – Leaf area density
show_plot – Whether to display a matplotlib plot
**kwargs – Additional parameters

Returns:

Tuple of (visibility_map, modified_voxel_data)