欢迎来到lidar包

lidar 是一个Python包，用于从数字高程模型（DEM）中划分表面洼地的嵌套层次结构。它特别适用于分析高分辨率地形数据，例如从光探测与测距（LiDAR）数据中派生的DEM。

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

引用

• Wu, Q.，(2021) lidar: 从数字高程数据中划分嵌套表面洼地的Python包。 开源软件杂志，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) 使用水平集方法在数字高程模型中高效划分嵌套洼地层次结构以进行水文分析。 美国水资源协会杂志。 https://doi.org/10.1111/1752-1688.12689 (PDF)

内容

• 介绍
• 需求声明
• 领域现状
• 主要功能
• 安装
• 使用
• 参考文献
• 贡献
• 鸣谢

介绍

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

需求声明

lidar 包旨在为希望将表面凹地纳入水文模型的科学家和研究人员使用。它还可以促进识别和绘制凹地特征，如溶洞、滞留池和草原凹坑。表面凹地的详细拓扑和几何属性对于地形分析和水文模型非常有用，包括大小、体积、平均深度、最大深度、最低高程、溢出高程、周长、主轴长度、副轴长度、细长比。

领域现状

目前，有几个开源Python包可以执行数字高程数据的凹地填充，例如 RichDEM 和 whitebox，它是 WhiteboxTools 的Python前端。然而，没有Python包提供绘制表面凹地层次结构和集水区以及模拟洪水动力学的工具。Python包 lidar 就是为了填补这一空白。

主要功能

• 使用均值、中值和高斯滤波平滑DEM。
• 从DEM中提取凹地。
• 根据用户指定的最小凹地大小过滤掉小伪影凹地。
• 生成精细DEM，小凹地被填充，但大凹地保持完整。
• 使用水平集方法绘制凹地嵌套层次结构。
• 使用水平集方法绘制山嵌套层次结构。
• 计算凹地的拓扑和几何属性，包括大小、体积、平均深度、最大深度、最低高程、溢出高程、周长、主轴长度、副轴长度、细长比、偏心率、方向和面积-边框比。
• 将凹地属性导出为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”，请按照以下步骤修复错误并重新安装lidar。更多信息可以在此链接找到：修复Python 3在Windows上的错误 - 需要Microsoft Visual C++ 14.0。

• 下载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 *

# identify the sample data directory of the package
package_name = 'lidar'
data_dir = pkg_resources.resource_filename(package_name, 'data/')

# use the sample dem. Change it to your own dem if needed
in_dem = os.path.join(data_dir, 'dem.tif')
# set the output directory
out_dir = os.getcwd()

# parameters for identifying sinks and delineating nested depressions
min_size = 1000      # minimum number of pixels as a depression
min_depth = 0.5      # minimum depth as a depression
interval = 0.3       # slicing interval for the level-set method
bool_shp = True      # output shapefiles for each individual level

# extracting sinks based on user-defined minimum depression size
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('Results are saved in: {}'.format(out_dir))

lidar GUI

lidar还提供了一个图形用户界面（GUI），可以使用以下Python脚本调用：

import lidar
lidar.gui()

lidar for ArcGIS Pro的工具箱

工具箱界面

视频教程

使用ArcGIS Pro绘制嵌套地表凹地和集水区

使用ArcMap绘制嵌套地表凹地和集水区

现实世界案例

下面的图片显示了在北达科他州Cottonwood湖研究区（CLSA）中绘制嵌套凹地的水平集方法的运行示例。更多测试数据集（例如，北达科他州大平原区域的Pipestem流域）可以从http://gishub.org/2019-JAWRA-Data下载。

以下示例是在具有四核Intel i7-7700 CPU和16 GB RAM的64位Linux机器上进行的。该DEM算法的平均运行时间为0.75秒。

参考文献

水平集算法由Wu等人（2019）提出。

• Wu, Q.，Lane, C.R.，Wang, L.，Vanderhoof, M.K.，Christensen, J.R.，& Liu, H. (2019)。使用水平集方法有效地绘制数字高程模型中的嵌套凹地层次结构，以进行水文分析。《美国水资源协会杂志》。DOI：10.1111/1752-1688.12689 (PDF)

使用水平集和等高线树方法从LiDAR数据中提取特征的应用

• Wu, Q.，& Lane, C.R. (2017)。使用LiDAR数据和航空影像绘制湿地集水区和模拟水文连通性。《水文与地球系统科学》。21：3579-3595。DOI：10.5194/hess-21-3579-2017
• 吴，Q.，邓，C.，& 陈，Z. (2016). 基于LiDAR数字高程模型的喀斯特落水洞自动提取. 地貌学. 266: 1-10. DOI: 10.1016/j.geomorph.2016.05.006
• 吴，Q.，苏，H.，谢尔曼，D.J.，刘，H.，沃曾克拉夫特，J.M.，余，B.，& 陈，Z. (2016). 基于图的方法评估风暴引起的海岸变化. 国际遥感杂志. 37:4854-4873. DOI: 10.1080/01431161.2016.1225180
• 吴，Q.，& 莱恩，C.R. (2016). 北达科他州大草原凹地地区湿地凹陷的提取和量化. 湿地. 36(2):215–227. DOI: 10.1007/s13157-015-0731-6
• 吴，Q.，刘，H.，王，S.，余，B.，贝克，R.，& 辛克尔，K. (2015). 基于高分辨率地形数据从复杂地表凹陷中提取几何和拓扑属性的局部等高线树方法. 国际地理信息科学杂志. 29(12): 2041-2060. DOI: 10.1080/13658816.2015.1038719
• 吴，Q.，莱恩，C.R.，& 刘，H. (2014). 利用高分辨率LiDAR数据和航空影像检测潜在林地春季积水坑的有效方法. 遥感. 6(11):11444-11467. DOI: 10.3390/rs61111444

贡献

欢迎贡献，我们将非常感激！每一份贡献都很有帮助，并且我们将永远给予认可。您可以通过许多方式做出贡献

贡献类型

报告错误

在https://github.com/opengeos/lidar/issues报告错误。

如果您正在报告一个错误，请包括

• 您的操作系统名称和版本。
• 任何可能有助于故障排除的本地设置细节。
• 重现错误的详细步骤。

修复错误

查看GitHub问题中的错误。任何标记为“bug”和“help wanted”的问题都欢迎任何人实现。

实现功能

查看GitHub问题中的功能。任何标记为“enhancement”和“help wanted”的问题都欢迎任何人实现。

编写文档

lidar始终需要更多的文档，无论是作为官方lidar文档的一部分，还是在docstrings中，甚至在网络上在博客文章和此类文章中。

提交反馈

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

如果您正在提出一个功能

• 详细说明它的工作方式。
• 尽可能缩小范围，以便更容易实现。
• 请记住，这是一个由志愿者驱动的项目，我们欢迎贡献。

开始贡献

准备好贡献了吗？以下是设置本地开发中的lidar的方法。

1. 在GitHub上Fork lidar 仓库。

2. 在本地克隆您的分支

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 "Your detailed description of your changes."
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 项目模板创建的。