Merge pull request #19 from iosefa/docs/joss-paper-review-2

Docs/joss paper review 2

Author: iosefa

.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

.idea/PyForestScan.iml

@@ -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}

.readthedocs.yml

@@ -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
 

Dockerfile

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

README.md

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