Package: lidar
Welcome to the lidar packagelidaris Python package for delineating the nested hierarchy of surface depressions in digital elevation models (DEMs). It is
particularly useful for analyzing high-resolution topographic data, such as DEMs derived from Light Detection and Ranging (LiDAR) data.GitHub repo:https://github.com/giswqs/lidarDocumentation:https://lidar.gishub.orgPyPI:https://pypi.org/project/lidarConda-forge:https://anaconda.org/conda-forge/lidarOpen in Colab:https://gishub.org/lidar-colabFree software:MIT licenseCitationsWu, 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.02965Wu, 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)ContentsIntroductionStatement of NeedState of the FieldKey FeaturesInstallationUsageReferencesContributingCreditsIntroductionlidaris a Python package for delineating the nested hierarchy of
surface depressions in digital elevation models (DEMs). In traditional
hydrological modeling, surface depressions in a DEM are commonly treated
as artifacts and thus filled and removed to create a depressionless DEM,
which can then be used to generate continuous stream networks. In
reality, however, surface depressions in DEMs are commonly a combination
of spurious and actual terrain features. Fine-resolution DEMs derived
from Light Detection and Ranging (LiDAR) data can capture and represent
actual surface depressions, especially in glaciated and karst
landscapes. During the past decades, various algorithms have been
developed to identify and delineate surface depressions, such as
depression filling, depression breaching, hybrid breaching-filling, and
contour tree method. More recently, a level-set method based on graph
theory was proposed to delineate the nested hierarchy of surface
depressions. ThelidarPython package implements the level-set
method and makes it possible for delineating the nested hierarchy of
surface depressions as well as elevated terrain features. It also
provides an interactive Graphical User Interface (GUI) that allows users
to run the program with minimal coding.Statement of NeedThelidarpackage is intended for scientists and researchers who
would like to integrate surface depressions into hydrological modeling.
It can also facilitate the identification and delineation of
depressional features, such as sinkholes, detention basins, and prairie
potholes. The detailed topological and geometric properties of surface
depressions can be useful for terrain analysis and hydrological
modeling, including the size, volume, mean depth, maximum depth, lowest
elevation, spill elevation, perimeter, major axis length, minor axis
length, elongatedness.State of the FieldCurrently, there are a few open-source Python packages that can perform depression filling on digital elevation data, such asRichDEMandwhitebox, the Python frontend forWhiteboxTools. However, there are no Python packages offering tools for delineating the nested hierarchy of surface depressions and catchments as well as simulating inundation dynamics. ThelidarPython package is intended for filling this gap.Key FeaturesSmoothing DEMs using mean, median, and Gaussian filters.Extracting depressions from DEMs.Filtering out small artifact depressions based on user-specified minimum depression size.Generating refined DEMs with small depressions filled but larger depressions kept intact.Delineating depression nested hierarchy using the level-set method.Delineating mount nested hierarchy using the level-set method.Computing topological and geometric properties of depressions, including size, volume, mean depth, maximum depth, lowest elevation,
spill elevation, perimeter, major axis length, minor axis length, elongatedness, eccentricity, orientation, and area-bbox-ratio.Exporting depression properties as a csv file.Installationlidarsupports a variety of platforms, including Microsoft Windows,
macOS, and Linux operating systems. Note that you will need to havePython 3.x(< 3.9) installed. Python 2.x is not supported.lidaris available on bothPyPIandconda-forge.
lidar has aGDALdependency, which can be challenging to install using pip on Windows.
Therefore, it is highly recommended to install lidar from the conda-forge channel.
If you encounter any errors, please check theDependenciessection below.Install from PyPITo installlidarfrom PyPI, run this command in your terminal:pip install lidarInstall from conda-forageIf you haveAnacondaorMinicondainstalled on your computer, you can create a fresh conda environment to install lidar:conda create -n py38 python=3.8conda activate py38conda install lidar -c conda-forgeUpgrade lidarIf you have installed lidar before and want to upgrade to the latest version, you can run the following command in your terminal:pip install -U lidarIf you use conda, you can update lidar to the latest version by running the following command in your terminal:conda update lidar -c conda-forgeTo install the development version from GitHub directly using Git, run the following code:pip install git+https://github.com/giswqs/lidarDependencieslidar's Python dependencies are listed in itsrequirements.txtfile. In
addition, lidar has a C library dependency: GDAL >=1.11.2. How to
install GDAL in different operating systems will be explained below.
More information about GDAL can be foundhere.LinuxDebian-based LinuxThe following commands can be used to install GDAL for Debian-based
Linux distributions (e.g., Ubuntu, Linux Mint).sudo add-apt-repository ppa:ubuntugis/ppasudo apt-get updatesudo apt-get install gdal-bin libgdal-devIf you encounter any compiling errors, try the following commands.sudo apt-get install --reinstall build-essentialsudo apt-get install python3-devpip install wheelPacman-based LinuxThe following commands can be used to install GDAL for Pacman-based
Linux distributions (e.g., Arch Linux, Manjaro). You might need to usesudoif you encounter permission errors.sudo pacman -S yaourt --noconfirmyaourt -S gdal --noconfirmyaourt -S python-gdal --noconfirmmacOSFor a Homebrew based Python environment, do the following.brew updatebrew install gdalAlternatively, you can install GDAL binaries fromkyngchaos. You will
then need to add the installed location/Library/Frameworks/GDAL.framework/Programsto your system path.WindowsThe instruction below assumes that you have installedAnaconda. OpenAnaconda Promptand enter the following commands to create a conda
environment and install required packagesconda create -n py38 python=3.8conda activate py38conda install lidar -c conda-forgeWhen installing thelidarpackage, if you encounter an error
sayingMicrosoft Visual C++ 14.0 is required, please follow the steps
below to fix the error and reinstalllidar. More information can
be found at this linkFix Python 3 on Windows error - Microsoft Visual C++ 14.0 is required.DownloadMicrosoft Build Tools for Visual Studio 2017Double click to install the downloaded installer -Microsoft Build Tools for Visual Studio 2017.OpenMicrosoft Build Tools for Visual Studio 2017SelectWorkloads --> Visual C++ build toolsand click the install buttonUsageLaunch the interactive notebook tutorial for thelidarPython
package withGoogle Colabnow:A quick exampleimportosimportpkg_resourcesfromlidarimport*# identify the sample data directory of the packagepackage_name='lidar'data_dir=pkg_resources.resource_filename(package_name,'data/')# use the sample dem. Change it to your own dem if neededin_dem=os.path.join(data_dir,'dem.tif')# set the output directoryout_dir=os.getcwd()# parameters for identifying sinks and delineating nested depressionsmin_size=1000# minimum number of pixels as a depressionmin_depth=0.5# minimum depth as a depressioninterval=0.3# slicing interval for the level-set methodbool_shp=True# output shapefiles for each individual level# extracting sinks based on user-defined minimum depression sizeout_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 GUIlidaralso provides a Graphical User Interface (GUI), which can be
invoked using the following Python script:importlidarlidar.gui()lidar toolbox for ArcGIS ProToolbox interfaceVideo tutorialsDelineating nested surface depressions and catchments using ArcGIS ProDelineating nested surface depressions and catchments using ArcMapA real-world exampleThe images below show working examples of the level set method for
delineating nested depressions in the Cottonwood Lake Study Area (CLSA),
North Dakota. More test datasets (e.g., the Pipestem watershed in the
Prairie Pothole Region of North Dakota) can be downloaded fromhttp://gishub.org/2019-JAWRA-DataThe following example was conducted on a 64-bit Linux machine with a
quad-core Intel i7-7700 CPU and 16 GB RAM. The average running time of
the algorithm for this DEM was 0.75 seconds.ReferencesThe level-set algorithm was proposed byWuet al. (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)Applications of the level-set and contour-tree methods for feature
extraction from LiDAR data:Wu, Q., & Lane, C.R. (2017). Delineating wetland catchments and
modeling hydrologic connectivity using LiDAR data and aerial
imagery.Hydrology and Earth System Sciences. 21: 3579-3595. DOI:10.5194/hess-21-3579-2017Wu, Q., Deng, C., & Chen, Z. (2016). Automated delineation of
karst sinkholes from LiDAR-derived digital elevation models.Geomorphology. 266: 1-10. DOI:10.1016/j.geomorph.2016.05.006Wu, Q., Su, H., Sherman, D.J., Liu, H., Wozencraft, J.M., Yu,
B., & Chen, Z. (2016). A graph-based approach for assessing
storm-induced coastal changes.International Journal of Remote
Sensing. 37:4854-4873. DOI:10.1080/01431161.2016.1225180Wu, Q., & Lane, C.R. (2016). Delineation and quantification of
wetland depressions in the Prairie Pothole Region of North Dakota.Wetlands. 36(2):215–227. DOI:10.1007/s13157-015-0731-6Wu, Q., Liu, H., Wang, S., Yu, B., Beck, R., & Hinkel, K.
(2015). A localized contour tree method for deriving geometric and
topological properties of complex surface depressions based on
high-resolution topographic data.International Journal of
Geographical Information Science. 29(12): 2041-2060. DOI:10.1080/13658816.2015.1038719Wu, Q., Lane, C.R., & Liu, H. (2014). An effective method for
detecting potential woodland vernal pools using high-resolution
LiDAR data and aerial imagery.Remote Sensing. 6(11):11444-11467.
DOI:10.3390/rs61111444ContributingContributions are welcome, and they are greatly appreciated! Every
little bit helps, and credit will always be given. You can contribute in many ways:Types of ContributionsReport BugsReport bugs athttps://github.com/giswqs/lidar/issues.If you are reporting a bug, please include:Your operating system name and version.Any details about your local setup that might be helpful in troubleshooting.Detailed steps to reproduce the bug.Fix BugsLook through the GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.Implement FeaturesLook through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.Write Documentationlidar could always use more documentation, whether as part of the official lidar docs, in docstrings, or even on the web in blog posts, articles, and such.Submit FeedbackThe best way to send feedback is to file an issue athttps://github.com/giswqs/lidar/issues.If you are proposing a feature:Explain in detail how it would work.Keep the scope as narrow as possible, to make it easier to implement.Remember that this is a volunteer-driven project, and that contributions are welcome.Get StartedReady to contribute? Here's how to set uplidarfor local development.Fork thelidarrepo on GitHub.Clone your fork locally:git clone git@github.com:your_name_here/lidar.gitInstall your local copy into a conda env. Assuming you have conda installed, this is how you set up your fork for local development:conda create -n lidar-test pythonconda activate lidar-testcd lidar/pip install -e .Create a branch for local development:git checkout -b name-of-your-bugfix-or-featureNow you can make your changes locally.When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:flake8 lidar testspython setup.py test or pytestTo get flake8 and tox, just pip install them into your conda env.Commit your changes and push your branch to GitHub:git add .git commit -m "Your detailed description of your changes."git push origin name-of-your-bugfix-or-featureSubmit a pull request through the GitHub website.Pull Request GuidelinesBefore you submit a pull request, check that it meets these guidelines:The pull request should include tests.If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.md.The pull request should work for Python 3.7 and 3.8. Checkhttps://github.com/giswqs/lidar/actionsand make sure that the tests pass for all supported Python versions.CreditsThe algorithms are built onRichDEM,numpy,scipy,scikit-image, andpygdal.This package was created withCookiecutterand theaudreyr/cookiecutter-pypackageproject template.