voxcity.visualizer.renderer

Attributes

go
pv

Classes

PyVistaRenderer

Renderer that uses PyVista to produce multi-view images from meshes or VoxCity.

Functions

visualize_voxcity_plotly(voxel_array, meshsize[, ...])	Interactive 3D visualization using Plotly Mesh3d of voxel faces and optional overlays.
create_multi_view_scene(meshes[, output_directory, ...])	Creates multiple rendered views of 3D city meshes from different camera angles.
create_rotation_view_scene(meshes[, output_directory, ...])	Creates a sequence of rendered frames forming a smooth isometric rotation that
visualize_voxcity(city[, mode, voxel_color_map, ...])	Visualize a VoxCity object with optional simulation result overlays.

Module Contents

voxcity.visualizer.renderer.go = None

voxcity.visualizer.renderer.pv = None

voxcity.visualizer.renderer.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.renderer.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.renderer.create_rotation_view_scene(meshes, output_directory: str = 'output', projection_type: str = 'perspective', distance_factor: float = 1.0, frames_per_segment: int = 60, close_loop: bool = False, file_prefix: str = 'city_rotation', image_size: tuple[int, int] | None = None, fixed_bounds: tuple[tuple[float, float, float], tuple[float, float, float]] | None = None)

Creates a sequence of rendered frames forming a smooth isometric rotation that passes through: iso_front_right -> iso_front_left -> iso_back_left -> iso_back_right.

Parameters:

• meshes (dict[Any, trimesh.Trimesh]) – Dictionary of trimesh meshes keyed by class/label.

• output_directory (str) – Directory to save frames.

• projection_type (str) – “perspective” or “orthographic”.

• distance_factor (float) – Camera distance multiplier.

• frames_per_segment (int) – Number of frames between each consecutive isometric anchor.

• close_loop (bool) – If True, also generates frames to return from iso_back_right to iso_front_right.

• file_prefix (str) – Prefix for saved frame filenames.

Returns:

List of saved frame file paths in order.

Return type:

list[str]

voxcity.visualizer.renderer.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”)