voxcity.visualizer

Submodules

• voxcity.visualizer.builder
• voxcity.visualizer.grids
• voxcity.visualizer.maps
• voxcity.visualizer.palette
• voxcity.visualizer.renderer
• voxcity.visualizer.renderer_gpu

Classes

MeshBuilder	Build mesh collections from voxel grids for rendering/export.
PyVistaRenderer	Renderer that uses PyVista to produce multi-view images from meshes or VoxCity.

Functions

create_multi_view_scene(meshes[, output_directory, ...])	Creates multiple rendered views of 3D city meshes from different camera angles.
visualize_voxcity_plotly(voxel_array, meshsize[, ...])	Interactive 3D visualization using Plotly Mesh3d of voxel faces and optional overlays.
visualize_voxcity(city[, mode, voxel_color_map, ...])	Visualize a VoxCity object with optional simulation result overlays.
get_voxel_color_map([color_scheme])	Returns a color map for voxel visualization based on the specified color scheme.
visualize_landcover_grid_on_basemap(landcover_grid, ...)
visualize_numerical_grid_on_basemap(grid, ...[, ...])
visualize_numerical_gdf_on_basemap(gdf[, value_name, ...])
visualize_point_gdf_on_basemap(point_gdf[, value_name])
plot_grid(grid, origin, adjusted_meshsize, u_vec, ...)
visualize_land_cover_grid_on_map(grid, ...[, source, ...])
visualize_building_height_grid_on_map(...[, vmin, ...])
visualize_numerical_grid_on_map(canopy_height_grid, ...)

Package Contents

voxcity.visualizer.create_multi_view_scene(meshes, output_directory='output', projection_type='perspective', distance_factor=1.0, image_size: tuple[int, int] | None = None, fixed_bounds: tuple[tuple[float, float, float], tuple[float, float, float]] | None = None)

Creates multiple rendered views of 3D city meshes from different camera angles.

voxcity.visualizer.visualize_voxcity_plotly(voxel_array, meshsize, classes=None, voxel_color_map='default', opacity=1.0, max_dimension=160, downsample=None, title=None, width=1000, height=800, show=True, return_fig=False, building_sim_mesh=None, building_value_name='svf_values', building_colormap='viridis', building_vmin=None, building_vmax=None, building_nan_color='gray', building_opacity=1.0, building_shaded=False, render_voxel_buildings=False, ground_sim_grid=None, ground_dem_grid=None, ground_z_offset=None, ground_view_point_height=None, ground_colormap='viridis', ground_vmin=None, ground_vmax=None, sim_surface_opacity=0.95, ground_shaded=False, building_colorbar_title=None, ground_colorbar_title=None, building_id_grid=None)

Interactive 3D visualization using Plotly Mesh3d of voxel faces and optional overlays.

voxcity.visualizer.visualize_voxcity(city: voxcity.models.VoxCity, mode: str = 'interactive', *, voxel_color_map: str | dict = 'default', classes=None, title: str | None = None, opacity: float = 1.0, max_dimension: int = 160, downsample: int | None = None, show: bool = True, return_fig: bool = False, output_directory: str = 'output', projection_type: str = 'perspective', distance_factor: float = 1.0, rotation: bool = False, rotation_frames_per_segment: int = 60, rotation_close_loop: bool = False, rotation_file_prefix: str = 'city_rotation', image_size: tuple[int, int] | None = None, fixed_scene_bounds_real: tuple[tuple[float, float, float], 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_opacity: float = 1.0, building_shaded: bool = False, render_voxel_buildings: bool = False, ground_sim_grid=None, ground_dem_grid=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, sim_surface_opacity: float = 0.95, ground_shaded: bool = False)

Visualize a VoxCity object with optional simulation result overlays.

Parameters:

• city (VoxCity) – VoxCity object to visualize

• mode (str, default="interactive") – Visualization mode: “interactive” (Plotly) or “static” (PyVista)

• Options (Ground Simulation Surface Overlay)

• --------------

• voxel_color_map (str or dict, default="default") – Color mapping for voxel classes

• classes (list, optional) – Specific voxel classes to render

• title (str, optional) – Plot title

• image_size ((int, int) or None, default=None) – Unified image size (width, height) applied across modes. - Interactive: overrides width/height below when provided. - Static (including rotation): sets PyVista window size for screenshots.

• (Plotly) (Interactive Mode Options)

• ----------------------------------

• opacity (float, default=1.0) – Voxel opacity (0-1)

• max_dimension (int, default=160) – Maximum grid dimension before downsampling

• downsample (int, optional) – Manual downsampling stride

• show (bool, default=True) – Whether to display the plot

• return_fig (bool, default=False) – Whether to return the figure object

• (PyVista) (Static Mode Options)

• ------------------------------

• output_directory (str, default="output") – Directory for saving rendered images

• projection_type (str, default="perspective") – Camera projection: “perspective” or “orthographic”

• distance_factor (float, default=1.0) – Camera distance multiplier

• rotation (bool, default=False) – If True, generate rotating isometric frames instead of multi-view snapshots

• rotation_frames_per_segment (int, default=60) – Frames between each isometric anchor when rotation=True

• rotation_close_loop (bool, default=False) – If True, continue frames to return to start when rotation=True

• rotation_file_prefix (str, default="city_rotation") – Filename prefix for rotation frames when rotation=True

• image_size – Static rendering output image size (width, height). If None, uses default.

• Options

• ------------------------------------

• building_sim_mesh (trimesh.Trimesh, optional) – Building mesh with simulation results in metadata. Typically created by get_surface_view_factor() or get_building_solar_irradiance().

• building_value_name (str, default='svf_values') – Metadata key to use for coloring (e.g., ‘svf_values’, ‘global’, ‘direct’, ‘diffuse’)

• building_colormap (str, default='viridis') – Matplotlib colormap for building values

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

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

• building_nan_color (str, default='gray') – Color for NaN/invalid values

• building_opacity (float, default=1.0) – Building mesh opacity (0-1)

• building_shaded (bool, default=False) – Whether to apply shading to building mesh

• render_voxel_buildings (bool, default=False) – Whether to render voxel buildings when building_sim_mesh is provided

• Options

• ------------------------------------------

• ground_sim_grid (np.ndarray, optional) – 2D array of ground-level simulation values (e.g., Green View Index, solar radiation). Should have the same shape as the city’s 2D grids.

• ground_dem_grid (np.ndarray, optional) – 2D DEM array for positioning the ground simulation surface. If None, uses city.dem.elevation when ground_sim_grid is provided.

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

• ground_view_point_height (float, optional) – Alternative parameter for ground surface height (used if ground_z_offset is None)

• ground_colormap (str, default='viridis') – Matplotlib colormap for ground values

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

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

• sim_surface_opacity (float, default=0.95) – Ground simulation surface opacity (0-1)

• ground_shaded (bool, default=False) – Whether to apply shading to ground surface

Returns:

• For mode=”interactive” – plotly.graph_objects.Figure or None Returns Figure if return_fig=True, otherwise None

• For mode=”static” – list of (view_name, filepath) tuples List of rendered view names and their file paths

Examples

Basic visualization: >>> visualize_voxcity(city, mode=”interactive”)

With building solar irradiance results: >>> building_mesh = get_building_solar_irradiance(city, …) >>> visualize_voxcity(city, mode=”interactive”, … building_sim_mesh=building_mesh, … building_value_name=’global’)

With ground-level Green View Index: >>> visualize_voxcity(city, mode=”interactive”, … ground_sim_grid=gvi_array, … ground_colormap=’YlGn’)

Static rendering with simulation overlays: >>> visualize_voxcity(city, mode=”static”, … building_sim_mesh=svf_mesh, … output_directory=”renders”)

voxcity.visualizer.get_voxel_color_map(color_scheme='default')

Returns a color map for voxel visualization based on the specified color scheme.

This function provides multiple predefined color schemes for visualizing voxel data. Each scheme maps voxel class IDs to RGB color values [0-255]. The class IDs follow a specific convention where negative values represent built environment elements and positive values represent natural/ground surface elements.

voxcity.visualizer.visualize_landcover_grid_on_basemap(landcover_grid, rectangle_vertices, meshsize, source='Standard', alpha=0.6, figsize=(12, 8), basemap='CartoDB light', show_edge=False, edge_color='black', edge_width=0.5)

voxcity.visualizer.visualize_numerical_grid_on_basemap(grid, rectangle_vertices, meshsize, value_name='value', cmap='viridis', vmin=None, vmax=None, alpha=0.6, figsize=(12, 8), basemap='CartoDB light', show_edge=False, edge_color='black', edge_width=0.5)

voxcity.visualizer.visualize_numerical_gdf_on_basemap(gdf, value_name='value', cmap='viridis', vmin=None, vmax=None, alpha=0.6, figsize=(12, 8), basemap='CartoDB light', show_edge=False, edge_color='black', edge_width=0.5, input_crs=None)

voxcity.visualizer.visualize_point_gdf_on_basemap(point_gdf, value_name='value', **kwargs)

voxcity.visualizer.plot_grid(grid, origin, adjusted_meshsize, u_vec, v_vec, transformer, vertices, data_type, vmin=None, vmax=None, color_map=None, alpha=0.5, buf=0.2, edge=True, basemap='CartoDB light', **kwargs)

voxcity.visualizer.visualize_land_cover_grid_on_map(grid, rectangle_vertices, meshsize, source='Urbanwatch', vmin=None, vmax=None, alpha=0.5, buf=0.2, edge=True, basemap='CartoDB light')

voxcity.visualizer.visualize_building_height_grid_on_map(building_height_grid, filtered_buildings, rectangle_vertices, meshsize, vmin=None, vmax=None, color_map=None, alpha=0.5, buf=0.2, edge=True, basemap='CartoDB light')

voxcity.visualizer.visualize_numerical_grid_on_map(canopy_height_grid, rectangle_vertices, meshsize, type, vmin=None, vmax=None, color_map=None, alpha=0.5, buf=0.2, edge=True, basemap='CartoDB light')