欢迎使用lidar包

lidar是一个用于描绘数字高程模型（DEMs）中嵌套地表凹陷层次结构的Python包。它特别适用于分析高分辨率地形数据，如由光detection和测距（LiDAR）数据生成的DEMs。

• GitHub仓库：https://github.com/opengeos/lidar
• 文档：https://lidar.gishub.org
• PyPI：https://pypi.org/project/lidar
• Conda-forge：https://anaconda.org/conda-forge/lidar
• 在Colab中打开：https://gishub.org/lidar-colab
• 免费软件：MIT许可证

引用

• Wu, Q., (2021). lidar: A Python package for delineating nested surface depressions from digital elevation data. Journal of Open Source Software, 6(59), 2965, https://doi.org/10.21105/joss.02965
• Wu, Q., Lane, C.R., Wang, L., Vanderhoof, M.K., Christensen, J.R., & Liu, H. (2019). Efficient Delineation of Nested Depression Hierarchy in Digital Elevation Models for Hydrological Analysis Using Level-Set Method. Journal of the American Water Resources Association. https://doi.org/10.1111/1752-1688.12689 (PDF)

目录

• 简介
• 需求说明
• 领域现状
• 主要特性
• 安装
• 使用
• 参考文献
• 贡献
• 致谢

简介

lidar是一个用于描绘数字高程模型（DEMs）中嵌套地表凹陷层次结构的Python包。在传统的水文建模中，DEM中的地表凹陷通常被视为人工制品，因此会被填充和移除以创建无凹陷DEM，然后用于生成连续的河流网络。然而，实际上，DEM中的地表凹陷通常是虚假和实际地形特征的组合。由光detection和测距（LiDAR）数据生成的高分辨率DEM可以捕捉和表示实际的地表凹陷，特别是在冰川和喀斯特地貌中。在过去几十年里，已经开发了各种算法来识别和描绘地表凹陷，如凹陷填充、凹陷破堤、混合破堤-填充和等高线树方法。最近，提出了一种基于图论的水平集方法来描绘嵌套的地表凹陷层次结构。lidar Python包实现了水平集方法，使描绘嵌套的地表凹陷层次结构以及高地地形特征成为可能。它还提供了一个交互式图形用户界面（GUI），允许用户通过最少的编码运行程序。

需求说明

lidar包面向希望将地表凹陷整合到水文建模中的科学家和研究人员。它还可以促进凹陷特征的识别和描绘，如沉洞、滞留池和草原坑洼。地表凹陷的详细拓扑和几何特性对地形分析和水文建模非常有用，包括大小、体积、平均深度、最大深度、最低高程、溢流高程、周长、主轴长度、次轴长度、细长度。

领域现状

目前，有一些开源Python包可以对数字高程数据进行凹陷填充，如RichDEM和whitebox，后者是WhiteboxTools的Python前端。然而，没有Python包提供用于描绘嵌套的地表凹陷和集水区层次结构以及模拟淹没动态的工具。lidar Python包旨在填补这一空白。

主要特性

• 使用均值、中值和高斯滤波器平滑DEMs。
• 从DEMs中提取凹陷。
• 根据用户指定的最小凹陷大小过滤掉小的人工凹陷。
• 生成精细的DEMs，小凹陷被填充但保持较大凹陷完整。
• 使用水平集方法描绘凹陷嵌套层次结构。
• 使用水平集方法描绘山体嵌套层次结构。
• 计算凹陷的拓扑和几何特性，包括大小、体积、平均深度、最大深度、最低高程、溢流高程、周长、主轴长度、次轴长度、细长度、偏心率、方向和面积-边界框比率。
• 将凹陷特性导出为csv文件。

安装

lidar支持多种平台，包括Microsoft Windows、macOS和Linux操作系统。请注意，您需要安装Python 3.x（< 3.9）。不支持Python 2.x。lidar在PyPI和conda-forge上均可获得。 lidar依赖于GDAL，在Windows上使用pip安装可能具有挑战性。 因此，强烈建议从conda-forge通道安装lidar。 如果遇到任何错误，请查看下面的依赖项部分。

从PyPI安装

要从PyPI安装lidar，请在终端中运行以下命令：

pip install lidar

从conda-forge安装

如果您的计算机上已安装Anaconda或Miniconda，您可以创建一个新的conda环境来安装lidar：

conda create -n geo python=3.11
conda activate geo
conda install -c conda-forge mamba
mamba install -c conda-forge lidar

升级lidar

如果您之前安装过lidar并想升级到最新版本，可以在终端中运行以下命令:

pip install -U lidar

如果您使用conda，可以通过在终端中运行以下命令将lidar更新到最新版本:

mamba update -c conda-forge lidar

要直接从GitHub使用Git安装开发版本，请运行以下代码:

pip install git+https://github.com/opengeos/lidar

依赖项

lidar的Python依赖项列在其requirements.txt文件中。此外，lidar还有一个C库依赖项:GDAL >=1.11.2。下面将解释如何在不同操作系统中安装GDAL。更多关于GDAL的信息可以在这里找到。

Linux

基于Debian的Linux

以下命令可用于为基于Debian的Linux发行版(如Ubuntu、Linux Mint)安装GDAL。

sudo add-apt-repository ppa:ubuntugis/ppa
sudo apt-get update
sudo apt-get install gdal-bin libgdal-dev

如果遇到任何编译错误，请尝试以下命令。

sudo apt-get install --reinstall build-essential
sudo apt-get install python3-dev
pip install wheel

基于Pacman的Linux

以下命令可用于为基于Pacman的Linux发行版(如Arch Linux、Manjaro)安装GDAL。如果遇到权限错误，可能需要使用sudo。

sudo pacman -S yaourt --noconfirm
yaourt -S gdal --noconfirm
yaourt -S python-gdal --noconfirm

macOS

对于基于Homebrew的Python环境，执行以下操作。

brew update
brew install gdal

或者，您可以从kyngchaos安装GDAL二进制文件。然后需要将安装位置/Library/Frameworks/GDAL.framework/Programs添加到系统路径中。

Windows

以下说明假设您已安装Anaconda。打开Anaconda Prompt并输入以下命令来创建conda环境并安装所需的包

conda create -n geo python=3.11
conda activate geo
conda install -c conda-forge mamba
mamba install -c conda-forge lidar

安装lidar包时，如果遇到错误提示Microsoft Visual C++ 14.0 is required，请按照以下步骤修复错误并重新安装lidar。更多信息可在此链接Fix Python 3 on Windows error - Microsoft Visual C++ 14.0 is required找到。

• 下载Microsoft Build Tools for Visual Studio 2017
• 双击安装下载的安装程序 - Microsoft Build Tools for Visual Studio 2017。
• 打开Microsoft Build Tools for Visual Studio 2017
• 选择Workloads --> Visual C++ build tools并点击安装按钮

用法

现在通过Google Colab启动lidar Python包的交互式笔记本教程:

快速示例

import os
import pkg_resources
from lidar import *

# 识别包的示例数据目录
package_name = 'lidar'
data_dir = pkg_resources.resource_filename(package_name, 'data/')

# 使用示例dem。如有需要，请更改为您自己的dem
in_dem = os.path.join(data_dir, 'dem.tif')
# 设置输出目录
out_dir = os.getcwd()

# 识别洼地和划定嵌套洼地的参数
min_size = 1000      # 作为洼地的最小像素数
min_depth = 0.5      # 作为洼地的最小深度
interval = 0.3       # 水平集方法的切片间隔
bool_shp = True      # 为每个单独的水平输出shapefile

# 根据用户定义的最小洼地大小提取洼地
out_dem = os.path.join(out_dir, "median.tif")
in_dem = MedianFilter(in_dem, kernel_size=3, out_file=out_dem)
sink_path = ExtractSinks(in_dem, min_size, out_dir)
dep_id_path, dep_level_path = DelineateDepressions(sink_path,
                                                   min_size,
                                                   min_depth,
                                                   interval,
                                                   out_dir,
                                                   bool_shp)
print('结果已保存在: {}'.format(out_dir))

lidar GUI

lidar还提供了一个图形用户界面(GUI)，可以使用以下Python脚本调用:

import lidar
lidar.gui()

ArcGIS Pro的lidar工具箱

工具箱界面

视频教程

使用ArcGIS Pro划定嵌套地表洼地和集水区

使用ArcMap划定嵌套地表洼地和集水区

实际例子

下面的图像展示了在北达科他州棉花湖研究区(CLSA)使用水平集方法划定嵌套洼地的工作示例。更多测试数据集(例如北达科他州草原坑塘区的Pipestem流域)可以从http://gishub.org/2019-JAWRA-Data下载

以下示例是在一台64位Linux机器上进行的，配备四核Intel i7-7700 CPU和16 GB RAM。该算法对这个DEM的平均运行时间为0.75秒。

参考文献

水平集算法由Wu等人(2019)提出:

• Wu, Q., Lane, C.R., Wang, L., Vanderhoof, M.K., Christensen, J.R., & Liu, H. (2019). Efficient Delineation of Nested Depression Hierarchy in Digital Elevation Models for Hydrological Analysis Using Level-Set Method. Journal of the American Water Resources Association. DOI: 10.1111/1752-1688.12689 (PDF)

水平集和轮廓树方法在LiDAR数据特征提取中的应用:

• 吴青和C.R. Lane (2017)。利用LiDAR数据和航空影像划定湿地集水区并模拟水文连通性。《水文与地球系统科学》21: 3579-3595。DOI: 10.5194/hess-21-3579-2017

• 吴青、邓春和陈震 (2016)。基于LiDAR生成的数字高程模型自动划定岩溶漏斗。《地貌学》266: 1-10。DOI: 10.1016/j.geomorph.2016.05.006

• 吴青、苏晗、D.J. Sherman、刘鸿、J.M. Wozencraft、于波和陈震 (2016)。评估风暴引起的海岸变化的图论方法。《国际遥感杂志》37:4854-4873。DOI: 10.1080/01431161.2016.1225180

• 吴青和C.R. Lane (2016)。北达科他州草原坑塘区湿地洼地的划定和量化。《湿地》36(2):215–227。DOI: 10.1007/s13157-015-0731-6

• 吴青、刘鸿、王松、于波、R. Beck和K. Hinkel (2015)。基于高分辨率地形数据的局部轮廓树方法推导复杂地表洼地的几何和拓扑特性。《国际地理信息科学杂志》29(12): 2041-2060。DOI: 10.1080/13658816.2015.1038719

• 吴青、C.R. Lane和刘鸿 (2014)。利用高分辨率LiDAR数据和航空影像探测潜在林地季节性池塘的有效方法。《遥感》6(11):11444-11467。DOI: 10.3390/rs61111444

贡献

我们欢迎并感谢您的贡献！每一点帮助都很重要，我们将始终给予认可。您可以通过多种方式做出贡献:

贡献类型

报告Bug

请在https://github.com/opengeos/lidar/issues报告Bug。

如果您要报告Bug，请包含以下内容:

• 您的操作系统名称和版本。
• 任何可能有助于解决问题的本地设置详细信息。
• 重现Bug的详细步骤。

修复Bug

浏览GitHub上的问题寻找Bug。任何标记为"bug"和"help wanted"的问题都欢迎任何人来实现。

实现功能

浏览GitHub上的问题寻找新功能。任何标记为"enhancement"和"help wanted"的问题都欢迎任何人来实现。

编写文档

lidar总是需要更多的文档，无论是作为官方lidar文档的一部分、在文档字符串中，还是在网络上的博客文章、文章等。

提交反馈

发送反馈的最佳方式是在https://github.com/opengeos/lidar/issues提交问题。

如果您要提出一个功能:

• 详细解释它将如何工作。
• 尽可能缩小范围,使其更容易实现。
• 请记住这是一个由志愿者驱动的项目,我们欢迎贡献。

入门

准备好贡献了吗?以下是如何为本地开发设置_lidar_。

1. 在GitHub上fork lidar仓库。

2. 将您的fork克隆到本地:

git clone git@github.com:your_name_here/lidar.git

3. 将本地副本安装到conda环境中。假设您已安装conda,以下是如何为本地开发设置fork:

conda create -n lidar-test python
conda activate lidar-test
cd lidar/
pip install -e .

4. 创建用于本地开发的分支:

git checkout -b name-of-your-bugfix-or-feature

现在您可以在本地进行更改了。

5. 完成更改后,检查您的更改是否通过flake8和测试,包括使用tox测试其他Python版本:

flake8 lidar tests
python setup.py test or pytest

要获取flake8和tox,只需将它们pip安装到您的conda环境中。

6. 提交您的更改并将分支推送到GitHub:

git add .
git commit -m "您更改的详细描述。"
git push origin name-of-your-bugfix-or-feature

7. 通过GitHub网站提交拉取请求。

拉取请求指南

在提交拉取请求之前,请检查它是否符合以下准则:

1. 拉取请求应包含测试。
2. 如果拉取请求添加了功能,则应更新文档。将新功能放入带有文档字符串的函数中,并将该功能添加到README.md中的列表中。
3. 拉取请求应适用于Python 3.7和3.8。检查https://github.com/opengeos/lidar/actions 并确保所有支持的Python版本都通过了测试。

致谢

• 算法基于RichDEM、numpy、scipy、scikit-image和pygdal构建。
• 本包是使用Cookiecutter和audreyr/cookiecutter-pypackage项目模板创建的。