voxcity 0.5.14__py3-none-any.whl → 0.5.16__py3-none-any.whl

voxcity/geoprocessor/draw.py

@@ -1,5 +1,26 @@
 """
-This module provides functions for drawing and manipulating rectangles on maps.
+This module provides functions for drawing and manipulating rectangles and polygons on interactive maps.
+It serves as a core component for defining geographical regions of interest in the VoxCity library.
+
+Key Features:
+    - Interactive rectangle drawing on maps using ipyleaflet
+    - Rectangle rotation with coordinate system transformations
+    - City-centered map initialization
+    - Fixed-dimension rectangle creation from center points
+    - Building footprint visualization and polygon drawing
+    - Support for both WGS84 and Web Mercator projections
+    - Coordinate format handling between (lon,lat) and (lat,lon)
+
+The module maintains consistent coordinate order conventions:
+    - Internal storage: (lon,lat) format to match GeoJSON standard
+    - ipyleaflet interface: (lat,lon) format as required by the library
+    - All return values: (lon,lat) format for consistency
+
+Dependencies:
+    - ipyleaflet: For interactive map display and drawing controls
+    - pyproj: For coordinate system transformations
+    - geopy: For distance calculations
+    - shapely: For geometric operations
 """
 
 import math
@@ -13,15 +34,36 @@ from .utils import get_coordinates_from_cityname
 
 def rotate_rectangle(m, rectangle_vertices, angle):
     """
-    Project rectangle to Mercator, rotate, and re-project to lat-lon.
+    Project rectangle to Mercator, rotate, and re-project to lat-lon coordinates.
+    
+    This function performs a rotation of a rectangle in geographic space by:
+    1. Converting coordinates from WGS84 (lat/lon) to Web Mercator projection
+    2. Performing the rotation in the projected space for accurate distance preservation
+    3. Converting back to WGS84 coordinates
+    4. Visualizing the result on the provided map
+    
+    The rotation is performed around the rectangle's centroid using a standard 2D rotation matrix.
+    The function handles coordinate system transformations to ensure geometrically accurate rotations
+    despite the distortions inherent in geographic projections.
 
     Args:
-        m (ipyleaflet.Map): Map object to draw the rotated rectangle on
-        rectangle_vertices (list): List of (lon, lat) tuples defining the rectangle vertices
-        angle (float): Rotation angle in degrees
+        m (ipyleaflet.Map): Map object to draw the rotated rectangle on.
+            The map must be initialized and have a valid center and zoom level.
+        rectangle_vertices (list): List of (lon, lat) tuples defining the rectangle vertices.
+            The vertices should be ordered in a counter-clockwise direction.
+            Example: [(lon1,lat1), (lon2,lat2), (lon3,lat3), (lon4,lat4)]
+        angle (float): Rotation angle in degrees.
+            Positive angles rotate counter-clockwise.
+            Negative angles rotate clockwise.
 
     Returns:
-        list: List of rotated (lon, lat) tuples defining the new rectangle vertices
+        list: List of rotated (lon, lat) tuples defining the new rectangle vertices.
+            The vertices maintain their original ordering.
+            Returns None if no rectangle vertices are provided.
+
+    Note:
+        The function uses EPSG:4326 (WGS84) for geographic coordinates and
+        EPSG:3857 (Web Mercator) for the rotation calculations.
     """
     if not rectangle_vertices:
         print("Draw a rectangle first!")
@@ -73,16 +115,43 @@ def rotate_rectangle(m, rectangle_vertices, angle):
 
 def draw_rectangle_map(center=(40, -100), zoom=4):
     """
-    Create an interactive map for drawing rectangles.
+    Create an interactive map for drawing rectangles with ipyleaflet.
+    
+    This function initializes an interactive map that allows users to draw rectangles
+    by clicking and dragging on the map surface. The drawn rectangles are captured
+    and their vertices are stored in geographic coordinates.
+
+    The map interface provides:
+    - A rectangle drawing tool activated by default
+    - Real-time coordinate capture of drawn shapes
+    - Automatic vertex ordering in counter-clockwise direction
+    - Console output of vertex coordinates for verification
+    
+    Drawing Controls:
+    - Click and drag to draw a rectangle
+    - Release to complete the rectangle
+    - Only one rectangle can be active at a time
+    - Drawing a new rectangle clears the previous one
 
     Args:
-        center (tuple): Center coordinates (lat, lon) for the map view. Defaults to (40, -100).
+        center (tuple): Center coordinates (lat, lon) for the map view.
+            Defaults to (40, -100) which centers on the continental United States.
+            Format: (latitude, longitude) in decimal degrees.
         zoom (int): Initial zoom level for the map. Defaults to 4.
+            Range: 0 (most zoomed out) to 18 (most zoomed in).
+            Recommended: 3-6 for countries, 10-15 for cities.
 
     Returns:
         tuple: (Map object, list of rectangle vertices)
-            - Map object for displaying and interacting with the map
-            - Empty list that will be populated with rectangle vertices when drawn
+            - Map object: ipyleaflet.Map instance for displaying and interacting with the map
+            - rectangle_vertices: Empty list that will be populated with (lon,lat) tuples
+              when a rectangle is drawn. Coordinates are stored in GeoJSON order (lon,lat).
+
+    Note:
+        The function disables all drawing tools except rectangles to ensure
+        consistent shape creation. The rectangle vertices are automatically
+        converted to (lon,lat) format when stored, regardless of the input
+        center coordinate order.
     """
     # Initialize the map centered at specified coordinates
     m = Map(center=center, zoom=zoom)
@@ -127,15 +196,34 @@ def draw_rectangle_map(center=(40, -100), zoom=4):
 def draw_rectangle_map_cityname(cityname, zoom=15):
     """
     Create an interactive map centered on a specified city for drawing rectangles.
+    
+    This function extends draw_rectangle_map() by automatically centering the map
+    on a specified city using geocoding. It provides a convenient way to focus
+    the drawing interface on a particular urban area without needing to know
+    its exact coordinates.
+
+    The function uses the utils.get_coordinates_from_cityname() function to
+    geocode the city name and obtain its coordinates. The resulting map is
+    zoomed to an appropriate level for urban-scale analysis.
 
     Args:
-        cityname (str): Name of the city to center the map on
+        cityname (str): Name of the city to center the map on.
+            Can include country or state for better accuracy.
+            Examples: "Tokyo, Japan", "New York, NY", "Paris, France"
         zoom (int): Initial zoom level for the map. Defaults to 15.
+            Range: 0 (most zoomed out) to 18 (most zoomed in).
+            Default of 15 is optimized for city-level visualization.
 
     Returns:
         tuple: (Map object, list of rectangle vertices)
-            - Map object centered on the specified city
-            - Empty list that will be populated with rectangle vertices when drawn
+            - Map object: ipyleaflet.Map instance centered on the specified city
+            - rectangle_vertices: Empty list that will be populated with (lon,lat)
+              tuples when a rectangle is drawn
+
+    Note:
+        If the city name cannot be geocoded, the function will raise an error.
+        For better results, provide specific city names with country/state context.
+        The function inherits all drawing controls and behavior from draw_rectangle_map().
     """
     # Get coordinates for the specified city
     center = get_coordinates_from_cityname(cityname)
@@ -145,17 +233,51 @@ def draw_rectangle_map_cityname(cityname, zoom=15):
 def center_location_map_cityname(cityname, east_west_length, north_south_length, zoom=15):
     """
     Create an interactive map centered on a city where clicking creates a rectangle of specified dimensions.
+    
+    This function provides a specialized interface for creating fixed-size rectangles
+    centered on user-selected points. Instead of drawing rectangles by dragging,
+    users click a point on the map and a rectangle of the specified dimensions
+    is automatically created centered on that point.
+
+    The function handles:
+    - Automatic city geocoding and map centering
+    - Distance calculations in meters using geopy
+    - Conversion between geographic and metric distances
+    - Rectangle creation with specified dimensions
+    - Visualization of created rectangles
+
+    Workflow:
+    1. Map is centered on the specified city
+    2. User clicks a point on the map
+    3. A rectangle is created centered on that point
+    4. Rectangle dimensions are maintained in meters regardless of latitude
+    5. Previous rectangles are automatically cleared
 
     Args:
-        cityname (str): Name of the city to center the map on
-        east_west_length (float): Width of the rectangle in meters
-        north_south_length (float): Height of the rectangle in meters
+        cityname (str): Name of the city to center the map on.
+            Can include country or state for better accuracy.
+            Examples: "Tokyo, Japan", "New York, NY"
+        east_west_length (float): Width of the rectangle in meters.
+            This is the dimension along the east-west direction.
+            The actual ground distance is maintained regardless of projection distortion.
+        north_south_length (float): Height of the rectangle in meters.
+            This is the dimension along the north-south direction.
+            The actual ground distance is maintained regardless of projection distortion.
         zoom (int): Initial zoom level for the map. Defaults to 15.
+            Range: 0 (most zoomed out) to 18 (most zoomed in).
+            Default of 15 is optimized for city-level visualization.
 
     Returns:
         tuple: (Map object, list of rectangle vertices)
-            - Map object centered on the specified city
-            - Empty list that will be populated with rectangle vertices when a point is clicked
+            - Map object: ipyleaflet.Map instance centered on the specified city
+            - rectangle_vertices: Empty list that will be populated with (lon,lat)
+              tuples when a point is clicked and the rectangle is created
+
+    Note:
+        - Rectangle dimensions are specified in meters but stored as geographic coordinates
+        - The function uses geopy's distance calculations for accurate metric distances
+        - Only one rectangle can exist at a time; clicking a new point removes the previous rectangle
+        - Rectangle vertices are returned in GeoJSON (lon,lat) order
     """
     
     # Get coordinates for the specified city
@@ -225,21 +347,52 @@ def center_location_map_cityname(cityname, east_west_length, north_south_length,
 
 def display_buildings_and_draw_polygon(building_gdf=None, rectangle_vertices=None, zoom=17):
     """
-    Displays building footprints (in Lon-Lat order) on an ipyleaflet map,
-    and allows the user to draw a polygon whose vertices are returned
-    in a Python list (also in Lon-Lat).
+    Displays building footprints and enables polygon drawing on an interactive map.
+    
+    This function creates an interactive map that visualizes building footprints and
+    allows users to draw arbitrary polygons. It's particularly useful for selecting
+    specific buildings or areas within an urban context.
+
+    The function provides three key features:
+    1. Building Footprint Visualization:
+       - Displays building polygons from a GeoDataFrame
+       - Uses consistent styling for all buildings
+       - Handles simple polygon geometries only
+    
+    2. Interactive Polygon Drawing:
+       - Enables free-form polygon drawing
+       - Captures vertices in consistent (lon,lat) format
+       - Maintains GeoJSON compatibility
+    
+    3. Map Initialization:
+       - Automatic centering based on input data
+       - Fallback to default location if no data provided
+       - Support for both building data and rectangle bounds
 
     Args:
-        building_gdf (GeoDataFrame, optional): A GeoDataFrame containing building footprints,
-                                             with geometry in [lon, lat] order.
+        building_gdf (GeoDataFrame, optional): A GeoDataFrame containing building footprints.
+            Must have geometry column with Polygon type features.
+            Geometries should be in [lon, lat] coordinate order.
+            If None, only the base map is displayed.
         rectangle_vertices (list, optional): List of [lon, lat] coordinates defining rectangle corners.
+            Used to set the initial map view extent.
+            Takes precedence over building_gdf for determining map center.
         zoom (int): Initial zoom level for the map. Default=17.
+            Range: 0 (most zoomed out) to 18 (most zoomed in).
+            Default of 17 is optimized for building-level detail.
 
     Returns:
-        (map_object, drawn_polygon_vertices)
-          - map_object: ipyleaflet Map instance
-          - drawn_polygon_vertices: a Python list that gets updated whenever
-            a new polygon is created. The list is in (lon, lat) order.
+        tuple: (map_object, drawn_polygon_vertices)
+            - map_object: ipyleaflet Map instance with building footprints and drawing controls
+            - drawn_polygon_vertices: List that gets updated with (lon,lat) coordinates
+              whenever a new polygon is drawn. Coordinates are in GeoJSON order.
+
+    Note:
+        - Building footprints are displayed in blue with 20% opacity
+        - Only simple Polygon geometries are supported (no MultiPolygons)
+        - Drawing tools are restricted to polygon creation only
+        - All coordinates are handled in (lon,lat) order internally
+        - The function automatically determines appropriate map bounds
     """
     # ---------------------------------------------------------
     # 1. Determine a suitable map center via bounding box logic

voxcity/geoprocessor/grid.py

@@ -1,5 +1,10 @@
 """
 This module provides functions for creating and manipulating grids of building heights, land cover, and elevation data.
+It includes functionality for:
+- Grid creation and manipulation for various data types (buildings, land cover, elevation)
+- Coordinate transformations and spatial operations
+- Data interpolation and aggregation
+- Vector to raster conversion
 """
 
 import numpy as np
@@ -44,7 +49,13 @@ from ..downloader.gee import (
 
 def apply_operation(arr, meshsize):
     """
-    Applies a sequence of operations to an array based on a mesh size.
+    Applies a sequence of operations to an array based on a mesh size to normalize and discretize values.
+    
+    This function performs the following sequence of operations:
+    1. Divides array by mesh size to normalize values
+    2. Adds 0.5 to round values to nearest integer
+    3. Floors the result to get integer values
+    4. Scales back to original units by multiplying by mesh size
     
     Args:
         arr (numpy.ndarray): Input array to transform
@@ -52,6 +63,11 @@ def apply_operation(arr, meshsize):
         
     Returns:
         numpy.ndarray: Transformed array after applying operations
+        
+    Example:
+        >>> arr = np.array([1.2, 2.7, 3.4])
+        >>> meshsize = 0.5
+        >>> result = apply_operation(arr, meshsize)
     """
     # Divide array by mesh size to normalize values
     step1 = arr / meshsize
@@ -66,12 +82,22 @@ def translate_array(input_array, translation_dict):
     """
     Translates values in an array according to a dictionary mapping.
     
+    This function creates a new array where each value from the input array
+    is replaced by its corresponding value from the translation dictionary.
+    Values not found in the dictionary are replaced with empty strings.
+    
     Args:
         input_array (numpy.ndarray): Array containing values to translate
         translation_dict (dict): Dictionary mapping input values to output values
         
     Returns:
-        numpy.ndarray: Array with translated values
+        numpy.ndarray: Array with translated values, with same shape as input array
+        
+    Example:
+        >>> arr = np.array([[1, 2], [3, 4]])
+        >>> trans_dict = {1: 'A', 2: 'B', 3: 'C', 4: 'D'}
+        >>> result = translate_array(arr, trans_dict)
+        >>> # result = array([['A', 'B'], ['C', 'D']], dtype=object)
     """
     # Create empty array of same shape that can hold objects (e.g. strings)
     translated_array = np.empty_like(input_array, dtype=object)
@@ -86,13 +112,22 @@ def translate_array(input_array, translation_dict):
 def group_and_label_cells(array):
     """
     Convert non-zero numbers in a 2D numpy array to sequential IDs starting from 1.
-    Zero values remain unchanged.
+    
+    This function creates a new array where all non-zero values are replaced with
+    sequential IDs (1, 2, 3, etc.) while preserving zero values. This is useful
+    for labeling distinct regions or features in a grid.
     
     Args:
-        array (numpy.ndarray): Input 2D array
+        array (numpy.ndarray): Input 2D array with non-zero values to be labeled
         
     Returns:
-        numpy.ndarray: Array with non-zero values converted to sequential IDs
+        numpy.ndarray: Array with non-zero values converted to sequential IDs,
+                      maintaining the same shape as input array
+        
+    Example:
+        >>> arr = np.array([[0, 5, 5], [0, 5, 8], [0, 0, 8]])
+        >>> result = group_and_label_cells(arr)
+        >>> # result = array([[0, 1, 1], [0, 1, 2], [0, 0, 2]])
     """
     # Create a copy to avoid modifying input
     result = array.copy()
@@ -113,12 +148,25 @@ def process_grid(grid_bi, dem_grid):
     """
     Process a binary grid and DEM grid to create averaged elevation values.
     
+    This function takes a binary grid identifying regions and a corresponding DEM
+    grid with elevation values. For each non-zero region in the binary grid, it
+    calculates the mean elevation from the DEM grid and assigns this average to
+    all cells in that region. The result is normalized by subtracting the minimum value.
+    
     Args:
-        grid_bi (numpy.ndarray): Binary grid indicating regions
-        dem_grid (numpy.ndarray): Grid of elevation values
+        grid_bi (numpy.ndarray): Binary grid indicating regions (0 for background,
+                                non-zero for different regions)
+        dem_grid (numpy.ndarray): Grid of elevation values corresponding to the
+                                same spatial extent as grid_bi
         
     Returns:
-        numpy.ndarray: Processed grid with averaged elevation values
+        numpy.ndarray: Processed grid with averaged and normalized elevation values.
+                      Same shape as input grids.
+        
+    Example:
+        >>> binary_grid = np.array([[1, 1, 0], [1, 1, 2], [0, 2, 2]])
+        >>> elevation = np.array([[100, 110, 90], [105, 115, 120], [95, 125, 130]])
+        >>> result = process_grid(binary_grid, elevation)
     """
     # Get unique non-zero region IDs
     unique_ids = np.unique(grid_bi[grid_bi != 0])
@@ -137,15 +185,29 @@ def calculate_grid_size(side_1, side_2, u_vec, v_vec, meshsize):
     """
     Calculate grid size and adjusted mesh size based on input parameters.
     
+    This function determines the number of grid cells needed in each direction and
+    adjusts the mesh size to exactly fit the desired area. The calculation takes into
+    account the input vectors and desired mesh size to ensure proper coverage.
+    
     Args:
-        side_1 (numpy.ndarray): First side vector
-        side_2 (numpy.ndarray): Second side vector
+        side_1 (numpy.ndarray): First side vector defining the grid extent
+        side_2 (numpy.ndarray): Second side vector defining the grid extent
         u_vec (numpy.ndarray): Unit vector in first direction
         v_vec (numpy.ndarray): Unit vector in second direction
-        meshsize (float): Desired mesh size
+        meshsize (float): Desired mesh size in the same units as the vectors
         
     Returns:
-        tuple: Grid size (tuple of ints) and adjusted mesh size (tuple of floats)
+        tuple: A tuple containing:
+            - grid_size (tuple of ints): Number of cells in each direction (nx, ny)
+            - adjusted_mesh_size (tuple of floats): Actual mesh sizes that fit the area exactly
+        
+    Example:
+        >>> side1 = np.array([100, 0])  # 100 units in x direction
+        >>> side2 = np.array([0, 50])   # 50 units in y direction
+        >>> u = np.array([1, 0])        # Unit vector in x
+        >>> v = np.array([0, 1])        # Unit vector in y
+        >>> mesh = 10                    # Desired 10-unit mesh
+        >>> grid_size, adj_mesh = calculate_grid_size(side1, side2, u, v, mesh)
     """
     # Calculate number of cells needed in each direction, rounding to nearest integer
     grid_size_0 = int(np.linalg.norm(side_1) / np.linalg.norm(meshsize * u_vec) + 0.5)
@@ -161,15 +223,29 @@ def create_coordinate_mesh(origin, grid_size, adjusted_meshsize, u_vec, v_vec):
     """
     Create a coordinate mesh based on input parameters.
     
+    This function generates a 3D array representing a coordinate mesh, where each point
+    in the mesh is calculated by adding scaled vectors to the origin point. The mesh
+    is created using the specified grid size and adjusted mesh sizes.
+    
     Args:
-        origin (numpy.ndarray): Origin point coordinates
-        grid_size (tuple): Size of grid in each dimension
-        adjusted_meshsize (tuple): Adjusted mesh size in each dimension
+        origin (numpy.ndarray): Origin point coordinates (shape: (2,) or (3,))
+        grid_size (tuple): Size of grid in each dimension (nx, ny)
+        adjusted_meshsize (tuple): Adjusted mesh size in each dimension (dx, dy)
         u_vec (numpy.ndarray): Unit vector in first direction
         v_vec (numpy.ndarray): Unit vector in second direction
         
     Returns:
-        numpy.ndarray: Coordinate mesh
+        numpy.ndarray: 3D array of shape (coord_dim, ny, nx) containing the coordinates
+                      of each point in the mesh. coord_dim is the same as the
+                      dimensionality of the input vectors.
+        
+    Example:
+        >>> origin = np.array([0, 0])
+        >>> grid_size = (5, 4)
+        >>> mesh_size = (10, 10)
+        >>> u = np.array([1, 0])
+        >>> v = np.array([0, 1])
+        >>> coords = create_coordinate_mesh(origin, grid_size, mesh_size, u, v)
     """
     # Create evenly spaced points along each axis
     x = np.linspace(0, grid_size[0], grid_size[0])
@@ -189,16 +265,29 @@ def create_cell_polygon(origin, i, j, adjusted_meshsize, u_vec, v_vec):
     """
     Create a polygon representing a grid cell.
     
+    This function generates a rectangular polygon for a specific grid cell by calculating
+    its four corners based on the cell indices and grid parameters. The polygon is
+    created in counter-clockwise order starting from the bottom-left corner.
+    
     Args:
-        origin (numpy.ndarray): Origin point coordinates
-        i (int): Row index
-        j (int): Column index
-        adjusted_meshsize (tuple): Adjusted mesh size in each dimension
+        origin (numpy.ndarray): Origin point coordinates (shape: (2,) or (3,))
+        i (int): Row index of the cell
+        j (int): Column index of the cell
+        adjusted_meshsize (tuple): Adjusted mesh size in each dimension (dx, dy)
         u_vec (numpy.ndarray): Unit vector in first direction
         v_vec (numpy.ndarray): Unit vector in second direction
         
     Returns:
-        shapely.geometry.Polygon: Polygon representing the grid cell
+        shapely.geometry.Polygon: Polygon representing the grid cell, with vertices
+                                ordered counter-clockwise from bottom-left
+        
+    Example:
+        >>> origin = np.array([0, 0])
+        >>> i, j = 1, 2  # Cell at row 1, column 2
+        >>> mesh_size = (10, 10)
+        >>> u = np.array([1, 0])
+        >>> v = np.array([0, 1])
+        >>> cell_poly = create_cell_polygon(origin, i, j, mesh_size, u, v)
     """
     # Calculate the four corners of the cell by adding scaled vectors
     bottom_left = origin + i * adjusted_meshsize[0] * u_vec + j * adjusted_meshsize[1] * v_vec
@@ -213,11 +302,25 @@ def tree_height_grid_from_land_cover(land_cover_grid_ori):
     """
     Convert a land cover grid to a tree height grid.
     
+    This function transforms a land cover classification grid into a grid of tree heights
+    by mapping land cover classes to predefined tree heights. The function first flips
+    the input grid vertically and adjusts class values, then applies a translation
+    dictionary to convert classes to heights.
+    
+    Land cover class to tree height mapping:
+    - Class 4 (Forest): 10m height
+    - All other classes: 0m height
+    
     Args:
-        land_cover_grid_ori (numpy.ndarray): Original land cover grid
+        land_cover_grid_ori (numpy.ndarray): Original land cover grid with class values
         
     Returns:
-        numpy.ndarray: Grid of tree heights
+        numpy.ndarray: Grid of tree heights in meters, with same dimensions as input
+        
+    Example:
+        >>> lc_grid = np.array([[1, 4, 2], [4, 3, 4], [2, 1, 3]])
+        >>> tree_heights = tree_height_grid_from_land_cover(lc_grid)
+        >>> # Result: array([[0, 10, 0], [10, 0, 10], [0, 0, 0]])
     """
     # Flip array vertically and add 1 to all values
     land_cover_grid = np.flipud(land_cover_grid_ori) + 1
@@ -882,17 +985,35 @@ def create_dem_grid_from_geotiff_polygon(tiff_path, mesh_size, rectangle_vertice
     return np.flipud(grid)
 
 def grid_to_geodataframe(grid_ori, rectangle_vertices, meshsize):
-    """Converts a 2D grid to a GeoDataFrame with cell polygons and values.
+    """
+    Converts a 2D grid to a GeoDataFrame with cell polygons and values.
+    
+    This function transforms a regular grid into a GeoDataFrame where each cell is
+    represented as a polygon. The transformation handles coordinate systems properly,
+    converting between WGS84 (EPSG:4326) and Web Mercator (EPSG:3857) for accurate
+    distance calculations.
     
     Args:
-        grid: 2D numpy array containing grid values
-        rectangle_vertices: List of [lon, lat] coordinates defining area corners
-        meshsize: Size of each grid cell in meters
+        grid_ori (numpy.ndarray): 2D array containing grid values
+        rectangle_vertices (list): List of [lon, lat] coordinates defining area corners.
+                                 Should be in WGS84 (EPSG:4326) format.
+        meshsize (float): Size of each grid cell in meters
         
     Returns:
-        GeoDataFrame with columns:
-            - geometry: Polygon geometry of each grid cell
-            - value: Value from the grid
+        GeoDataFrame: A GeoDataFrame with columns:
+            - geometry: Polygon geometry of each grid cell in WGS84 (EPSG:4326)
+            - value: Value from the original grid
+            
+    Example:
+        >>> grid = np.array([[1, 2], [3, 4]])
+        >>> vertices = [[lon1, lat1], [lon2, lat2], [lon3, lat3], [lon4, lat4]]
+        >>> mesh_size = 100  # 100 meters
+        >>> gdf = grid_to_geodataframe(grid, vertices, mesh_size)
+    
+    Notes:
+        - The input grid is flipped vertically before processing to match geographic
+          orientation (north at top)
+        - The output GeoDataFrame uses WGS84 (EPSG:4326) coordinate system
     """
     grid = np.flipud(grid_ori.copy())
     
@@ -951,17 +1072,36 @@ def grid_to_geodataframe(grid_ori, rectangle_vertices, meshsize):
     return gdf
 
 def grid_to_point_geodataframe(grid_ori, rectangle_vertices, meshsize):
-    """Converts a 2D grid to a GeoDataFrame with point geometries at cell centers and values.
+    """
+    Converts a 2D grid to a GeoDataFrame with point geometries at cell centers and values.
+    
+    This function transforms a regular grid into a GeoDataFrame where each cell is
+    represented by a point at its center. The transformation handles coordinate systems
+    properly, converting between WGS84 (EPSG:4326) and Web Mercator (EPSG:3857) for
+    accurate distance calculations.
     
     Args:
-        grid: 2D numpy array containing grid values
-        rectangle_vertices: List of [lon, lat] coordinates defining area corners
-        meshsize: Size of each grid cell in meters
+        grid_ori (numpy.ndarray): 2D array containing grid values
+        rectangle_vertices (list): List of [lon, lat] coordinates defining area corners.
+                                 Should be in WGS84 (EPSG:4326) format.
+        meshsize (float): Size of each grid cell in meters
         
     Returns:
-        GeoDataFrame with columns:
-            - geometry: Point geometry at center of each grid cell
-            - value: Value from the grid
+        GeoDataFrame: A GeoDataFrame with columns:
+            - geometry: Point geometry at center of each grid cell in WGS84 (EPSG:4326)
+            - value: Value from the original grid
+            
+    Example:
+        >>> grid = np.array([[1, 2], [3, 4]])
+        >>> vertices = [[lon1, lat1], [lon2, lat2], [lon3, lat3], [lon4, lat4]]
+        >>> mesh_size = 100  # 100 meters
+        >>> gdf = grid_to_point_geodataframe(grid, vertices, mesh_size)
+    
+    Notes:
+        - The input grid is flipped vertically before processing to match geographic
+          orientation (north at top)
+        - The output GeoDataFrame uses WGS84 (EPSG:4326) coordinate system
+        - Points are placed at the center of each grid cell
     """
     grid = np.flipud(grid_ori.copy())
     
@@ -1220,7 +1360,7 @@ def create_dem_grid_from_gdf_polygon(terrain_gdf, mesh_size, polygon):
     #    (all points, not just inside the polygon)
     # ------------------------------------------------------------------------
     xs = np.linspace(left, right, num_cells_x)
-    ys = np.linspace(top, bottom, num_cells_y)  # top->bottom
+    ys = np.linspace(top, bottom, num_cells_y)  # top→bottom
     X, Y = np.meshgrid(xs, ys)
 
     # Flatten for convenience