voxcity.visualizer ================== .. py:module:: voxcity.visualizer Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/voxcity/visualizer/builder/index /autoapi/voxcity/visualizer/grids/index /autoapi/voxcity/visualizer/maps/index /autoapi/voxcity/visualizer/palette/index /autoapi/voxcity/visualizer/renderer/index /autoapi/voxcity/visualizer/renderer_gpu/index Classes ------- .. toctree:: :hidden: /autoapi/voxcity/visualizer/MeshBuilder /autoapi/voxcity/visualizer/PyVistaRenderer .. autoapisummary:: voxcity.visualizer.MeshBuilder voxcity.visualizer.PyVistaRenderer Functions --------- .. autoapisummary:: voxcity.visualizer.create_multi_view_scene voxcity.visualizer.visualize_voxcity_plotly voxcity.visualizer.visualize_voxcity voxcity.visualizer.get_voxel_color_map voxcity.visualizer.visualize_landcover_grid_on_basemap voxcity.visualizer.visualize_numerical_grid_on_basemap voxcity.visualizer.visualize_numerical_gdf_on_basemap voxcity.visualizer.visualize_point_gdf_on_basemap voxcity.visualizer.plot_grid voxcity.visualizer.visualize_land_cover_grid_on_map voxcity.visualizer.visualize_building_height_grid_on_map voxcity.visualizer.visualize_numerical_grid_on_map Package Contents ---------------- .. 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:: 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:: 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") .. py:function:: 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. .. py:function:: 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) .. py:function:: 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) .. py:function:: 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) .. py:function:: visualize_point_gdf_on_basemap(point_gdf, value_name='value', **kwargs) .. py:function:: 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) .. py:function:: 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') .. py:function:: 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') .. py:function:: 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')