voxcity.utils.material

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

get_material_dict()	Returns a dictionary mapping material names to their corresponding ID values.
get_modulo_numbers(window_ratio)	Determines the appropriate modulo numbers for x, y, z based on window_ratio.
set_building_material_by_id(voxelcity_grid, ...[, ...])	Marks cells in voxelcity_grid based on building IDs and window ratio.
set_building_material_by_gdf(voxelcity_grid_ori, ...)	Sets building materials based on a GeoDataFrame containing building information.

Module Contents

voxcity.utils.material.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

Return type:

dict

voxcity.utils.material.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.

Parameters:

window_ratio (float) – Value between 0 and 1.0 representing window density

Returns:

(x_mod, y_mod, z_mod) - modulo numbers for each dimension

Higher values = sparser windows, lower values = denser windows

Return type:

tuple

voxcity.utils.material.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.

Parameters:

• voxelcity_grid (numpy.ndarray) – 3D numpy array representing the voxel grid

• building_id_grid_ori (numpy.ndarray) – 2D numpy array containing building IDs

• ids (list/array) – Building IDs to process

• mark (int) – Material ID value to set for building cells

• window_ratio (float) – 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)

• glass_id (int) – Material ID for glass/window cells (default: -16)

Returns:

Modified voxelcity_grid with building materials and windows applied

Return type:

numpy.ndarray

voxcity.utils.material.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.

Parameters:

• voxelcity_grid_ori (numpy.ndarray) – 3D numpy array of the original voxel grid

• building_id_grid (numpy.ndarray) – 2D numpy array containing building IDs

• gdf_buildings (GeoDataFrame) – 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

• material_id_dict (dict, optional) – Dictionary mapping material names to IDs. If None, uses default from get_material_dict()

Returns:

Modified voxelcity_grid with all building materials and windows applied

Return type:

numpy.ndarray