voxcity.geoprocessor.raster =========================== .. py:module:: voxcity.geoprocessor.raster .. autoapi-nested-parse:: 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 ---------- .. toctree:: :maxdepth: 1 /autoapi/voxcity/geoprocessor/raster/buildings/index /autoapi/voxcity/geoprocessor/raster/canopy/index /autoapi/voxcity/geoprocessor/raster/core/index /autoapi/voxcity/geoprocessor/raster/export/index /autoapi/voxcity/geoprocessor/raster/landcover/index /autoapi/voxcity/geoprocessor/raster/raster/index Functions --------- .. autoapisummary:: voxcity.geoprocessor.raster.apply_operation voxcity.geoprocessor.raster.translate_array voxcity.geoprocessor.raster.group_and_label_cells voxcity.geoprocessor.raster.process_grid_optimized voxcity.geoprocessor.raster.process_grid voxcity.geoprocessor.raster.calculate_grid_size voxcity.geoprocessor.raster.create_coordinate_mesh voxcity.geoprocessor.raster.create_cell_polygon voxcity.geoprocessor.raster.compute_grid_shape voxcity.geoprocessor.raster.tree_height_grid_from_land_cover voxcity.geoprocessor.raster.create_land_cover_grid_from_geotiff_polygon voxcity.geoprocessor.raster.create_land_cover_grid_from_gdf_polygon voxcity.geoprocessor.raster.create_height_grid_from_geotiff_polygon voxcity.geoprocessor.raster.create_dem_grid_from_geotiff_polygon voxcity.geoprocessor.raster.create_building_height_grid_from_gdf_polygon voxcity.geoprocessor.raster.create_building_height_grid_from_open_building_temporal_polygon voxcity.geoprocessor.raster.grid_to_geodataframe voxcity.geoprocessor.raster.grid_to_point_geodataframe voxcity.geoprocessor.raster.create_vegetation_height_grid_from_gdf_polygon voxcity.geoprocessor.raster.create_dem_grid_from_gdf_polygon voxcity.geoprocessor.raster.create_canopy_grids_from_tree_gdf Package Contents ---------------- .. py:function:: 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 .. py:function:: 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. .. py:function:: group_and_label_cells(array: numpy.ndarray) -> numpy.ndarray Convert non-zero numbers in a 2D numpy array to sequential IDs starting from 1. .. py:function:: 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. .. py:function:: process_grid(grid_bi: numpy.ndarray, dem_grid: numpy.ndarray) -> numpy.ndarray Safe version that tries optimization first, then falls back to original method. .. py:function:: 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)) .. py:function:: 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) .. py:function:: 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. .. py:function:: 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). :param rectangle_vertices: List of 4 vertices [(lon, lat), ...] defining the rectangle. :param meshsize: Grid cell size in meters. :returns: Tuple of (grid_size_0, grid_size_1) representing grid dimensions. .. py:function:: 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. .. py:function:: 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 :func:`compute_cell_center_coords` so rotated rectangles are handled correctly. .. py:function:: 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. :param gdf: GeoDataFrame with land cover polygons and 'class' column :param meshsize: Grid cell size in meters :param source: Land cover data source name (e.g., 'OpenStreetMap') :param rectangle_vertices: List of (lon, lat) tuples defining the area :param default_class: Default class for cells not covered by any polygon :param 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. :param 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 .. py:function:: 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 :func:`compute_cell_center_coords` so rotated rectangles are handled correctly. .. py:function:: 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 :func:`compute_cell_center_coords` so rotated rectangles are handled correctly. .. py:function:: create_building_height_grid_from_gdf_polygon(gdf: geopandas.GeoDataFrame, meshsize: float, rectangle_vertices: List[Tuple[float, float]], overlapping_footprint: any = 'auto', gdf_comp: Optional[geopandas.GeoDataFrame] = None, geotiff_path_comp: Optional[str] = None, complement_building_footprints: Optional[bool] = None, complement_height: Optional[float] = 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) .. py:function:: 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. .. py:function:: grid_to_geodataframe(grid_ori, rectangle_vertices, meshsize) Converts a 2D grid to a GeoDataFrame with cell polygons and values. Output CRS: EPSG:4326 .. py:function:: 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 .. py:function:: 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 :func:`compute_cell_center_coords` so rotated rectangles are handled correctly. .. py:function:: 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 :func:`compute_cell_center_coords` so rotated rectangles are handled correctly. .. py:function:: 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). :param 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 :param meshsize: Grid cell size in meters :param rectangle_vertices: List of (lon, lat) tuples defining the area :returns: (canopy_height_grid, canopy_bottom_height_grid) :rtype: tuple