From ddc008aa3e62abebf998a467308477b34889d894 Mon Sep 17 00:00:00 2001
From: iosefa <ipercival@gmail.com>
Date: Wed, 11 Feb 2026 12:58:07 -1000
Subject: [PATCH] Add docs page for custom voxel statistic rasters

---
 docs/usage/voxel-stat-rasters.md | 62 ++++++++++++++++++++++++++++++++
 mkdocs.yml                       |  3 +-
 2 files changed, 64 insertions(+), 1 deletion(-)
 create mode 100644 docs/usage/voxel-stat-rasters.md

diff --git a/docs/usage/voxel-stat-rasters.md b/docs/usage/voxel-stat-rasters.md
new file mode 100644
index 0000000..e5f2544
--- /dev/null
+++ b/docs/usage/voxel-stat-rasters.md
@@ -0,0 +1,62 @@
+# Custom Voxel Statistic Rasters
+
+PyForestScan can build rasters from arbitrary point dimensions by combining:
+
+- `calculate_voxel_stat` to aggregate values per XY cell.
+- `create_geotiff` to write the result as a GeoTIFF.
+
+This is useful for products like mean intensity, return count, median height-above-ground, and more.
+
+## Example: Mean Intensity at 1 m Resolution
+
+```python
+from pyforestscan.handlers import read_lidar, create_geotiff
+from pyforestscan.calculate import calculate_voxel_stat
+
+file_path = "../example_data/20191210_5QKB020880.laz"
+arrays = read_lidar(file_path, "EPSG:32605", hag=True)
+
+# 1 m XY cells, 1 m vertical bins
+voxel_resolution = (1.0, 1.0, 1.0)
+
+mean_intensity, extent = calculate_voxel_stat(
+    arrays[0],
+    voxel_resolution=voxel_resolution,
+    dimension="Intensity",
+    stat="mean"
+)
+
+create_geotiff(
+    mean_intensity,
+    "../example_data/mean_intensity_1m.tif",
+    "EPSG:32605",
+    extent
+)
+```
+
+## Supported Statistics
+
+`calculate_voxel_stat` supports:
+
+- `mean`
+- `sum`
+- `count`
+- `min`
+- `max`
+- `median`
+- `std`
+
+## Restricting by Height Range
+
+Use `z_index_range=(start, stop)` to include only specific vertical bins (inclusive-exclusive index range).
+
+```python
+subset_mean_intensity, extent = calculate_voxel_stat(
+    arrays[0],
+    voxel_resolution=(1.0, 1.0, 1.0),
+    dimension="Intensity",
+    stat="mean",
+    z_index_range=(2, 10)  # use bins 2..9
+)
+```
+
diff --git a/mkdocs.yml b/mkdocs.yml
index 83a2b64..e7e472c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -39,6 +39,7 @@ nav:
     - Usage:
         - usage/getting-started-import-and-preprocess.md
         - usage/digital-terrain-models.md
+        - usage/voxel-stat-rasters.md
         - Forest Structure:
             - usage/forest-structure/intro.md
             - usage/forest-structure/chm.md
@@ -66,4 +67,4 @@ extra_css:
     - overrides/custom.css
 
 extra_javascript:
- - https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.0/es5/tex-mml-chtml.js
\ No newline at end of file
+ - https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.0/es5/tex-mml-chtml.js