Docs/joss paper review 2

.github/workflows/main.yml

@@ -12,6 +12,10 @@ jobs:
   test:
     runs-on: ubuntu-latest
 
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
     steps:
       - name: Check out the repository
         uses: actions/checkout@v3
@@ -20,12 +24,12 @@ jobs:
         uses: conda-incubator/setup-miniconda@v3
         with:
           auto-update-conda: true
-          python-version: "3.10"
+          python-version: ${{ matrix.python-version }}
           channels: conda-forge
 
-      - name: Create Conda environment with Python 3.10 and PDAL
+      - name: Create Conda environment with Python and PDAL
         run: |
-          conda create --name pyforestscan_env python=3.10 pdal gdal -c conda-forge -v
+          conda create --name pyforestscan_env python=${{ matrix.python-version }} pdal gdal -c conda-forge -v
 
       - name: Activate Conda environment and install dependencies
         shell: bash -l {0}
@@ -38,4 +42,9 @@ jobs:
         shell: bash -l {0}
         run: |
           conda activate pyforestscan_env
-          pytest
+          pytest --cov --cov-report=xml
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/publish.yml

@@ -1,4 +1,4 @@
-name: Publish Python Package
+name: Publish Python Package and Docker Image
 
 on:
   push:
@@ -28,4 +28,27 @@ jobs:
           PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
         run: |
           python setup.py sdist bdist_wheel
-          twine upload dist/* -u __token__ -p $PYPI_TOKEN
+          twine upload dist/* -u __token__ -p $PYPI_TOKEN
+
+  docker:
+    runs-on: ubuntu-latest
+    needs: release
+
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v2
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Build Docker image
+        run: docker build -t pyforestscan .
+
+      - name: Tag Docker image
+        run: docker tag pyforestscan iosefa/pyforestscan:latest
+
+      - name: Push Docker image
+        run: docker push iosefa/pyforestscan:latest

.gitignore

@@ -68,9 +68,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
-
 # PyBuilder
 .pybuilder/
 target/
@@ -174,3 +171,11 @@ data/
 
 # tests
 test_data/output.tif
+
+# tifs created from tests
+*.tif
+
+docs/example_data/ept
+
+*.pdf
+*.jats

Dockerfile

@@ -0,0 +1,28 @@
+FROM jupyter/base-notebook:latest
+LABEL maintainer="Iosefa Percival"
+LABEL repo="https://github.com/iosefa/PyForestScan"
+
+USER root
+RUN apt-get update -y && apt-get install -y \
+    gcc g++ make \
+    libgdal-dev libgl1 sqlite3 && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+RUN fix-permissions "${CONDA_DIR}" && \
+    fix-permissions "/home/${NB_USER}"
+
+USER 1000
+RUN mamba install -c conda-forge sqlite gdal pdal -y && \
+    pip install --no-cache-dir pyforestscan jupyter-server-proxy && \
+    mamba update -c conda-forge -y && \
+    jupyter server extension enable --sys-prefix jupyter_server_proxy
+
+RUN mkdir ./examples
+COPY /docs/examples ./examples
+
+ENV PROJ_LIB='/opt/conda/share/proj'
+ENV JUPYTER_ENABLE_LAB=yes
+
+USER root
+RUN chown -R ${NB_UID} ${HOME}
+USER ${NB_USER}

README.md

@@ -1,18 +1,25 @@
 # PyForestScan: Airborne Point Cloud Analysis for Forest Structure
 
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/iosefa/PyForestScan/HEAD?labpath=docs%2Fexamples%2Fgetting-started-importing-preprocessing-dtm-chm.ipynb)
+[![PyPI](https://img.shields.io/pypi/v/PyForestScan.svg)](https://pypi.org/project/PyForestScan/)
+[![Docker Pulls](https://img.shields.io/docker/pulls/iosefa/pyforestscan?logo=docker&label=pulls)](https://hub.docker.com/r/iosefa/pyforestscan)
+[![Contributors](https://img.shields.io/github/contributors/iosefa/PyForestScan.svg?label=contributors)](https://github.com/iosefa/PyForestScan/graphs/contributors)
+[![Tests](https://img.shields.io/github/actions/workflow/status/iosefa/PyForestScan/main.yml?branch=main)](https://github.com/iosefa/PyForestScan/actions/workflows/main.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/iosefa/PyForestScan/main)](https://codecov.io/gh/iosefa/PyForestScan)
+
+**Calculate Forest Structural Metrics from lidar point clouds in Python**
+
 ![Height Above Ground](./screenshots/hag.png)
 
 ## Overview
 
-PyForestScan is a Python library designed for analyzing and visualizing forest structure using airborne 
-3D point cloud data. The library helps derive important forest metrics such as Canopy Height, 
-Plant Area Index (PAI), Canopy Cover, Plant Area Density (PAD), and Foliage Height Diversity (FHD).
+PyForestScan is a Python library designed for analyzing and visualizing forest structure using airborne 3D point cloud data. The library helps derive important forest metrics such as Canopy Height, Plant Area Index (PAI), Canopy Cover, Plant Area Density (PAD), and Foliage Height Diversity (FHD).
 
 ## Features
 
 - **Forest Metrics**: Calculate and visualize key metrics like Canopy Height, PAI, PAD, and FHD.
-- **Airborne Data Compatibility**: Supports LiDAR and Structure from Motion (SfM) data from drones and UAVs.
-- **Visualization**: Create 2D and 3D visualizations of forest structures.
+- **Large Point Cloud Support**: Utilizes efficient data formats such as EPT for large point cloud processing.
+- **Visualization**: Create 2D and 3D visualizations of forest structure and structural metrics
 - **Extensibility**: Easily add custom filters and visualization techniques to suit your needs.
 
 ## Installation
@@ -26,27 +33,34 @@ pip install pyforestscan
 ### Dependencies
 
 > [!IMPORTANT]
-> You MUST have installed PDAL to use PyForestScan. If you use conda to install PDAL, make sure you install pyforestscan in the conda environment with PDAL. See https://pdal.io/en/latest/ for more information.
+> You MUST have installed both PDAL and GDAL to use PyForestScan. If you use conda to install PDAL, make sure you install pyforestscan in the conda environment with PDAL (and GDAL if using conda). See https://pdal.io/en/latest/ for more information on PDAL and https://gdal.org/en/stable/.
 
 - PDAL >= 2.7
+- GDAL >= 3.5
 - Python >= 3.10
 
 ## Quick Start
 
-### Derive Forest Metrics from Airborne Data
+### Calculate, Export, and Plot Plant Area Index
+
+The following snippet shows how you can load a las file, create 5m by 5m by 1m voxels with points assigned to them, and generate plant area density at 1m layers and plant area index for each 5m grid cell before writing the resulting PAI layer to a geotiff and plotting. 
 
-The following snipped shows how you can load a las file, create 25m by 25m by 5m voxels with points assigned to them, and generate plant area density at 5m layers and plant area index for each 25m grid cell before writing the resulting PAI layer to a geotiff. 
 ```python
 from pyforestscan.handlers import read_lidar, create_geotiff
 from pyforestscan.calculate import assign_voxels, calculate_pad, calculate_pai
+from pyforestscan.visualize import plot_metric
 
-arrays = read_lidar("path/to/lidar/file.las", "EPSG:32605", hag=True)
-voxels, extent = assign_voxels(arrays[0], (25, 25, 5))
-pad = calculate_pad(voxels, 5)
+arrays = read_lidar("example_data/20191210_5QKB020880.laz", "EPSG:32605", hag=True)
+voxel_resolution = (5, 5, 1)
+voxels, extent = assign_voxels(arrays[0], voxel_resolution)
+pad = calculate_pad(voxels, voxel_resolution[-1])
 pai = calculate_pai(pad)
 create_geotiff(pai, "output_pai.tiff", "EPSG:32605", extent)
+plot_metric('Plant Area Index', pai, extent, metric_name='PAI', cmap='viridis', fig_size=None)
 ```
 
+![Plant Area Index](./screenshots/pai.png)
+
 ## Documentation
 
 For detailed instructions and examples, visit our [documentation](https://pyforestscan.readthedocs.io/).
@@ -85,7 +99,7 @@ pytest tests/test_calculate.py
 
 ## Contributing
 
-We welcome contributions! Please check our [Contributing Guidelines](CONTRIBUTING.md) to get started.
+We welcome contributions! Please check our [Contributing Guidelines](docs/contributing.md) to get started.
 
 ## License
 

docs/CNAME

@@ -0,0 +1 @@
+pyforestscan.sefa.ai

docs/api/calculate.md

@@ -0,0 +1,3 @@
+# Calculate Module
+
+::: pyforestscan.calculate

docs/api/filters.md

@@ -0,0 +1,3 @@
+# Filters Module
+
+::: pyforestscan.filters

docs/api/handlers.md

@@ -0,0 +1,3 @@
+# Handlers Module
+
+::: pyforestscan.handlers

docs/api/pipeline.md

@@ -0,0 +1,3 @@
+# Pipeline Module
+
+::: pyforestscan.pipeline

docs/api/process.md

@@ -0,0 +1,3 @@
+# Process Module
+
+::: pyforestscan.process

docs/api/visualize.md

@@ -0,0 +1,3 @@
+# Visualize Module
+
+::: pyforestscan.visualize

docs/benchmarks.md

@@ -0,0 +1,71 @@
+# Benchmarking
+
+PyForestScan is designed for high performance and memory efficiency, ensuring it can handle large-scale point cloud datasets effectively. While no other Python libraries specifically calculate these forest structure metrics, there are alternatives in R, such as the`leafR` library (Almeida et al. 2021), that offer similar functionality.
+
+We provide a direct performance comparison between PyForestScan and`leafR` to demonstrate its efficiency. In both cases, we calculate Plant Area Index (PAI) (this is labelled as Leaf Area Index in the `leafR` library) on a LAS tile, repeating the process 100 times and plotting the results. The measured benchmarking is only done on the functions to calculate PAI/LAI. It does not include time taken to load the point cloud, etc.
+
+
+The benchmarks were conducted on a Mac with an Apple M3 Max processor (16 cores) and 128GB RAM.
+
+![Benchmark comparison between PyForestScan and leafR](images/lai_computation_times.png)
+
+## Code Used
+To calculate LAI in `leafR`, and compare these with the python code, we:
+
+```R
+# Install and load required packages
+if (!require("lidR")) install.packages("lidR")
+if (!require("raster")) install.packages("raster")
+if (!require("leafR")) install.packages("leafR")
+
+library(lidR)
+library(raster)
+library(leafR)
+
+file_path <- "example_data/20191126_5QKB020840_normalized.laz"
+las <- readLAS(file_path)
+if (is.empty(las)) {
+  stop("The LAS file is empty or could not be read.")
+}
+
+if (is.null(las@data$Z)) {
+  stop("The LAS file does not contain Z coordinates.")
+}
+
+if (!"Zref" %in% names(las@data)) {
+  las <- normalize_height(las, tin())
+}
+
+temp_las_file <- tempfile(fileext = ".las")
+writeLAS(las, temp_las_file)
+
+compute_lai <- function(las_file_path) {
+  lad_voxels <- lad.voxels(las_file_path, grain.size = 25)
+  lai_raster <- lai.raster(lad_voxels)
+  return(lai_raster)
+}
+
+timing_results <- data.frame(software = character(),
+                             time = numeric(),
+                             stringsAsFactors = FALSE)
+
+for (i in 1:100) {
+  start_time <- Sys.time()
+  lai_result <- compute_lai(temp_las_file)
+  end_time <- Sys.time()
+  iteration_time <- as.numeric(difftime(end_time, start_time, units = "secs"))
+
+  timing_results <- rbind(timing_results, data.frame(software = "R::leafR", time = iteration_time))
+  cat(sprintf("Iteration %d completed in %.2f seconds.\n", i, iteration_time))
+}
+
+write.csv(timing_results, file = "timing_results.csv", row.names = FALSE)
+
+cat(sprintf("Total time for 100 iterations: %.2f seconds.\n", sum(timing_results$time)))
+
+unlink(temp_las_file)
+```
+
+## Reference
+
+Almeida, Danilo Roberti Alves de, Scott Christopher Stark, Carlos Alberto Silva, Caio Hamamura, and Ruben Valbuena. 2021. "leafR: Calculates the Leaf Area Index (LAD) and Other Related Functions."Manual. <https://CRAN.R-project.org/package=leafR>.