voxcity.simulator_gpu.visibility ================================ .. py:module:: voxcity.simulator_gpu.visibility .. autoapi-nested-parse:: 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 ---------- .. toctree:: :maxdepth: 1 /autoapi/voxcity/simulator_gpu/visibility/geometry/index /autoapi/voxcity/simulator_gpu/visibility/integration/index /autoapi/voxcity/simulator_gpu/visibility/landmark/index /autoapi/voxcity/simulator_gpu/visibility/view/index /autoapi/voxcity/simulator_gpu/visibility/workspace/index Attributes ---------- .. autoapisummary:: voxcity.simulator_gpu.visibility.VOXCITY_GROUND_CODE voxcity.simulator_gpu.visibility.VOXCITY_TREE_CODE voxcity.simulator_gpu.visibility.VOXCITY_BUILDING_CODE voxcity.simulator_gpu.visibility.GREEN_VIEW_CODES Classes ------- .. toctree:: :hidden: /autoapi/voxcity/simulator_gpu/visibility/ViewCalculator /autoapi/voxcity/simulator_gpu/visibility/SurfaceViewFactorCalculator /autoapi/voxcity/simulator_gpu/visibility/LandmarkVisibilityCalculator /autoapi/voxcity/simulator_gpu/visibility/SurfaceLandmarkVisibilityCalculator .. autoapisummary:: voxcity.simulator_gpu.visibility.ViewCalculator voxcity.simulator_gpu.visibility.SurfaceViewFactorCalculator voxcity.simulator_gpu.visibility.LandmarkVisibilityCalculator voxcity.simulator_gpu.visibility.SurfaceLandmarkVisibilityCalculator Functions --------- .. autoapisummary:: voxcity.simulator_gpu.visibility.compute_view_index_map voxcity.simulator_gpu.visibility.compute_sky_view_factor_map voxcity.simulator_gpu.visibility.compute_landmark_visibility_map voxcity.simulator_gpu.visibility.compute_landmark_visibility voxcity.simulator_gpu.visibility.generate_ray_directions_grid voxcity.simulator_gpu.visibility.generate_ray_directions_fibonacci voxcity.simulator_gpu.visibility.rotate_vector_axis_angle voxcity.simulator_gpu.visibility.get_view_index voxcity.simulator_gpu.visibility.get_sky_view_factor_map voxcity.simulator_gpu.visibility.get_surface_view_factor voxcity.simulator_gpu.visibility.get_landmark_visibility_map voxcity.simulator_gpu.visibility.get_surface_landmark_visibility voxcity.simulator_gpu.visibility.get_view_index_gpu voxcity.simulator_gpu.visibility.get_sky_view_factor_map_gpu voxcity.simulator_gpu.visibility.get_landmark_visibility_map_gpu voxcity.simulator_gpu.visibility.create_domain_from_voxcity voxcity.simulator_gpu.visibility.mark_building_by_id voxcity.simulator_gpu.visibility.clear_visibility_cache voxcity.simulator_gpu.visibility.reset_visibility_taichi_cache Package Contents ---------------- .. py:function:: compute_view_index_map(domain, voxel_data: numpy.ndarray = None, mode: str = 'green', **kwargs) -> numpy.ndarray Compute View Index map. :param domain: Domain object :param voxel_data: 3D voxel class array :param mode: 'green', 'sky', or custom :param \*\*kwargs: Additional parameters for ViewCalculator :returns: 2D view index map .. py:function:: compute_sky_view_factor_map(domain, voxel_data: numpy.ndarray = None, **kwargs) -> numpy.ndarray Compute Sky View Factor map. :param domain: Domain object :param voxel_data: 3D voxel class array :param \*\*kwargs: Additional parameters :returns: 2D SVF map .. py:function:: 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. :param domain: Domain object :param voxel_data: 3D voxel class array with landmarks marked :param landmark_value: Voxel value marking landmarks :param view_height_voxel: Observer height in voxels :param \*\*kwargs: Additional parameters :returns: 2D visibility map .. py:function:: 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`. .. rubric:: Notes - Uses Taichi GPU ray tracing underneath. - Returns a 2D map in uv layout, consistent with voxel_data. .. py:function:: 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. :param n_azimuth: Number of azimuthal divisions :param n_elevation: Number of elevation divisions :param elevation_min_degrees: Minimum elevation angle in degrees :param elevation_max_degrees: Maximum elevation angle in degrees :returns: Array of shape (n_azimuth * n_elevation, 3) with unit direction vectors .. py:function:: 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. :param n_rays: Total number of rays :param elevation_min_degrees: Minimum elevation angle in degrees :param elevation_max_degrees: Maximum elevation angle in degrees :returns: Array of shape (n_rays, 3) with unit direction vectors .. py:function:: 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. :param vec: Vector to rotate (3,) :param axis: Rotation axis (3,) - will be normalized :param angle: Rotation angle in radians :returns: Rotated vector (3,) .. 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_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_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) .. 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:: 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. :param voxcity_grid_ori: 3D voxel class array :param building_id_grid_ori: 2D array of building IDs in uv layout :param ids: List of building IDs to mark :param mark: Marker value to use :returns: Modified voxel_data copy .. 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: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