Add type annotations across modules for enhanced clarity and checking

Introduced type hints for functions in core modules (`filters.py`, `process.py`, `handlers.py`, etc.) to improve code clarity and enable static type checking. Adjusted related docstrings and examples to align with the updates. Updated `mkdocs.yml` to include Code of Conduct in documentation.

Author: iosefa

docs/examples.md

@@ -8,7 +8,7 @@ import pyforestscan
 
 Then, you can use it to load point cloud data and extract forest structure metrics. 
 
-The following sections will provide an overview of usage of the major functions of pyforestscan. For a complete reference of all functions in pyforestscan, please check the [API documentation](api.md). For comprehensive examples of these functions, please see the [example jupyter notebooks](examples). 
+The following sections will provide an overview of usage of the major functions of pyforestscan. For a complete reference of all functions in pyforestscan, please check the [API documentation](/api/calculate/). For comprehensive examples of these functions, please see the [example jupyter notebooks](/examples/getting-started-importing-preprocessing-dtm-chm/). 
 
 ## Importing Point Cloud Data
 

docs/usage/getting-started-import-and-preprocess.md

@@ -47,6 +47,7 @@ nav:
             - usage/forest-structure/fhd.md
     - Benchmarks: benchmarks.md
     - Contributing: contributing.md
+    - Code of Conduct: code_of_conduct.md
     - Changelog: https://github.com/iosefa/PyForestScan/releases
     - Report Issues: https://github.com/iosefa/PyForestScan/issues
     - Examples:

mkdocs.yml

@@ -1,10 +1,12 @@
 import numpy as np
+
 from scipy.interpolate import griddata
 from scipy.stats import entropy
 from scipy import ndimage
+from typing import List, Tuple
 
 
-def generate_dtm(ground_points, resolution=2.0):
+def generate_dtm(ground_points, resolution=2.0) -> Tuple[np.ndarray, List]:
     """
     Generates a Digital Terrain Model (DTM) raster from classified ground points.
 
@@ -50,7 +52,7 @@ def generate_dtm(ground_points, resolution=2.0):
     return dtm, extent
 
 
-def assign_voxels(arr, voxel_resolution):
+def assign_voxels(arr, voxel_resolution) -> Tuple[np.ndarray, List]:
     """
     Assigns voxel grids to spatial data points based on the specified resolutions.
 
@@ -59,7 +61,7 @@ def assign_voxels(arr, voxel_resolution):
         voxel_resolution (tuple of floats): The resolution for x, y, and z dimensions of the voxel grid.
 
     Returns:
-        tuple of (numpy.ndarray, list): A tuple containing the histogram of the voxel grid (with corrected orientation) and the extent of the point cloud.
+        tuple of (numpy.ndarray, List): A tuple containing the histogram of the voxel grid (with corrected orientation) and the extent of the point cloud.
     """
     dx, dy, dz = voxel_resolution
 
@@ -86,7 +88,7 @@ def calculate_pad(voxel_returns,
                   voxel_height=1.0,
                   beer_lambert_constant=1.0,
                   drop_ground=True
-                  ):
+                  ) -> np.ndarray:
     """
     Calculate the Plant Area Density (PAD) using the Beer-Lambert Law.
 
@@ -136,7 +138,7 @@ def calculate_pad(voxel_returns,
 def calculate_pai(pad,
                   voxel_height,
                   min_height=1.0,
-                  max_height=None):
+                  max_height=None) -> np.ndarray:
     """
     Calculate Plant Area Index (PAI) from Plant Area Density (PAD) data by summing PAD values along the height (Z) axis.
 
@@ -166,7 +168,7 @@ def calculate_pai(pad,
     return pai
 
 
-def calculate_fhd(voxel_returns):
+def calculate_fhd(voxel_returns) -> np.ndarray:
     """
     Calculate the Foliage Height Diversity (FHD) for a given set of voxel returns.
 
@@ -197,7 +199,7 @@ def calculate_fhd(voxel_returns):
 
 
 def calculate_chm(arr, voxel_resolution, interpolation="linear",
-                  interp_valid_region=False, interp_clean_edges=False):
+                  interp_valid_region=False, interp_clean_edges=False) -> Tuple[np.ndarray, List]:
     """
     Calculate the Canopy Height Model (CHM) for a given voxel grid.
 

pyforestscan/calculate.py

@@ -1,9 +1,11 @@
+from typing import List
+
 from pyforestscan.handlers import _build_pdal_pipeline
 from pyforestscan.pipeline import _filter_hag, _filter_ground, _filter_statistical_outlier, _filter_smrf, \
     _filter_radius, _select_ground
 
 
-def filter_hag(arrays, lower_limit=0, upper_limit=None):
+def filter_hag(arrays, lower_limit=0, upper_limit=None) -> List:
     """
     Apply a Height Above Ground (HAG) filter to a list of point cloud arrays.
 
@@ -27,7 +29,7 @@ def filter_hag(arrays, lower_limit=0, upper_limit=None):
     return pipeline.arrays
 
 
-def filter_ground(arrays):
+def filter_ground(arrays) -> List:
     """
     Remove ground points (classification 2) from a list of point cloud arrays.
 
@@ -41,7 +43,7 @@ def filter_ground(arrays):
     return pipeline.arrays
 
 
-def filter_select_ground(arrays):
+def filter_select_ground(arrays) -> List:
     """
     Select only ground points (classification 2) from a list of point cloud arrays.
 
@@ -55,7 +57,7 @@ def filter_select_ground(arrays):
     return pipeline.arrays
 
 
-def remove_outliers_and_clean(arrays, mean_k=8, multiplier=3.0, remove=False):
+def remove_outliers_and_clean(arrays, mean_k=8, multiplier=3.0, remove=False) -> List:
     """
     Processes input arrays by removing statistical outliers and optionally cleans
     the data, filtering out specific classifications.
@@ -115,7 +117,7 @@ def classify_ground_points(
         slope=0.15,
         threshold=0.5,
         window=18.0
-):
+) -> List:
     """
     Apply the SMRF (Simple Morphological Filter) to classify ground points in the point cloud arrays.
 
@@ -166,7 +168,7 @@ def classify_ground_points(
     return processed_arrays
 
 
-def downsample_poisson(arrays, thin_radius):
+def downsample_poisson(arrays, thin_radius) -> List:
     """
     Downsample point cloud arrays using Poisson (radius-based) thinning.
 

pyforestscan/filters.py

@@ -1,4 +1,5 @@
 import os
+
 import geopandas as gpd
 import json
 import pdal
@@ -8,6 +9,7 @@
 from pyproj import CRS
 from rasterio.transform import from_bounds
 from shapely.geometry import MultiPolygon
+from typing import List, Tuple
 from urllib.parse import urlparse
 
 from pyforestscan.pipeline import _crop_polygon, _filter_radius, _hag_delaunay, _hag_raster
@@ -22,7 +24,7 @@ def _is_url(input_str):
         return False
 
 
-def simplify_crs(crs_list):
+def simplify_crs(crs_list) -> List:
     """
     Convert a list of coordinate reference system (CRS) representations to their corresponding EPSG codes.
 
@@ -48,7 +50,7 @@ def simplify_crs(crs_list):
     return epsg_codes
 
 
-def load_polygon_from_file(vector_file_path, index=0):
+def load_polygon_from_file(vector_file_path, index=0) -> Tuple[str, str]:
     """
     Load a polygon geometry and its CRS from a given vector file.
 
@@ -79,7 +81,7 @@ def load_polygon_from_file(vector_file_path, index=0):
     return polygon.wkt, gdf.crs.to_string()
 
 
-def get_raster_epsg(dtm_path):
+def get_raster_epsg(dtm_path) -> str:
     """
     Retrieve the EPSG code from a raster file.
 
@@ -164,7 +166,7 @@ def _build_pdal_pipeline(arrays, pipeline_stages):
     return pipeline
 
 
-def validate_crs(crs_list):
+def validate_crs(crs_list) -> bool:
     """
     Validate that all CRS (Coordinate Reference System) representations in the list are identical.
 
@@ -183,7 +185,9 @@ def validate_crs(crs_list):
     return True
 
 
-def read_lidar(input_file, srs, bounds=None, thin_radius=None, hag=False, hag_dtm=False, dtm=None, crop_poly=False, poly=None):
+def read_lidar(input_file, srs, bounds=None, thin_radius=None,
+               hag=False, hag_dtm=False, dtm=None, crop_poly=False,
+               poly=None) -> np.ndarray or None:
     """
     Read and process a LiDAR point cloud file using PDAL with various options.
 
@@ -285,7 +289,7 @@ def read_lidar(input_file, srs, bounds=None, thin_radius=None, hag=False, hag_dt
     return point_cloud if point_cloud else None
 
 
-def write_las(arrays, output_file, srs=None, compress=True):
+def write_las(arrays, output_file, srs=None, compress=True) -> None:
     """
     Write point cloud data to a LAS or LAZ file.
 
@@ -342,7 +346,7 @@ def write_las(arrays, output_file, srs=None, compress=True):
     pipeline.execute()
 
 
-def create_geotiff(layer, output_file, crs, spatial_extent, nodata=-9999):
+def create_geotiff(layer, output_file, crs, spatial_extent, nodata=-9999) -> None:
     """
     Create a GeoTIFF file from the given data layer.
 

pyforestscan/handlers.py

@@ -50,7 +50,7 @@ def _crop_dtm(dtm_path, tile_min_x, tile_min_y, tile_max_x, tile_max_y):
 
 def process_with_tiles(ept_file, tile_size, output_path, metric, voxel_size,
                        voxel_height=1, buffer_size=0.1, srs=None, hag=False,
-                       hag_dtm=False, dtm=None, bounds=None, interpolation=None, remove_outliers=False):
+                       hag_dtm=False, dtm=None, bounds=None, interpolation=None, remove_outliers=False) -> None:
     """
     Process a large EPT point cloud by tiling, compute CHM or other metrics for each tile,
     and write the results to the specified output directory.

pyforestscan/process.py

@@ -21,7 +21,7 @@ def _read_ept_json(ept_source):
     return ept_json
 
 
-def get_srs_from_ept(ept_file):
+def get_srs_from_ept(ept_file) -> str or None:
     """
     Extract the Spatial Reference System (SRS) from an EPT (Entwine Point Tile) file.
 
@@ -46,7 +46,7 @@ def get_srs_from_ept(ept_file):
         return None
 
 
-def get_bounds_from_ept(ept_file):
+def get_bounds_from_ept(ept_file) -> tuple[float, float, float, float, float, float]:
     """
     Extract the spatial bounds of a point cloud from an EPT (Entwine Point Tile) file using PDAL.
 
@@ -75,7 +75,7 @@ def tile_las_in_memory(
         overlap,
         output_dir,
         srs=None
-):
+) -> None:
     """
     Read an entire LAS/LAZ/COPC file into memory and subdivide it into tiles
     with a specified overlap on the right and bottom edges. Writes each tile as a new LAS file.

pyforestscan/utils.py

@@ -9,7 +9,7 @@ def plot_2d(points, x_dim='X',
             fig_size=None, fig_title=None,
             slice_dim=None, slice_val=0.0,
             slice_tolerance=5, save_fname=None
-):
+) -> None:
     """
     Plot a 2D scatter plot of point cloud data with customizable axes, coloring, slicing, and figure settings.
 
@@ -84,7 +84,7 @@ def plot_2d(points, x_dim='X',
 
 
 def plot_metric(title, metric, extent, metric_name=None, cmap='viridis', fig_size=None,
-                save_fname=None):
+                save_fname=None) -> None:
     """
     Plot a 2D metric array as an image with geospatial extent, colorbar, and customizable settings.
 
@@ -126,7 +126,8 @@ def plot_metric(title, metric, extent, metric_name=None, cmap='viridis', fig_siz
 
 
 def plot_pad(pad, slice_index=None, axis='x', cmap='viridis',
-             hag_values=None, horizontal_values=None, title=None, save_fname=None):
+             hag_values=None, horizontal_values=None, title=None,
+             save_fname=None) -> None:
     """
     Visualize 3D Plant Area Density (PAD) data as a 2D image, using projection or slicing.