voxcity.utils.material
======================

.. py:module:: voxcity.utils.material

.. autoapi-nested-parse::

   Material utilities for VoxelCity voxel grid processing.

   This module provides functions for setting building materials and window patterns
   in 3D voxel grids based on building IDs, material types, and window ratios.
   The main functionality includes:
   - Material ID mapping and retrieval
   - Window pattern generation based on configurable ratios
   - Building material assignment from GeoDataFrame data



Functions
---------

.. autoapisummary::

   voxcity.utils.material.get_material_dict
   voxcity.utils.material.get_modulo_numbers
   voxcity.utils.material.set_building_material_by_id
   voxcity.utils.material.set_building_material_by_gdf


Module Contents
---------------

.. py:function:: get_material_dict()

   Returns a dictionary mapping material names to their corresponding ID values.

   The material IDs use negative values to distinguish them from other voxel types.
   Each material has a unique negative ID that can be used for material-based
   rendering and analysis.

   :returns:

             Dictionary with material names as keys and negative integer IDs as values.
                   Available materials: unknown, brick, wood, concrete, metal, stone, glass, plaster
   :rtype: dict


.. py:function:: get_modulo_numbers(window_ratio)

   Determines the appropriate modulo numbers for x, y, z based on window_ratio.

   This function creates different window patterns by returning modulo values that
   control the spacing of windows in the x, y, and z dimensions. Lower window_ratio
   values result in sparser window patterns (higher modulo values), while higher
   ratios create denser patterns.

   The function uses hash-based selection for certain ratios to introduce variety
   in window patterns for buildings with similar window ratios.

   :param window_ratio: Value between 0 and 1.0 representing window density
   :type window_ratio: float

   :returns:

             (x_mod, y_mod, z_mod) - modulo numbers for each dimension
                    Higher values = sparser windows, lower values = denser windows
   :rtype: tuple


.. py:function:: set_building_material_by_id(voxelcity_grid, building_id_grid_ori, ids, mark, window_ratio=0.125, glass_id=-16)

   Marks cells in voxelcity_grid based on building IDs and window ratio.
   Never sets glass_id to cells with maximum z index.

   This function processes buildings by:
   1. Finding all positions matching the specified building IDs
   2. Setting the base material for all building voxels
   3. Creating window patterns based on window_ratio and modulo calculations
   4. Ensuring the top floor (maximum z) never gets windows (glass_id)

   The window pattern is determined by the modulo values returned from get_modulo_numbers(),
   which creates different densities and arrangements of windows based on the window_ratio.

   :param voxelcity_grid: 3D numpy array representing the voxel grid
   :type voxelcity_grid: numpy.ndarray
   :param building_id_grid_ori: 2D numpy array containing building IDs
   :type building_id_grid_ori: numpy.ndarray
   :param ids: Building IDs to process
   :type ids: list/array
   :param mark: Material ID value to set for building cells
   :type mark: int
   :param window_ratio: Value between 0 and 1.0 determining window density:
                        ~0.125: sparse windows (2,2,2)
                        ~0.25: medium-sparse windows (2,2,1), (2,1,2), or (1,2,2)
                        ~0.5: medium windows (2,1,1), (1,2,1), or (1,1,2)
                        ~0.75: dense windows (2,1,1), (1,2,1), or (1,1,2)
                        >0.875: maximum density (1,1,1)
   :type window_ratio: float
   :param glass_id: Material ID for glass/window cells (default: -16)
   :type glass_id: int

   :returns: Modified voxelcity_grid with building materials and windows applied
   :rtype: numpy.ndarray


.. py:function:: set_building_material_by_gdf(voxelcity_grid_ori, building_id_grid, gdf_buildings, material_id_dict=None)

   Sets building materials based on a GeoDataFrame containing building information.

   This function iterates through a GeoDataFrame of building data and applies
   materials and window patterns to the corresponding buildings in the voxel grid.
   It handles missing material information by defaulting to 'unknown' material.

   :param voxelcity_grid_ori: 3D numpy array of the original voxel grid
   :type voxelcity_grid_ori: numpy.ndarray
   :param building_id_grid: 2D numpy array containing building IDs
   :type building_id_grid: numpy.ndarray
   :param gdf_buildings: Building information with required columns:
                         'building_id': Unique identifier for each building
                         'surface_material': Material type (brick, wood, concrete, etc.)
                         'window_ratio': Float between 0-1 for window density
   :type gdf_buildings: GeoDataFrame
   :param material_id_dict: Dictionary mapping material names to IDs.
                            If None, uses default from get_material_dict()
   :type material_id_dict: dict, optional

   :returns: Modified voxelcity_grid with all building materials and windows applied
   :rtype: numpy.ndarray