NAIP-CHM: A 0.6-meter resolution canopy height model for the contiguous United States

Overview This repository contains the source code, trained model weights, model validation data, training metadata, and inference tools for NAIP-CHM, a project that generates a 0.6-meter resolution canopy height model (CHM) for the contiguous United States using National Agriculture Imagery Program (NAIP) aerial imagery. This repository supports the published version of the model based on weights dated 2025-10-16. This codebase constitutes the version of record associated with the paper: A 0.6-meter resolution canopy height model for the contiguous United States. Now pubished in Scientific Data The repository provides: Inference Pipeline: Tools to generate canopy height models from NAIP DOQQs using a pre-trained U-Net model. Training Code: Scripts to train the model on new data, including distributed training support. Pre-trained Model: The final model weights used to generate the CONUS-wide dataset. Conditioning Data: Static environmental raster data required for model inference. Model Validation Data: Validation metrics and tile-level statistics at 0.6m and 1.0m resolutions, plus an evaluation script for custom datasets. The development repository for this project can be found at https://github.com/smorf-ntsg/naip-chm. To investigate the model output, see the Google Earth Engine App or download the data from our servers. Installation This codebase requires Python 3.11+. Ensure you have the repository files extracted to your local machine. Install the required dependencies: pip install -r requirements.txt Data Access 1. Training Dataset The training dataset is not included in this repository due to its size. It contains over 22 million image pairs.You can download the training data from the University of Montana Rangeland server: URL: http://rangeland.ntsg.umt.edu/data/rap/chm-naip/ See data/training_dataset/README for more details. 2. Inference Assets This repository includes the necessary assets to run inference: Pre-trained Model Weights: Located at model/model_20251016.pt Static Conditioning Rasters: Located in data/conditioning_data/ (includes elevation, climate, soil, NLCD, and ecoregion data). 3. Model Validation Data Validation data for the trained model is provided in the `model_validation_data/` directory. The model has been evaluated at both standard resolutions: 0.6m Resolution: Native model resolution with tile-level statistics in `tilestats_06m.csv` 1.0m Resolution: Resampled predictions with tile-level statistics in `tilestats_10m.csv` Evaluation Report: Comprehensive performance summary The scripts/evaluate_model.py script can be used to generate validation results and performance metrics for custom evaluation datasets. Usage Running Inference You can run the model on a standard NAIP DOQQ (Digital Ortho Quarter Quad) using the scripts/inference.py script. A sample NAIP image is provided in data/naip_doqqs/. Example Command: python scripts/inference.py \ --naip-quad data/naip_doqqs/m_3812259_nw_10_060_20220519.tif \ --output-dir output/ \ --model-checkpoint model/model_20251016.pt \ --config configs/config.yaml \ --static-rasters-dir data/conditioning_data/ Arguments: --naip-quad: Path to the input 4-band NAIP imagery (R, G, B, NIR). --output-dir: Directory where the output CHM GeoTIFF and report will be saved. --model-checkpoint: Path to the trained model weights. --config: Path to the configuration YAML file. --static-rasters-dir: Directory containing the environmental conditioning rasters. --chip-size: (Optional) Processing chip size (default: 432). --chip-overlap: (Optional) Overlap between chips (default: 0.2). Training the Model To train the model from scratch or fine-tune it, use the scripts/train.py script. Ensure you have downloaded the training dataset and updated the configs/config.yaml file to point to the correct data paths. Command: python scripts/train.py \ --config configs/config.yaml \ --experiment_name my_experiment Distributed Training: The script supports Distributed Data Parallel (DDP) training. To run on multiple GPUs (e.g., 2 GPUs): torchrun --nproc_per_node=2 scripts/train.py \ --config configs/config.yaml \ --experiment_name my_ddp_experiment Citation If you use this dataset or code in your research, please cite the following manuscript: Morford, S. L., Allred, B. W., Coons, S. P., Marcozzi, A. A., McCord, S. E., Smith, J.T., & Naugle, D. E. 2026. A 0.6-meter resolution canopy height model for the contiguous United States. Sci Data doi: https://doi.org/10.1038/s41597-026-07549-w# 概览 本仓库包含NAIP-CHM项目的源代码、预训练模型权重、模型验证数据、训练元数据以及推理工具。NAIP-CHM项目依托美国国家农业影像计划（National Agriculture Imagery Program, NAIP）的航空影像，生成覆盖美国本土的0.6米分辨率冠层高度模型（canopy height model, CHM）。本仓库适配基于2025-10-16权重的正式发布版模型。 本代码库对应即将发表的论文《面向美国本土的0.6米分辨率冠层高度模型》的正式版本，预印本可在bioRxiv平台查阅。 本仓库提供以下内容： - 推理流水线：基于预训练U-Net模型，从NAIP数字正射四分之一象限图（Digital Ortho Quarter Quad, DOQQs）生成冠层高度模型的工具集。 - 训练代码：支持分布式训练的模型训练脚本，可用于在新数据集上训练模型。 - 预训练模型：用于生成全美范围冠层高度模型数据集的最终模型权重。 - 条件数据：模型推理所需的静态环境栅格数据。 - 模型验证数据：包含0.6米与1.0米分辨率下的验证指标与瓦片级统计信息，以及适用于自定义数据集的评估脚本。 本项目的开发仓库可访问：https://github.com/smorf-ntsg/naip-chm。如需探究模型输出结果，可使用Google Earth Engine应用或从我们的服务器下载数据集。 # 安装要求 本代码库要求Python 3.11及以上版本。 请将仓库文件解压至本地设备。安装所需依赖： pip install -r requirements.txt # 数据获取 1. 训练数据集 由于体积过大，训练数据集未包含在本仓库中，其包含超过2200万张图像对。可从蒙大拿大学牧场研究服务器下载训练数据： URL: http://rangeland.ntsg.umt.edu/data/rap/chm-naip/ 更多详情请查阅`data/training_dataset/README`文件。 2. 推理资源 本仓库包含运行推理所需的全部必要资源： - 预训练模型权重：存储于`model/model_20251016.pt` - 静态条件栅格：位于`data/conditioning_data/`目录下，包含高程、气候、土壤、NLCD以及生态区数据。 3. 模型验证数据 训练模型的验证数据存储于`model_validation_data/`目录。本模型已在两种标准分辨率下完成评估： - 0.6米分辨率：模型原生分辨率，瓦片级统计信息存储于`tilestats_06m.csv` - 1.0米分辨率：重采样后的预测结果，瓦片级统计信息存储于`tilestats_10m.csv` - 评估报告：完整的性能总结 可使用`scripts/evaluate_model.py`脚本为自定义评估数据集生成验证结果与性能指标。 # 使用方法 ## 运行推理 可通过`scripts/inference.py`脚本在标准NAIP DOQQ（数字正射四分之一象限图）上运行模型。示例NAIP图像已提供于`data/naip_doqqs/`目录下。 示例命令： python scripts/inference.py --naip-quad data/naip_doqqs/m_3812259_nw_10_060_20220519.tif --output-dir output/ --model-checkpoint model/model_20251016.pt --config configs/config.yaml --static-rasters-dir data/conditioning_data/ 参数说明： - `--naip-quad`：输入的4波段NAIP影像（红、绿、蓝、近红外）路径。 - `--output-dir`：输出冠层高度模型GeoTIFF与报告的保存目录。 - `--model-checkpoint`：预训练模型权重路径。 - `--config`：配置YAML文件路径。 - `--static-rasters-dir`：包含环境条件栅格的目录路径。 - `--chip-size`：（可选）处理瓦片大小（默认值：432）。 - `--chip-overlap`：（可选）瓦片间重叠比例（默认值：0.2）。 ## 训练模型 如需从零训练模型或对模型进行微调，请使用`scripts/train.py`脚本。请确保已下载训练数据集，并更新`configs/config.yaml`文件以指向正确的数据路径。 命令： python scripts/train.py --config configs/config.yaml --experiment_name my_experiment 分布式训练：本脚本支持分布式数据并行（Distributed Data Parallel, DDP）训练。如需在多GPU环境下运行（例如2张GPU）： torchrun --nproc_per_node=2 scripts/train.py --config configs/config.yaml --experiment_name my_ddp_experiment # 引用 如您在研究中使用本数据集或代码，请引用以下论文： Morford, S. L., Allred, B. W., Coons, S. P., Marcozzi, A. A., McCord, S. E., Smith, J.T., & Naugle, D. E. 2025. 面向美国本土的0.6米分辨率冠层高度模型. bioRxiv 2025.12.12.694075; doi: https://doi.org/10.6489/2025.12.12.694075