voxcity 0.5.14__py3-none-any.whl → 0.5.16__py3-none-any.whl

voxcity/geoprocessor/mesh.py

@@ -7,29 +7,75 @@ import matplotlib.pyplot as plt
 
 def create_voxel_mesh(voxel_array, class_id, meshsize=1.0, building_id_grid=None, mesh_type=None):
     """
-    Create a mesh from voxels preserving sharp edges, scaled by meshsize.
-
+    Create a 3D mesh from voxels preserving sharp edges, scaled by meshsize.
+    
+    This function converts a 3D voxel array into a triangulated mesh, where each voxel
+    face is converted into two triangles. The function preserves sharp edges between
+    different classes and handles special cases for buildings.
+    
     Parameters
     ----------
     voxel_array : np.ndarray (3D)
-        The voxel array of shape (X, Y, Z).
+        The voxel array of shape (X, Y, Z) where each cell contains a class ID.
+        - 0: typically represents void/air
+        - -2: typically represents trees
+        - -3: typically represents buildings
+        Other values can represent different classes as defined by the application.
+    
     class_id : int
-        The ID of the class to extract.
-    meshsize : float
-        The real-world size of each voxel in meters, for x, y, and z.
+        The ID of the class to extract. Only voxels with this ID will be included
+        in the output mesh.
+    
+    meshsize : float, default=1.0
+        The real-world size of each voxel in meters, applied uniformly to x, y, and z
+        dimensions. Used to scale the output mesh to real-world coordinates.
+    
     building_id_grid : np.ndarray (2D), optional
-        2D grid of building IDs, shape (X, Y). Used when class_id=-3 (buildings).
+        2D grid of building IDs with shape (X, Y). Only used when class_id=-3 (buildings).
+        Each cell contains a unique identifier for the building at that location.
+        This allows tracking which faces belong to which building.
+    
     mesh_type : str, optional
-        Type of mesh to create:
-        - None (default): create meshes for boundaries between different classes
-        - 'building_solar': only create meshes for boundaries between buildings (-3) 
-                           and void (0) or trees (-2)
+        Type of mesh to create, controlling which faces are included:
+        - None (default): create faces at boundaries between different classes
+        - 'building_solar': only create faces at boundaries between buildings (-3)
+                          and either void (0) or trees (-2). Useful for solar analysis
+                          where only exposed surfaces matter.
 
     Returns
     -------
     mesh : trimesh.Trimesh or None
-        The resulting mesh for the given class_id (or None if no voxels).
-        If class_id=-3, mesh.metadata['building_id'] contains building IDs.
+        The resulting triangulated mesh for the given class_id. Returns None if no
+        voxels of the specified class are found.
+        
+        The mesh includes:
+        - vertices: 3D coordinates of each vertex
+        - faces: triangles defined by vertex indices
+        - face_normals: normal vectors for each face
+        - metadata: If class_id=-3, includes 'building_id' mapping faces to buildings
+    
+    Examples
+    --------
+    Basic usage for a simple voxel array:
+    >>> voxels = np.zeros((10, 10, 10))
+    >>> voxels[4:7, 4:7, 0:5] = 1  # Create a simple column
+    >>> mesh = create_voxel_mesh(voxels, class_id=1, meshsize=0.5)
+    
+    Creating a building mesh with IDs:
+    >>> building_ids = np.zeros((10, 10))
+    >>> building_ids[4:7, 4:7] = 1  # Mark building #1
+    >>> mesh = create_voxel_mesh(voxels, class_id=-3, 
+    ...                         building_id_grid=building_ids,
+    ...                         meshsize=1.0)
+    
+    Notes
+    -----
+    - The function creates faces only at boundaries between different classes or at
+      the edges of the voxel array.
+    - Each face is split into two triangles for compatibility with graphics engines.
+    - Face normals are computed to ensure correct lighting and rendering.
+    - For buildings (class_id=-3), building IDs are tracked to maintain building identity.
+    - The mesh preserves sharp edges, which is important for architectural visualization.
     """
     # Find voxels of the current class
     voxel_coords = np.argwhere(voxel_array == class_id)
@@ -152,32 +198,78 @@ def create_sim_surface_mesh(sim_grid, dem_grid,
                             cmap_name='viridis',
                             vmin=None, vmax=None):
     """
-    Create a planar surface mesh from sim_grid located at dem_grid + z_offset.
-    Skips any cells in sim_grid that are NaN, and flips both sim_grid and dem_grid
-    (up-down) to match voxel_array orientation. Applies meshsize scaling in x,y.
-
+    Create a colored planar surface mesh from simulation data, positioned above a DEM.
+    
+    This function generates a 3D visualization mesh for 2D simulation results (like
+    Green View Index, solar radiation, etc.). The mesh is positioned above the Digital
+    Elevation Model (DEM) by a specified offset, and colored according to the simulation
+    values using a matplotlib colormap.
+    
     Parameters
     ----------
     sim_grid : 2D np.ndarray
-        2D array of simulation values (e.g., Green View Index).
+        2D array of simulation values (e.g., Green View Index, solar radiation).
+        NaN values in this grid will be skipped in the output mesh.
+        The grid should be oriented with north at the top.
+    
     dem_grid : 2D np.ndarray
-        2D array of ground elevations (same shape as sim_grid).
-    meshsize : float
-        Size of each cell in meters (same in x and y).
-    z_offset : float
-        Additional offset added to dem_grid for placing the mesh.
-    cmap_name : str
-        Matplotlib colormap name. Default is 'viridis'.
-    vmin : float or None
-        Minimum value for color mapping. If None, use min of sim_grid (non-NaN).
-    vmax : float or None
-        Maximum value for color mapping. If None, use max of sim_grid (non-NaN).
-
+        2D array of ground elevations in meters. Must have the same shape as sim_grid.
+        Used to position the visualization mesh at the correct height above terrain.
+    
+    meshsize : float, default=1.0
+        Size of each cell in meters. Applied uniformly to x and y dimensions.
+        Determines the resolution of the output mesh.
+    
+    z_offset : float, default=1.5
+        Additional height offset in meters added to dem_grid elevations.
+        Used to position the visualization above ground level for better visibility.
+    
+    cmap_name : str, default='viridis'
+        Matplotlib colormap name used for coloring the mesh based on sim_grid values.
+        Common options:
+        - 'viridis': Default, perceptually uniform, colorblind-friendly
+        - 'RdYlBu': Red-Yellow-Blue, good for diverging data
+        - 'jet': Rainbow colormap (not recommended for scientific visualization)
+    
+    vmin : float, optional
+        Minimum value for color mapping. If None, uses min of sim_grid (excluding NaN).
+        Used to control the range of the colormap.
+    
+    vmax : float, optional
+        Maximum value for color mapping. If None, uses max of sim_grid (excluding NaN).
+        Used to control the range of the colormap.
+    
     Returns
     -------
-    trimesh.Trimesh or None
-        A single mesh containing one square face per non-NaN cell.
-        Returns None if there are no valid cells.
+    mesh : trimesh.Trimesh or None
+        A single mesh containing one colored square face (two triangles) per non-NaN cell.
+        Returns None if there are no valid (non-NaN) cells in sim_grid.
+        
+        The mesh includes:
+        - vertices: 3D coordinates of each vertex
+        - faces: triangles defined by vertex indices
+        - face_colors: RGBA colors for each face based on sim_grid values
+        - visual: trimesh.visual.ColorVisuals object storing the face colors
+    
+    Examples
+    --------
+    Basic usage with Green View Index data:
+    >>> gvi = np.array([[0.5, 0.6], [0.4, 0.8]])  # GVI values
+    >>> dem = np.array([[10.0, 10.2], [9.8, 10.1]])  # Ground heights
+    >>> mesh = create_sim_surface_mesh(gvi, dem, meshsize=1.0, z_offset=1.5)
+    
+    Custom color range and colormap:
+    >>> mesh = create_sim_surface_mesh(gvi, dem,
+    ...                               cmap_name='RdYlBu',
+    ...                               vmin=0.0, vmax=1.0)
+    
+    Notes
+    -----
+    - The function automatically creates a matplotlib colorbar figure for visualization
+    - Both input grids are flipped vertically to match the voxel_array orientation
+    - Each grid cell is converted to two triangles for compatibility with 3D engines
+    - The mesh is positioned at dem_grid + z_offset to float above the terrain
+    - Face colors are interpolated from the colormap based on sim_grid values
     """
     # Flip arrays vertically
     sim_grid_flipped = np.flipud(sim_grid)
@@ -260,8 +352,65 @@ def create_sim_surface_mesh(sim_grid, dem_grid,
 
 def create_city_meshes(voxel_array, vox_dict, meshsize=1.0):
     """
-    Create meshes from voxel data with sharp edges preserved.
-    Applies meshsize for voxel scaling.
+    Create a collection of colored 3D meshes representing different city elements.
+    
+    This function processes a voxelized city model and creates separate meshes for
+    different urban elements (buildings, trees, etc.), each with its own color.
+    The function preserves sharp edges and applies appropriate colors based on the
+    provided color dictionary.
+    
+    Parameters
+    ----------
+    voxel_array : np.ndarray (3D)
+        3D array representing the voxelized city model. Each voxel contains a class ID
+        that maps to an urban element type:
+        - 0: Void/air (automatically skipped)
+        - -2: Trees
+        - -3: Buildings
+        Other values can represent different urban elements as defined in vox_dict.
+    
+    vox_dict : dict
+        Dictionary mapping class IDs to RGB colors. Each entry should be:
+        {class_id: [R, G, B]} where R, G, B are 0-255 integer values.
+        Example: {-3: [200, 200, 200], -2: [0, 255, 0]} for grey buildings and
+        green trees. The key 0 (air) is automatically excluded.
+    
+    meshsize : float, default=1.0
+        Size of each voxel in meters, applied uniformly to x, y, and z dimensions.
+        Used to scale the output meshes to real-world coordinates.
+    
+    Returns
+    -------
+    meshes : dict
+        Dictionary mapping class IDs to their corresponding trimesh.Trimesh objects.
+        Each mesh includes:
+        - vertices: 3D coordinates scaled by meshsize
+        - faces: triangulated faces preserving sharp edges
+        - face_colors: RGBA colors from vox_dict
+        - visual: trimesh.visual.ColorVisuals object storing the face colors
+        
+        Classes with no voxels are automatically excluded from the output.
+    
+    Examples
+    --------
+    Basic usage with buildings and trees:
+    >>> voxels = np.zeros((10, 10, 10))
+    >>> voxels[4:7, 4:7, 0:5] = -3  # Add a building
+    >>> voxels[2:4, 2:4, 0:3] = -2  # Add some trees
+    >>> colors = {
+    ...     -3: [200, 200, 200],  # Grey buildings
+    ...     -2: [0, 255, 0]       # Green trees
+    ... }
+    >>> meshes = create_city_meshes(voxels, colors, meshsize=1.0)
+    
+    Notes
+    -----
+    - The function automatically skips class_id=0 (typically air/void)
+    - Each urban element type gets its own separate mesh for efficient rendering
+    - Colors are converted from RGB [0-255] to RGBA [0-1] format
+    - Sharp edges are preserved to maintain architectural features
+    - Empty classes (no voxels) are automatically excluded from the output
+    - Errors during mesh creation for a class are caught and reported
     """
     meshes = {}
 
@@ -296,7 +445,58 @@ def create_city_meshes(voxel_array, vox_dict, meshsize=1.0):
 
 def export_meshes(meshes, output_directory, base_filename):
     """
-    Export meshes to OBJ (with MTL) and STL formats.
+    Export a collection of meshes to both OBJ (with MTL) and STL formats.
+    
+    This function exports meshes in two ways:
+    1. A single combined OBJ file with materials (and associated MTL file)
+    2. Separate STL files for each mesh, named with their class IDs
+    
+    Parameters
+    ----------
+    meshes : dict
+        Dictionary mapping class IDs to trimesh.Trimesh objects.
+        Each mesh should have:
+        - vertices: 3D coordinates
+        - faces: triangulated faces
+        - face_colors: RGBA colors (if using materials)
+    
+    output_directory : str
+        Directory path where the output files will be saved.
+        Will be created if it doesn't exist.
+    
+    base_filename : str
+        Base name for the output files (without extension).
+        Will be used to create:
+        - {base_filename}.obj : Combined mesh with materials
+        - {base_filename}.mtl : Material definitions for OBJ
+        - {base_filename}_{class_id}.stl : Individual STL files
+    
+    Returns
+    -------
+    None
+        Files are written directly to the specified output directory.
+    
+    Examples
+    --------
+    >>> meshes = {
+    ...     -3: building_mesh,  # Building mesh with grey color
+    ...     -2: tree_mesh      # Tree mesh with green color
+    ... }
+    >>> export_meshes(meshes, 'output/models', 'city_model')
+    
+    This will create:
+    - output/models/city_model.obj
+    - output/models/city_model.mtl
+    - output/models/city_model_-3.stl
+    - output/models/city_model_-2.stl
+    
+    Notes
+    -----
+    - OBJ/MTL format preserves colors and materials but is more complex
+    - STL format is simpler but doesn't support colors
+    - STL files are exported separately for each class for easier processing
+    - The OBJ file combines all meshes while preserving their materials
+    - File extensions are automatically added to the base filename
     """
     # Export combined mesh as OBJ with materials
     combined_mesh = trimesh.util.concatenate(list(meshes.values()))
@@ -309,8 +509,55 @@ def export_meshes(meshes, output_directory, base_filename):
 
 def split_vertices_manual(mesh):
     """
-    Imitate trimesh's split_vertices() by giving each face its own copy of vertices.
-    This ensures every face is truly disconnected, preventing smooth shading in Rhino.
+    Split a mesh into independent faces by duplicating shared vertices.
+    
+    This function imitates trimesh's split_vertices() functionality but ensures
+    complete face independence by giving each face its own copy of vertices.
+    This is particularly useful for rendering applications where smooth shading
+    between faces is undesirable, such as architectural visualization in Rhino.
+    
+    Parameters
+    ----------
+    mesh : trimesh.Trimesh
+        Input mesh to split. Should have:
+        - vertices: array of vertex coordinates
+        - faces: array of vertex indices forming triangles
+        - visual: Optional ColorVisuals object with face colors
+    
+    Returns
+    -------
+    out_mesh : trimesh.Trimesh
+        New mesh where each face is completely independent, with:
+        - Duplicated vertices for each face
+        - No vertex sharing between faces
+        - Preserved face colors if present in input
+        - Each face as a separate component
+    
+    Examples
+    --------
+    Basic usage:
+    >>> vertices = np.array([[0,0,0], [1,0,0], [1,1,0], [0,1,0]])
+    >>> faces = np.array([[0,1,2], [0,2,3]])  # Two triangles sharing vertices
+    >>> mesh = trimesh.Trimesh(vertices=vertices, faces=faces)
+    >>> split_mesh = split_vertices_manual(mesh)
+    >>> print(f"Original vertices: {len(mesh.vertices)}")  # 4 vertices
+    >>> print(f"Split vertices: {len(split_mesh.vertices)}")  # 6 vertices
+    
+    With face colors:
+    >>> colors = np.array([[255,0,0,255], [0,255,0,255]])  # Red and green faces
+    >>> mesh.visual = trimesh.visual.ColorVisuals(mesh, face_colors=colors)
+    >>> split_mesh = split_vertices_manual(mesh)  # Colors are preserved
+    
+    Notes
+    -----
+    - Each output face has exactly 3 unique vertices
+    - Face colors are preserved in the output mesh
+    - Useful for:
+        - Preventing smooth shading artifacts
+        - Ensuring face color independence
+        - Preparing meshes for CAD software
+        - Creating sharp edges in architectural models
+    - Memory usage increases as vertices are duplicated
     """
     new_meshes = []
     
@@ -345,23 +592,80 @@ def split_vertices_manual(mesh):
 
 def save_obj_from_colored_mesh(meshes, output_path, base_filename):
     """
-    Save colored meshes as OBJ and MTL files.
+    Save a collection of colored meshes as OBJ and MTL files with material support.
+    
+    This function exports colored meshes to the Wavefront OBJ format with an
+    accompanying MTL file for material definitions. It handles the conversion of
+    face colors to materials and ensures proper material assignment in the OBJ file.
+    The function is particularly useful for preserving color information in
+    architectural and urban visualization models.
     
     Parameters
     ----------
     meshes : dict
-        Dictionary of trimesh.Trimesh objects with face colors.
+        Dictionary mapping class IDs to trimesh.Trimesh objects.
+        Each mesh should have:
+        - vertices: array of 3D coordinates
+        - faces: array of vertex indices forming triangles
+        - visual.face_colors: RGBA colors for each face
+    
     output_path : str
         Directory path where to save the files.
+        Will be created if it doesn't exist.
+        Should be writable by the current user.
+    
     base_filename : str
         Base name for the output files (without extension).
-        
+        Will be used to create:
+        - {base_filename}.obj : The main geometry file
+        - {base_filename}.mtl : The material definitions file
+    
     Returns
     -------
     tuple
-        Paths to the saved (obj_file, mtl_file).
-    """
+        (obj_path, mtl_path) : Paths to the saved OBJ and MTL files.
+        Both paths are absolute or relative depending on the input output_path.
     
+    Examples
+    --------
+    Basic usage with multiple colored meshes:
+    >>> building_mesh = trimesh.Trimesh(
+    ...     vertices=[[0,0,0], [1,0,0], [1,1,0]],
+    ...     faces=[[0,1,2]],
+    ...     face_colors=[[200,200,200,255]]  # Grey color
+    ... )
+    >>> tree_mesh = trimesh.Trimesh(
+    ...     vertices=[[2,0,0], [3,0,0], [2.5,1,0]],
+    ...     faces=[[0,1,2]],
+    ...     face_colors=[[0,255,0,255]]  # Green color
+    ... )
+    >>> meshes = {-3: building_mesh, -2: tree_mesh}
+    >>> obj_path, mtl_path = save_obj_from_colored_mesh(
+    ...     meshes, 'output/models', 'city'
+    ... )
+    
+    Notes
+    -----
+    - Creates unique materials for each distinct face color
+    - Material names are auto-generated as 'material_0', 'material_1', etc.
+    - Handles both RGB and RGBA colors (alpha channel supported)
+    - Colors are normalized from [0-255] to [0-1] range for MTL format
+    - Vertices are written in OBJ's 1-based indexing format
+    - Faces are grouped by material for efficient rendering
+    - The MTL file is automatically referenced in the OBJ file
+    
+    File Format Details
+    -----------------
+    OBJ file structure:
+    - mtllib reference to MTL file
+    - All vertex coordinates (v)
+    - Face definitions (f) grouped by material (usemtl)
+    
+    MTL file structure:
+    - newmtl: Material name
+    - Kd: Diffuse color (RGB)
+    - d: Alpha/transparency
+    """
     os.makedirs(output_path, exist_ok=True)
     obj_path = os.path.join(output_path, f"{base_filename}.obj")
     mtl_path = os.path.join(output_path, f"{base_filename}.mtl")