voxcity.simulator_gpu.visibility.integration ============================================ .. py:module:: voxcity.simulator_gpu.visibility.integration .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: voxcity.simulator_gpu.visibility.integration.VOXCITY_GROUND_CODE voxcity.simulator_gpu.visibility.integration.VOXCITY_TREE_CODE voxcity.simulator_gpu.visibility.integration.VOXCITY_BUILDING_CODE voxcity.simulator_gpu.visibility.integration.GREEN_VIEW_CODES Functions --------- .. autoapisummary:: voxcity.simulator_gpu.visibility.integration.clear_visibility_cache voxcity.simulator_gpu.visibility.integration.reset_visibility_taichi_cache voxcity.simulator_gpu.visibility.integration.create_domain_from_voxcity voxcity.simulator_gpu.visibility.integration.get_view_index_gpu voxcity.simulator_gpu.visibility.integration.get_view_index voxcity.simulator_gpu.visibility.integration.get_sky_view_factor_map voxcity.simulator_gpu.visibility.integration.get_surface_view_factor voxcity.simulator_gpu.visibility.integration.get_landmark_visibility_map voxcity.simulator_gpu.visibility.integration.get_surface_landmark_visibility voxcity.simulator_gpu.visibility.integration.get_sky_view_factor_map_gpu voxcity.simulator_gpu.visibility.integration.get_landmark_visibility_map_gpu Module Contents --------------- .. py:data:: VOXCITY_GROUND_CODE :value: -1 .. py:data:: VOXCITY_TREE_CODE :value: -2 .. py:data:: VOXCITY_BUILDING_CODE :value: -3 .. py:data:: GREEN_VIEW_CODES .. py:function:: clear_visibility_cache() Clear the cached Domain and workspace fields. .. py:function:: 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. .. py:function:: create_domain_from_voxcity(voxcity) -> voxcity.simulator_gpu.domain.Domain Create a Domain object from a VoxCity model. :param voxcity: VoxCity object with voxels attribute :returns: Domain object configured for view analysis .. py:function:: 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. :param voxcity: VoxCity object :param mode: Predefined mode ('green', 'sky', or None for custom) :param hit_values: Target voxel values to count as visible :param inclusion_mode: If True, count hits on targets; if False, count non-blocked rays :param view_point_height: Observer height above ground (meters) :param n_azimuth: Number of azimuthal divisions :param n_elevation: Number of elevation divisions :param elevation_min_degrees: Minimum viewing angle :param elevation_max_degrees: Maximum viewing angle :param ray_sampling: 'grid' or 'fibonacci' :param n_rays: Total rays for fibonacci sampling :param tree_k: Tree extinction coefficient :param tree_lad: Leaf area density :param show_plot: Whether to display a matplotlib plot :param \*\*kwargs: Additional parameters :returns: 2D array of view index values .. py:function:: 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. :param voxcity: VoxCity object :param mode: Predefined mode ('green', 'sky', or None for custom) :param hit_values: Target voxel values to count as visible :param inclusion_mode: If True, count hits on targets; if False, count non-blocked rays :param \*\*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 .. py:function:: 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. :param voxcity: VoxCity object :param show_plot: Whether to display a matplotlib plot :param \*\*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 .. py:function:: 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. :param voxcity: VoxCity object :param \*\*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 .. py:function:: 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. :param voxcity: VoxCity object :param building_gdf: GeoDataFrame of buildings (optional, will use voxcity.extras['building_gdf']) :param \*\*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) .. py:function:: 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. :param voxcity: VoxCity object :param building_gdf: GeoDataFrame of buildings :param \*\*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) .. py:function:: 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. :param voxcity: VoxCity object :param view_point_height: Observer height above ground (meters) :param n_azimuth: Number of azimuthal divisions :param n_elevation: Number of elevation divisions :param tree_k: Tree extinction coefficient :param tree_lad: Leaf area density :param show_plot: Whether to display a matplotlib plot :param \*\*kwargs: Additional parameters :returns: 2D array of SVF values .. py:function:: 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. :param voxcity: VoxCity object :param building_gdf: GeoDataFrame of buildings (optional) :param landmark_building_ids: List of building IDs to mark as landmarks :param view_point_height: Observer height above ground (meters) :param tree_k: Tree extinction coefficient :param tree_lad: Leaf area density :param show_plot: Whether to display a matplotlib plot :param \*\*kwargs: Additional parameters :returns: Tuple of (visibility_map, modified_voxel_data)