voxcity.visualizer.renderer_gpu

GPU-accelerated renderer using Taichi for ray tracing.

This module provides GPU-accelerated rendering functionality for VoxCity visualization, using Taichi for parallel ray tracing on GPU.

Based on ray-tracing-one-weekend-taichi implementation, extended for triangle mesh support.

Attributes

Vector3

REFLECTIVE_CLASSES

METALLIC_CLASSES

Classes

GPURenderer

High-level GPU renderer for VoxCity objects.

Functions

light_direction_from_angles(→ Tuple[float, float, float])

Convert azimuth and elevation angles to light direction vector (Z-up).

build_bvh_fast(→ Tuple[numpy.ndarray, numpy.ndarray, ...)

Build BVH using fast iterative construction with vectorized operations.

merge_meshes(→ Tuple[numpy.ndarray, numpy.ndarray, ...)

Merge all meshes in a collection into single arrays with material assignments.

visualize_voxcity_gpu(...)

Visualize a VoxCity using GPU-accelerated ray tracing.

Module Contents

voxcity.visualizer.renderer_gpu.light_direction_from_angles(azimuth_deg: float, elevation_deg: float) → Tuple[float, float, float][source]

Convert azimuth and elevation angles to light direction vector (Z-up).

Parameters:

  • azimuth_deg – Angle in XY plane from X-axis (0°=East, 90°=North), in degrees

  • elevation_deg – Angle above horizon (0°=horizontal, 90°=zenith), in degrees

Returns:

Normalized (x, y, z) direction vector pointing toward the light source

voxcity.visualizer.renderer_gpu.build_bvh_fast(vertices: numpy.ndarray, indices: numpy.ndarray) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

Build BVH using fast iterative construction with vectorized operations.

Returns arrays for GPU consumption: - bvh_triangle_id: triangle ID at each node (-1 for internal) - bvh_left_id: left child ID (-1 for none) - bvh_right_id: right child ID (-1 for none) - bvh_next_id: next node in traversal (-1 for none) - bvh_min: bounding box min (N, 3) - bvh_max: bounding box max (N, 3)

voxcity.visualizer.renderer_gpu.Vector3
voxcity.visualizer.renderer_gpu.REFLECTIVE_CLASSES
voxcity.visualizer.renderer_gpu.METALLIC_CLASSES
voxcity.visualizer.renderer_gpu.merge_meshes(mesh_collection: voxcity.models.MeshCollection, exclude_classes: set | None = None) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

Merge all meshes in a collection into single arrays with material assignments.

Parameters:

  • mesh_collection (MeshCollection) – Collection of meshes to merge

  • exclude_classes (set, optional) – Set of class IDs to exclude from merging (e.g., {-3} to skip buildings)

Returns:

  • vertices (np.ndarray) – (N, 3) combined vertices

  • indices (np.ndarray) – (M, 3) combined triangle indices

  • colors (np.ndarray) – (M, 3) combined face colors

  • materials (np.ndarray) – (M,) material types per face (0=Lambert, 1=Metal, 2=Dielectric)

voxcity.visualizer.renderer_gpu.visualize_voxcity_gpu(city: voxcity.models.VoxCity, voxel_color_map: str | dict = 'default', width: int = 1920, height: int = 1080, samples_per_pixel: int = 64, max_depth: int = 8, camera_position: Tuple[float, float, float] | None = None, camera_look_at: Tuple[float, float, float] | None = None, fov: float = 25.0, output_path: str | None = None, show_progress: bool = True, arch: str = 'gpu', rotation: bool = False, output_directory: str = 'output', rotation_frames: int = 240, rotation_file_prefix: str = 'city_rotation', multi_view: bool = False, multi_view_file_prefix: str = 'city_view', views: List[str] | None = None, floor_enabled: bool = True, light_direction: Tuple[float, float, float] | None = None, direct: Tuple[float, float, float] | None = None, ambient: Tuple[float, float, float] | None = None, background_color: Tuple[float, float, float] | None = None, building_sim_mesh=None, building_value_name: str = 'svf_values', building_colormap: str = 'viridis', building_vmin: float | None = None, building_vmax: float | None = None, building_nan_color: str = 'gray', building_emissive: float = 0.0, render_voxel_buildings: bool = False, ground_sim_grid: numpy.ndarray | None = None, ground_dem_grid: numpy.ndarray | None = None, ground_z_offset: float | None = None, ground_view_point_height: float | None = None, ground_colormap: str = 'viridis', ground_vmin: float | None = None, ground_vmax: float | None = None, ground_emissive: float = 0.0) → numpy.ndarray | List[str] | List[Tuple[str, str]][source]

Visualize a VoxCity using GPU-accelerated ray tracing.

This is the main entry point for GPU rendering, providing a simple interface similar to visualize_voxcity() but with GPU acceleration.

Parameters:

  • city (VoxCity) – The VoxCity object to visualize

  • voxel_color_map (str or dict) – Color mapping for voxel classes

  • width (int) – Output image width

  • height (int) – Output image height

  • samples_per_pixel (int) – Anti-aliasing quality (higher = better, slower)

  • max_depth (int) – Ray bounce depth

  • camera_position (tuple, optional) – Camera position (auto-computed if None)

  • camera_look_at (tuple, optional) – Camera look-at point (auto-computed if None)

  • fov (float) – Field of view in degrees

  • output_path (str, optional) – Path to save the rendered image

  • show_progress (bool) – Whether to show rendering progress

  • arch (str) – Compute architecture (‘gpu’, ‘cpu’, ‘cuda’, ‘vulkan’, ‘metal’)

  • rotation (bool) – If True, render rotating frames instead of single image

  • output_directory (str) – Directory for output frames/images

  • rotation_frames (int) – Number of frames for rotation

  • rotation_file_prefix (str) – Filename prefix for rotation frames

  • multi_view (bool) – If True, render standard multi-view images (isometric + orthographic)

  • multi_view_file_prefix (str) – Filename prefix for multi-view images

  • views (List[str], optional) – Specific views to render. Available views: - Isometric: ‘iso_front_right’, ‘iso_front_left’, ‘iso_back_right’, ‘iso_back_left’ - Orthographic: ‘xy_top’, ‘yz_right’, ‘xz_front’, ‘yz_left’, ‘xz_back’ If None, renders all 9 standard views.

  • floor_enabled (bool) – Whether to render a floor plane that receives shadows (default: True)

  • light_direction (tuple, optional) – Light direction vector (x, y, z). Use light_direction_from_angles() for easy setup. If None, uses default southwest lighting.

  • direct (tuple, optional) – Direct light color and intensity (R, G, B) from 0.0 to 1.0. Higher values = brighter direct light. Default is (0.9, 0.9, 0.85).

  • ambient (tuple, optional) – Ambient light color (R, G, B) from 0.0 to 1.0. If None, uses default.

  • background_color (tuple, optional) – Background color (R, G, B) from 0.0 to 1.0. If None, uses default light blue.

  • building_sim_mesh (trimesh, optional) – Building mesh with simulation results in metadata

  • building_value_name (str) – Metadata key for building values (e.g., ‘svf_values’, ‘global’, ‘direct’)

  • building_colormap (str) – Matplotlib colormap for building values

  • building_vmin (float, optional) – Minimum value for building color scale

  • building_vmax (float, optional) – Maximum value for building color scale

  • building_nan_color (str) – Color for NaN/invalid building values

  • building_emissive (float) – Emissive/luminous intensity for building simulation mesh (0=no emission, >0=glowing)

  • render_voxel_buildings (bool) – Whether to show voxel buildings with sim mesh

  • ground_sim_grid (np.ndarray, optional) – 2D array of ground-level simulation values (e.g., GVI, solar)

  • ground_dem_grid (np.ndarray, optional) – 2D DEM array for ground surface positioning

  • ground_z_offset (float, optional) – Height offset for ground surface above DEM

  • ground_view_point_height (float, optional) – Alternative height parameter for ground surface

  • ground_colormap (str) – Matplotlib colormap for ground values

  • ground_vmin (float, optional) – Minimum value for ground color scale

  • ground_vmax (float, optional) – Maximum value for ground color scale

  • ground_emissive (float) – Emissive/luminous intensity for ground simulation mesh (0=no emission, >0=glowing)

Returns:

If rotation=False and multi_view=False: (H, W, 3) RGB image array If rotation=True: List of frame file paths If multi_view=True: List of (view_name, filepath) tuples

Return type:

np.ndarray or List[str] or List[Tuple[str, str]]

Examples

Simple rendering: >>> img = visualize_voxcity_gpu(city)

Save to file: >>> img = visualize_voxcity_gpu(city, output_path=”render.png”)

High quality render: >>> img = visualize_voxcity_gpu(city, samples_per_pixel=64, width=1920, height=1080)

Rotation animation: >>> frames = visualize_voxcity_gpu(city, rotation=True, rotation_frames=120)

Multi-view rendering (9 standard views): >>> images = visualize_voxcity_gpu(city, multi_view=True, output_directory=”output”) >>> for view_name, path in images: … print(f”{view_name}: {path}”)

Multi-view with specific views only: >>> images = visualize_voxcity_gpu(city, multi_view=True, … views=[‘iso_front_right’, ‘iso_front_left’, ‘xy_top’])

With building solar irradiance: >>> building_mesh = get_building_solar_irradiance(city, …) >>> img = visualize_voxcity_gpu(city, building_sim_mesh=building_mesh, … building_value_name=’global’, building_colormap=’magma’)

With ground-level Green View Index: >>> img = visualize_voxcity_gpu(city, ground_sim_grid=gvi_array, ground_colormap=’YlGn’)