voxcity.geoprocessor.raster.core
================================

.. py:module:: voxcity.geoprocessor.raster.core


Functions
---------

.. autoapisummary::

   voxcity.geoprocessor.raster.core.apply_operation
   voxcity.geoprocessor.raster.core.translate_array
   voxcity.geoprocessor.raster.core.group_and_label_cells
   voxcity.geoprocessor.raster.core.process_grid_optimized
   voxcity.geoprocessor.raster.core.process_grid
   voxcity.geoprocessor.raster.core.calculate_grid_size
   voxcity.geoprocessor.raster.core.create_coordinate_mesh
   voxcity.geoprocessor.raster.core.create_cell_polygon
   voxcity.geoprocessor.raster.core.compute_grid_geometry
   voxcity.geoprocessor.raster.core.compute_cell_center_coords
   voxcity.geoprocessor.raster.core.compute_grid_shape
   voxcity.geoprocessor.raster.core.normalize_gdf_crs
   voxcity.geoprocessor.raster.core.bbox_from_vertices


Module 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_geometry(rectangle_vertices, meshsize: float) -> voxcity.utils.projector.GridGeom | None

   Compute full grid geometry from rectangle vertices and mesh size.

   Returns a :class:`~voxcity.utils.projector.GridGeom` dict with keys:
   origin, side_1, side_2, u_vec, v_vec, grid_size, adj_mesh, meshsize_m —
   or *None* if inputs are insufficient.


.. py:function:: compute_cell_center_coords(rectangle_vertices, meshsize: float) -> dict

   Compute (lon, lat) coordinates for each grid cell center.

   Works correctly for both axis-aligned and rotated rectangles.
   Cell (i, j) centre = origin + (i+0.5)*dx*u_vec + (j+0.5)*dy*v_vec.

   Returns a dict with all keys from :func:`compute_grid_geometry` plus:
   - ``lons`` : ndarray of shape *grid_size* with cell-centre longitudes
   - ``lats`` : ndarray of shape *grid_size* with cell-centre latitudes

   Returns *None* when *rectangle_vertices* is insufficient.


.. 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:: normalize_gdf_crs(gdf, assume_epsg: int = 4326)

   Return *gdf* re-projected to *assume_epsg*.

   If the GeoDataFrame has no CRS, EPSG:4326 is assumed with a warning.


.. py:function:: bbox_from_vertices(rectangle_vertices: List[Tuple[float, float]]) -> shapely.geometry.box

   Return a shapely box covering *rectangle_vertices* (lon, lat) pairs.