voxcity.geoprocessor.raster

Raster processing package.

Orientation contract: - All public functions accept and return 2D grids using the canonical internal

orientation “uv_m/SOUTH_UP”: axis 0 = u/north (row 0 = southern origin edge), axis 1 = v/east.

• Where data sources use south_up, conversions are performed internally; outputs are uv_m/SOUTH_UP unless explicitly documented otherwise.

• Columns increase eastward (col 0 = west/left), indices increase to the east.

Submodules

• voxcity.geoprocessor.raster.buildings
• voxcity.geoprocessor.raster.canopy
• voxcity.geoprocessor.raster.core
• voxcity.geoprocessor.raster.export
• voxcity.geoprocessor.raster.landcover
• voxcity.geoprocessor.raster.raster

Functions

apply_operation(→ numpy.ndarray)	Applies a sequence of operations to an array based on a mesh size to normalize and discretize values.
translate_array(→ numpy.ndarray)	Translate values in an array using a dictionary mapping (vectorized).
group_and_label_cells(→ numpy.ndarray)	Convert non-zero numbers in a 2D numpy array to sequential IDs starting from 1.
process_grid_optimized(→ numpy.ndarray)	Optimized version that computes per-building averages without allocating huge arrays
process_grid(→ numpy.ndarray)	Safe version that tries optimization first, then falls back to original method.
calculate_grid_size(→ Tuple[Tuple[int, int], ...)	Calculate grid size and adjusted mesh size based on input parameters.
create_coordinate_mesh(→ numpy.ndarray)	Create a coordinate mesh based on input parameters.
create_cell_polygon(origin, i, j, adjusted_meshsize, ...)	Create a polygon representing a grid cell.
compute_grid_shape(→ Tuple[int, int])	Compute the grid dimensions (rows, cols) for a given rectangle and mesh size.
tree_height_grid_from_land_cover(→ numpy.ndarray)	Convert a land cover grid to a tree height grid.
create_land_cover_grid_from_geotiff_polygon(...)	Create a land cover grid from a GeoTIFF file within a polygon boundary.
create_land_cover_grid_from_gdf_polygon(→ numpy.ndarray)	Create a grid of land cover classes from GeoDataFrame polygon data.
create_height_grid_from_geotiff_polygon(→ numpy.ndarray)	Create a height grid from a GeoTIFF file within a polygon boundary.
create_dem_grid_from_geotiff_polygon(tiff_path, ...[, ...])	Create a Digital Elevation Model (DEM) grid from a GeoTIFF within a polygon boundary.
create_building_height_grid_from_gdf_polygon(gdf, ...)	Create a building height grid from GeoDataFrame data within a polygon boundary.
create_building_height_grid_from_open_building_temporal_polygon(...)	Create a building height grid from OpenBuildings temporal data within a polygon.
grid_to_geodataframe(grid_ori, rectangle_vertices, ...)	Converts a 2D grid to a GeoDataFrame with cell polygons and values.
grid_to_point_geodataframe(grid_ori, ...)	Converts a 2D grid to a GeoDataFrame with point geometries at cell centers and values.
create_vegetation_height_grid_from_gdf_polygon(...)	Create a vegetation height grid from a GeoDataFrame of vegetation polygons/objects.
create_dem_grid_from_gdf_polygon(terrain_gdf, ...)	Create a height grid from a terrain GeoDataFrame using nearest-neighbor sampling.
create_canopy_grids_from_tree_gdf(tree_gdf, meshsize, ...)	Create canopy top and bottom height grids from a tree GeoDataFrame.

Package Contents

voxcity.geoprocessor.raster.apply_operation(arr: numpy.ndarray, meshsize: float) → numpy.ndarray

Applies a sequence of operations to an array based on a mesh size to normalize and discretize values.

1. Divide by meshsize, 2) +0.5, 3) floor, 4) rescale by meshsize

voxcity.geoprocessor.raster.translate_array(input_array: numpy.ndarray, translation_dict: Dict[Any, Any]) → numpy.ndarray

Translate values in an array using a dictionary mapping (vectorized).

Any value not found in the mapping is replaced with an empty string. Returns an object-dtype ndarray preserving the input shape.

voxcity.geoprocessor.raster.group_and_label_cells(array: numpy.ndarray) → numpy.ndarray

Convert non-zero numbers in a 2D numpy array to sequential IDs starting from 1.

voxcity.geoprocessor.raster.process_grid_optimized(grid_bi: numpy.ndarray, dem_grid: numpy.ndarray) → numpy.ndarray

Optimized version that computes per-building averages without allocating huge arrays when building IDs are large and sparse.

voxcity.geoprocessor.raster.process_grid(grid_bi: numpy.ndarray, dem_grid: numpy.ndarray) → numpy.ndarray

Safe version that tries optimization first, then falls back to original method.

voxcity.geoprocessor.raster.calculate_grid_size(side_1: numpy.ndarray, side_2: numpy.ndarray, u_vec: numpy.ndarray, v_vec: numpy.ndarray, meshsize: float) → Tuple[Tuple[int, int], Tuple[float, float]]

Calculate grid size and adjusted mesh size based on input parameters. Returns ((nx, ny), (dx, dy))

voxcity.geoprocessor.raster.create_coordinate_mesh(origin: numpy.ndarray, grid_size: Tuple[int, int], adjusted_meshsize: Tuple[float, float], u_vec: numpy.ndarray, v_vec: numpy.ndarray) → numpy.ndarray

Create a coordinate mesh based on input parameters. Returns array of shape (coord_dim, ny, nx)

voxcity.geoprocessor.raster.create_cell_polygon(origin: numpy.ndarray, i: int, j: int, adjusted_meshsize: Tuple[float, float], u_vec: numpy.ndarray, v_vec: numpy.ndarray)

Create a polygon representing a grid cell.

voxcity.geoprocessor.raster.compute_grid_shape(rectangle_vertices, meshsize: float) → Tuple[int, int]

Compute the grid dimensions (rows, cols) for a given rectangle and mesh size.

This is useful when you need to know the output grid shape without actually creating the grid (e.g., for pre-allocating arrays or fallback shapes).

Parameters:

• rectangle_vertices – List of 4 vertices [(lon, lat), …] defining the rectangle.

• meshsize – Grid cell size in meters.

Returns:

Tuple of (grid_size_0, grid_size_1) representing grid dimensions.

voxcity.geoprocessor.raster.tree_height_grid_from_land_cover(land_cover_grid_ori: numpy.ndarray) → numpy.ndarray

Convert a land cover grid to a tree height grid.

Expects 1-based land cover indices where class 5 is Tree.

voxcity.geoprocessor.raster.create_land_cover_grid_from_geotiff_polygon(tiff_path: str, mesh_size: float, land_cover_classes: Dict[str, Any], polygon: List[Tuple[float, float]]) → numpy.ndarray

Create a land cover grid from a GeoTIFF file within a polygon boundary.

Uses compute_cell_center_coords() so rotated rectangles are handled correctly.

voxcity.geoprocessor.raster.create_land_cover_grid_from_gdf_polygon(gdf, meshsize: float, source: str, rectangle_vertices: List[Tuple[float, float]], default_class: str = 'Developed space', detect_ocean: bool = True, land_polygon='NOT_PROVIDED') → numpy.ndarray

Create a grid of land cover classes from GeoDataFrame polygon data.

Uses vectorized rasterization for ~100x speedup over cell-by-cell intersection. Correctly handles rotated rectangles by rasterizing onto a bounding-box grid and then sampling at the rotated cell centre coordinates.

Parameters:

• gdf – GeoDataFrame with land cover polygons and ‘class’ column

• meshsize – Grid cell size in meters

• source – Land cover data source name (e.g., ‘OpenStreetMap’)

• rectangle_vertices – List of (lon, lat) tuples defining the area

• default_class – Default class for cells not covered by any polygon

• detect_ocean – If True, use OSM land polygons to detect ocean areas. Areas outside land polygons will be classified as ‘Water’ instead of the default class.

• land_polygon – Optional pre-computed land polygon from OSM coastlines. If provided (including None), this is used directly. If “NOT_PROVIDED”, coastlines will be queried when detect_ocean=True.

Returns:

2D numpy array of land cover class names

voxcity.geoprocessor.raster.create_height_grid_from_geotiff_polygon(tiff_path: str, mesh_size: float, polygon: List[Tuple[float, float]]) → numpy.ndarray

Create a height grid from a GeoTIFF file within a polygon boundary.

Uses compute_cell_center_coords() so rotated rectangles are handled correctly.

voxcity.geoprocessor.raster.create_dem_grid_from_geotiff_polygon(tiff_path, mesh_size, rectangle_vertices, dem_interpolation=False)

Create a Digital Elevation Model (DEM) grid from a GeoTIFF within a polygon boundary.

Uses compute_cell_center_coords() so rotated rectangles are handled correctly.

voxcity.geoprocessor.raster.create_building_height_grid_from_gdf_polygon(gdf: geopandas.GeoDataFrame, meshsize: float, rectangle_vertices: List[Tuple[float, float]], overlapping_footprint: any = 'auto', gdf_comp: geopandas.GeoDataFrame | None = None, geotiff_path_comp: str | None = None, complement_building_footprints: bool | None = None, complement_height: float | None = None)

Create a building height grid from GeoDataFrame data within a polygon boundary. Returns: (building_height_grid, building_min_height_grid, building_id_grid, filtered_buildings)

voxcity.geoprocessor.raster.create_building_height_grid_from_open_building_temporal_polygon(meshsize, rectangle_vertices, output_dir)

Create a building height grid from OpenBuildings temporal data within a polygon.

voxcity.geoprocessor.raster.grid_to_geodataframe(grid_ori, rectangle_vertices, meshsize)

Converts a 2D grid to a GeoDataFrame with cell polygons and values. Output CRS: EPSG:4326

voxcity.geoprocessor.raster.grid_to_point_geodataframe(grid_ori, rectangle_vertices, meshsize)

Converts a 2D grid to a GeoDataFrame with point geometries at cell centers and values. Output CRS: EPSG:4326

voxcity.geoprocessor.raster.create_vegetation_height_grid_from_gdf_polygon(veg_gdf, mesh_size, polygon)

Create a vegetation height grid from a GeoDataFrame of vegetation polygons/objects. Cells with vegetation take the max height of intersecting features. Returns uv_m/SOUTH_UP grid (axis 0 = u/north, row 0 = southern origin edge).

Uses compute_cell_center_coords() so rotated rectangles are handled correctly.

voxcity.geoprocessor.raster.create_dem_grid_from_gdf_polygon(terrain_gdf, mesh_size, polygon)

Create a height grid from a terrain GeoDataFrame using nearest-neighbor sampling. Returns uv_m/SOUTH_UP grid (axis 0 = u/north, row 0 = southern origin edge).

Uses compute_cell_center_coords() so rotated rectangles are handled correctly.

voxcity.geoprocessor.raster.create_canopy_grids_from_tree_gdf(tree_gdf, meshsize, rectangle_vertices)

Create canopy top and bottom height grids from a tree GeoDataFrame.

Supports both Point geometries (individual trees with ellipsoid crowns) and Polygon geometries (forest/wood areas with flat canopy).

Parameters:

• tree_gdf – GeoDataFrame with columns: - geometry: Point or Polygon/MultiPolygon - top_height: Height to canopy top (meters) - bottom_height: Height to canopy bottom (meters) - crown_diameter: Crown diameter (meters, used for Point geometries) - geometry_type (optional): ‘point’ or ‘polygon’ to distinguish geometry types

• meshsize – Grid cell size in meters

• rectangle_vertices – List of (lon, lat) tuples defining the area

Returns:

(canopy_height_grid, canopy_bottom_height_grid)

Return type:

tuple