voxcity.simulator_gpu.visibility¶

simulator_gpu.visibility: GPU-accelerated visibility analysis module.

This package emulates voxcity.simulator.visibility using Taichi GPU acceleration.

Features: - View Index calculation (green view, sky view, custom targets) - Sky View Factor calculation - Landmark visibility analysis - Surface view factor computation

API Compatibility:

This module provides GPU-accelerated versions of the voxcity.simulator.visibility API functions. The main functions mirror the original API:

get_view_index() -> GPU version of voxcity.simulator.visibility.get_view_index
get_sky_view_factor_map() -> GPU version of voxcity.simulator.visibility.get_sky_view_factor_map
get_surface_view_factor() -> GPU version of voxcity.simulator.visibility.get_surface_view_factor
get_landmark_visibility_map() -> GPU version of voxcity.simulator.visibility.get_landmark_visibility_map
get_surface_landmark_visibility() -> GPU version of voxcity.simulator.visibility.get_surface_landmark_visibility
mark_building_by_id() -> Same as voxcity.simulator.visibility.mark_building_by_id

Usage:

from simulator_gpu.visibility import get_view_index, get_sky_view_factor_map

vi_map = get_view_index(voxcity, mode=’green’) svf_map = get_sky_view_factor_map(voxcity)

# Or use the class-based API: from simulator_gpu.visibility import ViewCalculator calc = ViewCalculator(domain) view_map = calc.compute_view_index(mode=’green’)

Submodules¶

Attributes¶

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

Classes¶

`ViewCalculator`	GPU-accelerated View Index calculator.
`SurfaceViewFactorCalculator`	GPU-accelerated Surface View Factor calculator.
`LandmarkVisibilityCalculator`	GPU-accelerated Landmark Visibility calculator.
`SurfaceLandmarkVisibilityCalculator`	GPU-accelerated Surface Landmark Visibility calculator.

Functions¶

`compute_view_index_map`(→ numpy.ndarray)	Compute View Index map.
`compute_sky_view_factor_map`(→ numpy.ndarray)	Compute Sky View Factor map.
`compute_landmark_visibility_map`(→ numpy.ndarray)	Compute landmark visibility map.
`compute_landmark_visibility`(→ numpy.ndarray)	VoxCity-compatible landmark visibility on raw voxel data.
`generate_ray_directions_grid`(→ numpy.ndarray)	Generate ray directions using a regular grid sampling.
`generate_ray_directions_fibonacci`(→ numpy.ndarray)	Generate ray directions using Fibonacci spiral sampling.
`rotate_vector_axis_angle`(→ numpy.ndarray)	Rotate a vector around an axis by a specified angle using Rodrigues' rotation formula.
`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_view_index_gpu`(→ numpy.ndarray)	GPU-accelerated View Index 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.
`create_domain_from_voxcity`(...)	Create a Domain object from a VoxCity model.
`mark_building_by_id`(→ numpy.ndarray)	Mark specific buildings in voxel data with a marker value.
`clear_visibility_cache`()	Clear the cached Domain and workspace fields.
`reset_visibility_taichi_cache`()	Reset Taichi runtime and clear all visibility caches.

Package Contents¶

voxcity.simulator_gpu.visibility.compute_view_index_map(domain, voxel_data: numpy.ndarray = None, mode: str = 'green', **kwargs) → numpy.ndarray¶

Compute View Index map.

Parameters:

domain – Domain object
voxel_data – 3D voxel class array
mode – ‘green’, ‘sky’, or custom
**kwargs – Additional parameters for ViewCalculator

Returns:

2D view index map

voxcity.simulator_gpu.visibility.compute_sky_view_factor_map(domain, voxel_data: numpy.ndarray = None, **kwargs) → numpy.ndarray¶

Compute Sky View Factor map.

Parameters:

domain – Domain object
voxel_data – 3D voxel class array
**kwargs – Additional parameters

Returns:

2D SVF map

voxcity.simulator_gpu.visibility.compute_landmark_visibility_map(domain, voxel_data: numpy.ndarray, landmark_value: int = -30, view_height_voxel: int = 0, **kwargs) → numpy.ndarray¶

Compute landmark visibility map.

Parameters:

domain – Domain object
voxel_data – 3D voxel class array with landmarks marked
landmark_value – Voxel value marking landmarks
view_height_voxel – Observer height in voxels
**kwargs – Additional parameters

Returns:

2D visibility map

voxcity.simulator_gpu.visibility.compute_landmark_visibility(voxel_data: numpy.ndarray, target_value: int = -30, view_height_voxel: int = 0, colormap: str = 'viridis') → numpy.ndarray¶

VoxCity-compatible landmark visibility on raw voxel data.

Matches voxcity.simulator.visibility.landmark.compute_landmark_visibility.

Notes

Uses Taichi GPU ray tracing underneath.
Returns a 2D map in uv layout, consistent with voxel_data.

voxcity.simulator_gpu.visibility.generate_ray_directions_grid(n_azimuth: int = 120, n_elevation: int = 20, elevation_min_degrees: float = -30.0, elevation_max_degrees: float = 30.0) → numpy.ndarray¶

Generate ray directions using a regular grid sampling.

Parameters:

n_azimuth – Number of azimuthal divisions
n_elevation – Number of elevation divisions
elevation_min_degrees – Minimum elevation angle in degrees
elevation_max_degrees – Maximum elevation angle in degrees

Returns:

Array of shape (n_azimuth * n_elevation, 3) with unit direction vectors

voxcity.simulator_gpu.visibility.generate_ray_directions_fibonacci(n_rays: int = 2400, elevation_min_degrees: float = -30.0, elevation_max_degrees: float = 30.0) → numpy.ndarray¶

Generate ray directions using Fibonacci spiral sampling.

This provides more uniform coverage of the hemisphere compared to grid sampling.

Parameters:

n_rays – Total number of rays
elevation_min_degrees – Minimum elevation angle in degrees
elevation_max_degrees – Maximum elevation angle in degrees

Returns:

Array of shape (n_rays, 3) with unit direction vectors

voxcity.simulator_gpu.visibility.rotate_vector_axis_angle(vec: numpy.ndarray, axis: numpy.ndarray, angle: float) → numpy.ndarray¶

Rotate a vector around an axis by a specified angle using Rodrigues’ rotation formula.

This is a CPU implementation matching voxcity.simulator.common.geometry.rotate_vector_axis_angle.

Parameters:

vec – Vector to rotate (3,)
axis – Rotation axis (3,) - will be normalized
angle – Rotation angle in radians

Returns:

Rotated vector (3,)

voxcity.simulator_gpu.visibility.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.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.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.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.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.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.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.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)

voxcity.simulator_gpu.visibility.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.mark_building_by_id(voxcity_grid_ori: numpy.ndarray, building_id_grid_ori: numpy.ndarray, ids: List[int], mark: int = -30) → numpy.ndarray¶

Mark specific buildings in voxel data with a marker value.

Parameters:

voxcity_grid_ori – 3D voxel class array
building_id_grid_ori – 2D array of building IDs in uv layout
ids – List of building IDs to mark
mark – Marker value to use

Returns:

Modified voxel_data copy

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

voxcity.simulator_gpu.visibility.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.VOXCITY_GROUND_CODE = -1¶

voxcity.simulator_gpu.visibility.VOXCITY_TREE_CODE = -2¶

voxcity.simulator_gpu.visibility.VOXCITY_BUILDING_CODE = -3¶

voxcity.simulator_gpu.visibility.GREEN_VIEW_CODES¶