voxcity.visualizer.renderer =========================== .. py:module:: voxcity.visualizer.renderer Attributes ---------- .. autoapisummary:: voxcity.visualizer.renderer.go voxcity.visualizer.renderer.pv Classes ------- .. toctree:: :hidden: /autoapi/voxcity/visualizer/renderer/PyVistaRenderer .. autoapisummary:: voxcity.visualizer.renderer.PyVistaRenderer Functions --------- .. autoapisummary:: voxcity.visualizer.renderer.visualize_voxcity_plotly voxcity.visualizer.renderer.create_multi_view_scene voxcity.visualizer.renderer.create_rotation_view_scene voxcity.visualizer.renderer.visualize_voxcity Module Contents --------------- .. py:data:: go :value: None .. py:data:: pv :value: None .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. :param meshes: Dictionary of trimesh meshes keyed by class/label. :type meshes: dict[Any, trimesh.Trimesh] :param output_directory: Directory to save frames. :type output_directory: str :param projection_type: "perspective" or "orthographic". :type projection_type: str :param distance_factor: Camera distance multiplier. :type distance_factor: float :param frames_per_segment: Number of frames between each consecutive isometric anchor. :type frames_per_segment: int :param close_loop: If True, also generates frames to return from iso_back_right to iso_front_right. :type close_loop: bool :param file_prefix: Prefix for saved frame filenames. :type file_prefix: str :returns: List of saved frame file paths in order. :rtype: list[str] .. py:function:: 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. :param city: VoxCity object to visualize :type city: VoxCity :param mode: Visualization mode: "interactive" (Plotly) or "static" (PyVista) :type mode: str, default="interactive" :param Common Options: :param --------------: :param voxel_color_map: Color mapping for voxel classes :type voxel_color_map: str or dict, default="default" :param classes: Specific voxel classes to render :type classes: list, optional :param title: Plot title :type title: str, optional :param image_size: Unified image size (width, height) applied across modes. - Interactive: overrides width/height below when provided. - Static (including rotation): sets PyVista window size for screenshots. :type image_size: (int, int) or None, default=None :param Interactive Mode Options (Plotly): :param ----------------------------------: :param opacity: Voxel opacity (0-1) :type opacity: float, default=1.0 :param max_dimension: Maximum grid dimension before downsampling :type max_dimension: int, default=160 :param downsample: Manual downsampling stride :type downsample: int, optional :param show: Whether to display the plot :type show: bool, default=True :param return_fig: Whether to return the figure object :type return_fig: bool, default=False :param Static Mode Options (PyVista): :param ------------------------------: :param output_directory: Directory for saving rendered images :type output_directory: str, default="output" :param projection_type: Camera projection: "perspective" or "orthographic" :type projection_type: str, default="perspective" :param distance_factor: Camera distance multiplier :type distance_factor: float, default=1.0 :param rotation: If True, generate rotating isometric frames instead of multi-view snapshots :type rotation: bool, default=False :param rotation_frames_per_segment: Frames between each isometric anchor when rotation=True :type rotation_frames_per_segment: int, default=60 :param rotation_close_loop: If True, continue frames to return to start when rotation=True :type rotation_close_loop: bool, default=False :param rotation_file_prefix: Filename prefix for rotation frames when rotation=True :type rotation_file_prefix: str, default="city_rotation" :param image_size: Static rendering output image size (width, height). If None, uses default. :type image_size: (int, int) or None, default=None :param Building Simulation Overlay Options: :param ------------------------------------: :param building_sim_mesh: Building mesh with simulation results in metadata. Typically created by get_surface_view_factor() or get_building_solar_irradiance(). :type building_sim_mesh: trimesh.Trimesh, optional :param building_value_name: Metadata key to use for coloring (e.g., 'svf_values', 'global', 'direct', 'diffuse') :type building_value_name: str, default='svf_values' :param building_colormap: Matplotlib colormap for building values :type building_colormap: str, default='viridis' :param building_vmin: Minimum value for color scale :type building_vmin: float, optional :param building_vmax: Maximum value for color scale :type building_vmax: float, optional :param building_nan_color: Color for NaN/invalid values :type building_nan_color: str, default='gray' :param building_opacity: Building mesh opacity (0-1) :type building_opacity: float, default=1.0 :param building_shaded: Whether to apply shading to building mesh :type building_shaded: bool, default=False :param render_voxel_buildings: Whether to render voxel buildings when building_sim_mesh is provided :type render_voxel_buildings: bool, default=False :param Ground Simulation Surface Overlay Options: :param ------------------------------------------: :param ground_sim_grid: 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. :type ground_sim_grid: np.ndarray, optional :param ground_dem_grid: 2D DEM array for positioning the ground simulation surface. If None, uses city.dem.elevation when ground_sim_grid is provided. :type ground_dem_grid: np.ndarray, optional :param ground_z_offset: Height offset for ground simulation surface above DEM :type ground_z_offset: float, optional :param ground_view_point_height: Alternative parameter for ground surface height (used if ground_z_offset is None) :type ground_view_point_height: float, optional :param ground_colormap: Matplotlib colormap for ground values :type ground_colormap: str, default='viridis' :param ground_vmin: Minimum value for color scale :type ground_vmin: float, optional :param ground_vmax: Maximum value for color scale :type ground_vmax: float, optional :param sim_surface_opacity: Ground simulation surface opacity (0-1) :type sim_surface_opacity: float, default=0.95 :param ground_shaded: Whether to apply shading to ground surface :type ground_shaded: bool, default=False :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 .. rubric:: 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")