{"id":19553585,"url":"https://github.com/opengeos/lidar","last_synced_at":"2025-12-12T00:52:00.504Z","repository":{"id":43512468,"uuid":"133390634","full_name":"opengeos/lidar","owner":"opengeos","description":"A Python package for delineating nested surface depressions from digital elevation data.","archived":false,"fork":false,"pushed_at":"2024-04-30T13:21:03.000Z","size":14518,"stargazers_count":220,"open_issues_count":9,"forks_count":50,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-05-01T15:41:05.651Z","etag":null,"topics":["digital-elevation-model","gis","hydrological","image-processing","lidar","python","remote-sensing","terrain-analysis"],"latest_commit_sha":null,"homepage":"https://lidar.gishub.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opengeos.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":"contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-14T16:26:53.000Z","updated_at":"2024-06-06T01:42:58.414Z","dependencies_parsed_at":"2024-05-16T21:00:43.446Z","dependency_job_id":"c392e8c6-6b0b-4365-a64e-d6d717d0b5cc","html_url":"https://github.com/opengeos/lidar","commit_stats":{"total_commits":194,"total_committers":6,"mean_commits":"32.333333333333336","dds":"0.030927835051546393","last_synced_commit":"d0ae666ea28ef01b2790da1526ec6728f9e908fa"},"previous_names":["giswqs/lidar"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opengeos%2Flidar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opengeos%2Flidar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opengeos%2Flidar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opengeos%2Flidar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opengeos","download_url":"https://codeload.github.com/opengeos/lidar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234923,"owners_count":20905854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["digital-elevation-model","gis","hydrological","image-processing","lidar","python","remote-sensing","terrain-analysis"],"created_at":"2024-11-11T04:23:55.774Z","updated_at":"2025-12-12T00:52:00.465Z","avatar_url":"https://github.com/opengeos.png","language":"Python","funding_links":["https://www.buymeacoffee.com/giswqs"],"categories":[],"sub_categories":[],"readme":"# Welcome to the lidar package\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/giswqs/lidar/blob/master/examples/lidar_colab.ipynb)\n[![image](https://img.shields.io/pypi/v/lidar.svg)](https://pypi.python.org/pypi/lidar)\n[![image](https://pepy.tech/badge/lidar)](https://pepy.tech/project/lidar)\n[![image](https://img.shields.io/conda/vn/conda-forge/lidar.svg)](https://anaconda.org/conda-forge/lidar)\n[![image](https://github.com/opengeos/lidar/workflows/build/badge.svg)](https://github.com/opengeos/lidar/actions?query=workflow%3Abuild)\n[![image](https://github.com/opengeos/lidar/workflows/docs/badge.svg)](https://lidar.gishub.org)\n[![image](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![image](https://img.shields.io/twitter/follow/giswqs?style=social)](https://twitter.com/giswqs)\n[![image](https://img.shields.io/badge/Donate-Buy%20me%20a%20coffee-yellowgreen.svg)](https://www.buymeacoffee.com/giswqs)\n[![DOI](https://joss.theoj.org/papers/10.21105/joss.02965/status.svg)](https://doi.org/10.21105/joss.02965)\n\n**lidar** is Python package for delineating the nested hierarchy of surface depressions in digital elevation models (DEMs). It is\nparticularly useful for analyzing high-resolution topographic data, such as DEMs derived from Light Detection and Ranging (LiDAR) data.\n\n-   GitHub repo: \u003chttps://github.com/opengeos/lidar\u003e\n-   Documentation: \u003chttps://lidar.gishub.org\u003e\n-   PyPI: \u003chttps://pypi.org/project/lidar\u003e\n-   Conda-forge: \u003chttps://anaconda.org/conda-forge/lidar\u003e\n-   Open in Colab: \u003chttps://gishub.org/lidar-colab\u003e\n-   Free software: [MIT license](https://opensource.org/licenses/MIT)\n\n**Citations**\n\n-   **Wu, Q.**, (2021). lidar: A Python package for delineating nested surface depressions from digital elevation data. _Journal of Open Source Software_, 6(59), 2965, \u003chttps://doi.org/10.21105/joss.02965\u003e\n-   **Wu, Q.**, Lane, C.R., Wang, L., Vanderhoof, M.K., Christensen,\n    J.R., \u0026 Liu, H. (2019). Efficient Delineation of Nested Depression\n    Hierarchy in Digital Elevation Models for Hydrological Analysis\n    Using Level-Set Method. _Journal of the American Water Resources\n    Association_. \u003chttps://doi.org/10.1111/1752-1688.12689\u003e ([PDF](https://spatial.utk.edu/pubs/2019_JAWRA.pdf))\n\n**Contents**\n\n-   [Introduction](#introduction)\n-   [Statement of Need](#statement-of-need)\n-   [State of the Field](#state-of-the-field)\n-   [Key Features](#key-features)\n-   [Installation](#installation)\n-   [Usage](#usage)\n-   [References](#references)\n-   [Contributing](#contributing)\n-   [Credits](#credits)\n\n## Introduction\n\n**lidar** is a Python package for delineating the nested hierarchy of\nsurface depressions in digital elevation models (DEMs). In traditional\nhydrological modeling, surface depressions in a DEM are commonly treated\nas artifacts and thus filled and removed to create a depressionless DEM,\nwhich can then be used to generate continuous stream networks. In\nreality, however, surface depressions in DEMs are commonly a combination\nof spurious and actual terrain features. Fine-resolution DEMs derived\nfrom Light Detection and Ranging (LiDAR) data can capture and represent\nactual surface depressions, especially in glaciated and karst\nlandscapes. During the past decades, various algorithms have been\ndeveloped to identify and delineate surface depressions, such as\ndepression filling, depression breaching, hybrid breaching-filling, and\ncontour tree method. More recently, a level-set method based on graph\ntheory was proposed to delineate the nested hierarchy of surface\ndepressions. The **lidar** Python package implements the level-set\nmethod and makes it possible for delineating the nested hierarchy of\nsurface depressions as well as elevated terrain features. It also\nprovides an interactive Graphical User Interface (GUI) that allows users\nto run the program with minimal coding.\n\n## Statement of Need\n\nThe **lidar** package is intended for scientists and researchers who\nwould like to integrate surface depressions into hydrological modeling.\nIt can also facilitate the identification and delineation of\ndepressional features, such as sinkholes, detention basins, and prairie\npotholes. The detailed topological and geometric properties of surface\ndepressions can be useful for terrain analysis and hydrological\nmodeling, including the size, volume, mean depth, maximum depth, lowest\nelevation, spill elevation, perimeter, major axis length, minor axis\nlength, elongatedness.\n\n## State of the Field\n\nCurrently, there are a few open-source Python packages that can perform depression filling on digital elevation data, such as [RichDEM](https://richdem.readthedocs.io/) and [whitebox](https://github.com/giswqs/whitebox-python), the Python frontend for [WhiteboxTools](https://github.com/jblindsay/whitebox-tools). However, there are no Python packages offering tools for delineating the nested hierarchy of surface depressions and catchments as well as simulating inundation dynamics. The **lidar** Python package is intended for filling this gap.\n\n## Key Features\n\n-   Smoothing DEMs using mean, median, and Gaussian filters.\n-   Extracting depressions from DEMs.\n-   Filtering out small artifact depressions based on user-specified minimum depression size.\n-   Generating refined DEMs with small depressions filled but larger depressions kept intact.\n-   Delineating depression nested hierarchy using the level-set method.\n-   Delineating mount nested hierarchy using the level-set method.\n-   Computing topological and geometric properties of depressions, including size, volume, mean depth, maximum depth, lowest elevation,\n    spill elevation, perimeter, major axis length, minor axis length, elongatedness, eccentricity, orientation, and area-bbox-ratio.\n-   Exporting depression properties as a csv file.\n\n## Installation\n\n**lidar** supports a variety of platforms, including Microsoft Windows,\nmacOS, and Linux operating systems. Note that you will need to have\n**Python 3.x** (\u0026lt; 3.9) installed. Python 2.x is not supported.\n**lidar** is available on both [PyPI](https://pypi.python.org/pypi/lidar) and [conda-forge](https://anaconda.org/conda-forge/lidar).\nlidar has a [GDAL](https://gdal.org/) dependency, which can be challenging to install using pip on Windows.\nTherefore, it is highly recommended to install lidar from the conda-forge channel.\nIf you encounter any errors, please check the [Dependencies](#dependencies) section below.\n\n### Install from PyPI\n\nTo install **lidar** from PyPI, run this command in your terminal:\n\n```console\npip install lidar\n```\n\n### Install from conda-forage\n\nIf you have [Anaconda](https://www.anaconda.com/distribution/#download-section) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html)\ninstalled on your computer, you can create a fresh conda environment to install lidar:\n\n```console\nconda create -n geo python=3.11\nconda activate geo\nconda install -c conda-forge mamba\nmamba install -c conda-forge lidar\n```\n\n### Upgrade lidar\n\nIf you have installed lidar before and want to upgrade to the latest version, you can run the following command in your terminal:\n\n```console\npip install -U lidar\n```\n\nIf you use conda, you can update lidar to the latest version by running the following command in your terminal:\n\n```console\nmamba update -c conda-forge lidar\n```\n\nTo install the development version from GitHub directly using Git, run the following code:\n\n```console\npip install git+https://github.com/opengeos/lidar\n```\n\n### Dependencies\n\nlidar's Python dependencies are listed in its [requirements.txt](https://github.com/opengeos/lidar/blob/master/requirements.txt) file. In\naddition, lidar has a C library dependency: GDAL \u0026gt;=1.11.2. How to\ninstall GDAL in different operating systems will be explained below.\nMore information about GDAL can be found [here](https://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries).\n\n#### Linux\n\n##### Debian-based Linux\n\nThe following commands can be used to install GDAL for Debian-based\nLinux distributions (e.g., Ubuntu, Linux Mint).\n\n```console\nsudo add-apt-repository ppa:ubuntugis/ppa\nsudo apt-get update\nsudo apt-get install gdal-bin libgdal-dev\n```\n\nIf you encounter any compiling errors, try the following commands.\n\n```console\nsudo apt-get install --reinstall build-essential\nsudo apt-get install python3-dev\npip install wheel\n```\n\n##### Pacman-based Linux\n\nThe following commands can be used to install GDAL for Pacman-based\nLinux distributions (e.g., Arch Linux, Manjaro). You might need to use\n**sudo** if you encounter permission errors.\n\n```console\nsudo pacman -S yaourt --noconfirm\nyaourt -S gdal --noconfirm\nyaourt -S python-gdal --noconfirm\n```\n\n#### macOS\n\nFor a Homebrew based Python environment, do the following.\n\n```console\nbrew update\nbrew install gdal\n```\n\nAlternatively, you can install GDAL binaries from [kyngchaos](http://www.kyngchaos.com/software/frameworks#gdal_complete). You will\nthen need to add the installed location\n`/Library/Frameworks/GDAL.framework/Programs` to your system path.\n\n#### Windows\n\nThe instruction below assumes that you have installed [Anaconda](https://www.anaconda.com/download). Open\n**Anaconda Prompt** and enter the following commands to create a conda\nenvironment and install required packages\n\n```console\nconda create -n geo python=3.11\nconda activate geo\nconda install -c conda-forge mamba\nmamba install -c conda-forge lidar\n```\n\nWhen installing the **lidar** package, if you encounter an error\nsaying `Microsoft Visual C++ 14.0 is required`, please follow the steps\nbelow to fix the error and reinstall **lidar**. More information can\nbe found at this link [Fix Python 3 on Windows error - Microsoft Visual C++ 14.0 is required](https://www.scivision.co/python-windows-visual-c++-14-required/).\n\n-   Download [Microsoft Build Tools for Visual Studio 2017](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools\u0026rel=15)\n-   Double click to install the downloaded installer - **Microsoft Build Tools for Visual Studio 2017**.\n-   Open **Microsoft Build Tools for Visual Studio 2017**\n-   Select **Workloads --\u003e Visual C++ build tools** and click the install button\n\n## Usage\n\nLaunch the interactive notebook tutorial for the **lidar** Python\npackage with **Google Colab** now:\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/giswqs/lidar/blob/master/examples/lidar_colab.ipynb)\n\n### A quick example\n\n```python\nimport os\nimport pkg_resources\nfrom lidar import *\n\n# identify the sample data directory of the package\npackage_name = 'lidar'\ndata_dir = pkg_resources.resource_filename(package_name, 'data/')\n\n# use the sample dem. Change it to your own dem if needed\nin_dem = os.path.join(data_dir, 'dem.tif')\n# set the output directory\nout_dir = os.getcwd()\n\n# parameters for identifying sinks and delineating nested depressions\nmin_size = 1000      # minimum number of pixels as a depression\nmin_depth = 0.5      # minimum depth as a depression\ninterval = 0.3       # slicing interval for the level-set method\nbool_shp = True      # output shapefiles for each individual level\n\n# extracting sinks based on user-defined minimum depression size\nout_dem = os.path.join(out_dir, \"median.tif\")\nin_dem = MedianFilter(in_dem, kernel_size=3, out_file=out_dem)\nsink_path = ExtractSinks(in_dem, min_size, out_dir)\ndep_id_path, dep_level_path = DelineateDepressions(sink_path,\n                                                   min_size,\n                                                   min_depth,\n                                                   interval,\n                                                   out_dir,\n                                                   bool_shp)\nprint('Results are saved in: {}'.format(out_dir))\n```\n\n### lidar GUI\n\n**lidar** also provides a Graphical User Interface (GUI), which can be\ninvoked using the following Python script:\n\n```python\nimport lidar\nlidar.gui()\n```\n\n![image](https://i.imgur.com/6hLGeV5.png)\n\n## lidar toolbox for ArcGIS Pro\n\n### Toolbox interface\n\n![toolbox](https://raw.githubusercontent.com/giswqs/lidar/master/images/toolbox_0.png)\n\n![toolbox_ui](https://raw.githubusercontent.com/giswqs/lidar/master/images/toolbox_ui.png)\n\n### Video tutorials\n\n[**Delineating nested surface depressions and catchments using ArcGIS Pro**](https://youtu.be/PpF8sfvCATE)\n\n[![demo](http://img.youtube.com/vi/W9PFHNV3cT0/0.jpg)](http://www.youtube.com/watch?v=W9PFHNV3cT0)\n\n[**Delineating nested surface depressions and catchments using ArcMap**](https://youtu.be/PpF8sfvCATE)\n\n[![demo](http://img.youtube.com/vi/PpF8sfvCATE/0.jpg)](http://www.youtube.com/watch?v=PpF8sfvCATE)\n\n### A real-world example\n\nThe images below show working examples of the level set method for\ndelineating nested depressions in the Cottonwood Lake Study Area (CLSA),\nNorth Dakota. More test datasets (e.g., the Pipestem watershed in the\nPrairie Pothole Region of North Dakota) can be downloaded from\n\u003chttp://gishub.org/2019-JAWRA-Data\u003e\n\nThe following example was conducted on a 64-bit Linux machine with a\nquad-core Intel i7-7700 CPU and 16 GB RAM. The average running time of\nthe algorithm for this DEM was 0.75 seconds.\n\n![image](https://wetlands.io/file/images/CLSA_DEM.jpg)\n\n![image](https://wetlands.io/file/images/CLSA_Result.jpg)\n\n![image](https://wetlands.io/file/images/CLSA_Table.jpg)\n\n## References\n\nThe level-set algorithm was proposed by **Wu** et al. (2019):\n\n-   **Wu, Q.**, Lane, C.R., Wang, L., Vanderhoof, M.K., Christensen,\n    J.R., \u0026 Liu, H. (2019). Efficient Delineation of Nested Depression\n    Hierarchy in Digital Elevation Models for Hydrological Analysis\n    Using Level-Set Method. _Journal of the American Water Resources\n    Association_. DOI: [10.1111/1752-1688.12689](https://doi.org/10.1111/1752-1688.12689) ([PDF](https://spatial.utk.edu/pubs/2019_JAWRA.pdf))\n\nApplications of the level-set and contour-tree methods for feature\nextraction from LiDAR data:\n\n-   **Wu, Q.**, \u0026 Lane, C.R. (2017). Delineating wetland catchments and\n    modeling hydrologic connectivity using LiDAR data and aerial\n    imagery. _Hydrology and Earth System Sciences_. 21: 3579-3595. DOI:\n    [10.5194/hess-21-3579-2017](https://doi.org/10.5194/hess-21-3579-2017)\n-   **Wu, Q.**, Deng, C., \u0026 Chen, Z. (2016). Automated delineation of\n    karst sinkholes from LiDAR-derived digital elevation models.\n    _Geomorphology_. 266: 1-10. DOI:\n    [10.1016/j.geomorph.2016.05.006](http://dx.doi.org/10.1016/j.geomorph.2016.05.006)\n-   **Wu, Q.**, Su, H., Sherman, D.J., Liu, H., Wozencraft, J.M., Yu,\n    B., \u0026 Chen, Z. (2016). A graph-based approach for assessing\n    storm-induced coastal changes. _International Journal of Remote\n    Sensing_. 37:4854-4873. DOI:\n    [10.1080/01431161.2016.1225180](http://dx.doi.org/10.1080/01431161.2016.1225180)\n-   **Wu, Q.**, \u0026 Lane, C.R. (2016). Delineation and quantification of\n    wetland depressions in the Prairie Pothole Region of North Dakota.\n    _Wetlands_. 36(2):215–227. DOI:\n    [10.1007/s13157-015-0731-6](http://dx.doi.org/10.1007/s13157-015-0731-6)\n-   **Wu, Q.**, Liu, H., Wang, S., Yu, B., Beck, R., \u0026 Hinkel, K.\n    (2015). A localized contour tree method for deriving geometric and\n    topological properties of complex surface depressions based on\n    high-resolution topographic data. _International Journal of\n    Geographical Information Science_. 29(12): 2041-2060. DOI:\n    [10.1080/13658816.2015.1038719](http://dx.doi.org/10.1080/13658816.2015.1038719)\n-   **Wu, Q.**, Lane, C.R., \u0026 Liu, H. (2014). An effective method for\n    detecting potential woodland vernal pools using high-resolution\n    LiDAR data and aerial imagery. _Remote Sensing_. 6(11):11444-11467.\n    DOI: [10.3390/rs61111444](http://dx.doi.org/10.3390/rs61111444)\n\n## Contributing\n\nContributions are welcome, and they are greatly appreciated! Every\nlittle bit helps, and credit will always be given. You can contribute in many ways:\n\n### Types of Contributions\n\n#### Report Bugs\n\nReport bugs at \u003chttps://github.com/opengeos/lidar/issues\u003e.\n\nIf you are reporting a bug, please include:\n\n-   Your operating system name and version.\n-   Any details about your local setup that might be helpful in troubleshooting.\n-   Detailed steps to reproduce the bug.\n\n#### Fix Bugs\n\nLook through the GitHub issues for bugs. Anything tagged with \"bug\" and \"help wanted\" is open to whoever wants to implement it.\n\n#### Implement Features\n\nLook through the GitHub issues for features. Anything tagged with \"enhancement\" and \"help wanted\" is open to whoever wants to implement it.\n\n#### Write Documentation\n\nlidar 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.\n\n#### Submit Feedback\n\nThe best way to send feedback is to file an issue at \u003chttps://github.com/opengeos/lidar/issues\u003e.\n\nIf you are proposing a feature:\n\n-   Explain in detail how it would work.\n-   Keep the scope as narrow as possible, to make it easier to implement.\n-   Remember that this is a volunteer-driven project, and that contributions are welcome.\n\n### Get Started\n\nReady to contribute? Here's how to set up _lidar_ for local development.\n\n1. Fork the [lidar](https://github.com/opengeos/lidar) repo on GitHub.\n\n2. Clone your fork locally:\n\n```console\ngit clone git@github.com:your_name_here/lidar.git\n```\n\n3. Install your local copy into a conda env. Assuming you have conda installed, this is how you set up your fork for local development:\n\n```console\nconda create -n lidar-test python\nconda activate lidar-test\ncd lidar/\npip install -e .\n```\n\n4. Create a branch for local development:\n\n```console\ngit checkout -b name-of-your-bugfix-or-feature\n```\n\nNow you can make your changes locally.\n\n5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:\n\n```console\nflake8 lidar tests\npython setup.py test or pytest\n```\n\nTo get flake8 and tox, just pip install them into your conda env.\n\n6. Commit your changes and push your branch to GitHub:\n\n```console\ngit add .\ngit commit -m \"Your detailed description of your changes.\"\ngit push origin name-of-your-bugfix-or-feature\n```\n\n7. Submit a pull request through the GitHub website.\n\n### Pull Request Guidelines\n\nBefore you submit a pull request, check that it meets these guidelines:\n\n1. The pull request should include tests.\n2. 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.\n3. The pull request should work for Python 3.7 and 3.8. Check \u003chttps://github.com/opengeos/lidar/actions\u003e and make sure that the tests pass for all supported Python versions.\n\n## Credits\n\n-   The algorithms are built on [RichDEM](https://github.com/r-barnes/richdem), [numpy](https://www.numpy.org), [scipy](https://www.scipy.org), [scikit-image](https://scikit-image.org), and [pygdal](https://github.com/nextgis/pygdal).\n-   This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage) project template.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopengeos%2Flidar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopengeos%2Flidar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopengeos%2Flidar/lists"}