{"id":21881697,"url":"https://github.com/r-barnes/richdem","last_synced_at":"2025-04-12T19:49:19.750Z","repository":{"id":6237382,"uuid":"7469158","full_name":"r-barnes/richdem","owner":"r-barnes","description":"High-performance Terrain and Hydrology Analysis ","archived":false,"fork":false,"pushed_at":"2024-06-24T02:15:29.000Z","size":11785,"stargazers_count":280,"open_issues_count":55,"forks_count":73,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-12T19:48:53.553Z","etag":null,"topics":["big-data","digital-elevation-model","geosciences","geospatial","hydrologic-modeling","hydrology"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r-barnes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","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":"2013-01-06T15:33:34.000Z","updated_at":"2025-03-25T15:48:05.000Z","dependencies_parsed_at":"2023-01-13T15:15:13.830Z","dependency_job_id":"b572689c-8176-4da2-a949-9226fc103e4b","html_url":"https://github.com/r-barnes/richdem","commit_stats":{"total_commits":2488,"total_committers":8,"mean_commits":311.0,"dds":0.007234726688102877,"last_synced_commit":"eb7bac6e12efa750e8d6140d99b2d18bf9c0b81d"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-barnes%2Frichdem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-barnes%2Frichdem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-barnes%2Frichdem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-barnes%2Frichdem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r-barnes","download_url":"https://codeload.github.com/r-barnes/richdem/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625501,"owners_count":21135513,"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":["big-data","digital-elevation-model","geosciences","geospatial","hydrologic-modeling","hydrology"],"created_at":"2024-11-28T09:20:00.322Z","updated_at":"2025-04-12T19:49:19.724Z","avatar_url":"https://github.com/r-barnes.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"RichDEM\n=======\n\n[![ReadTheDocs](https://readthedocs.org/projects/richdem/badge/?version=latest)](https://richdem.readthedocs.io/)\n[![Travis](https://travis-ci.org/r-barnes/richdem.svg?branch=master)](https://travis-ci.org/r-barnes/richdem)\n[![DOI](https://zenodo.org/badge/7469158.svg)](https://zenodo.org/badge/latestdoi/7469158)\n\nAuthor: Richard Barnes (rbarnes@umn.edu)\n\nRichDEM is a set of digital elevation model (DEM) hydrologic analysis tools.\nRichDEM uses parallel processing and state of the art algorithms to quickly\nprocess even very large DEMs.\n\nRichDEM offers a variety of flow metrics, such as D8 and D∞. It can flood or\nbreach depressions. It can calculate flow accumulation, slops, curvatures, \u0026c.\n\nRichDEM is available as a performant C++ library, a low-dependency Python\npackage, and a set of command-line tools.\n\nPlease cite RichDEM (see below).\n\n\n\nUsing It\n========\n\nCiting It\n---------\n\nAs of 883ea734e957, David A. Wheeler's SLOCCount estimates the value of RichDEM\nat $240,481 and 1.78 person-years of development effort. This value is yours to\nuse, but citations are encouraged as they provide justification of continued\ndevelopment.\n\nGeneral usage of the library can be cited as:\n\n    Barnes, Richard. 2016. RichDEM: Terrain Analysis Software. http://github.com/r-barnes/richdem\n\nAn example BibTeX entry is:\n\n    @manual{RichDEM,\n      title        = {RichDEM: Terrain Analysis Software},\n      author       = {Richard Barnes},\n      year         = {2016},\n      url          = {http://github.com/r-barnes/richdem},\n    }\n\nThis information will be updated as versioned releases become available.\n\nAlthough I have written all of the code in this library, some of the algorithms\nwere discovered or invented by others, and they deserve credit for their good\nwork. Citations to particular algorithms will be printed whenever an app,\nprogram, or library function is run. Such citations are prefixed by the\ncharacter `C` and look like:\n\n    C Barnes, R., Lehman, C., Mulla, D., 2014. Priority-flood: An optimal depression-filling and watershed-labeling algorithm for digital elevation models. Computers \u0026 Geosciences 62, 117–127. doi:10.1016/j.cageo.2013.04.024\n\nA typical academic citation might read as follows:\n\n \u003e We performed hydrological corrections on our DEM using the Zhou (2016) algorithm implemented in RichDEM (Barnes 2016).\n\n\n\nCompilation\n-----------\n\nTo compile, first acquire the source code:\n\n    git clone --recursive https://github.com/r-barnes/richdem\n\nYou will need a C++ compiler, *cmake*, and, optionally, *libgdal*. If you are\nusing *conda*, you can install these requirements in a new environment with\nthe following commands:\n\n    $ conda create -n richdem\n    $ conda activate richdem\n    $ conda install --file=requirements.txt -c conda-forge\n\nThen compile using the standard `cmake` sequence:\n\n    $ mkdir build\n    $ cd build\n    $ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..\n    $ make -j 6    # Adjust to use more or fewer processors\n\nIf you do not want to build *richdem* with *gdal*, use the `-DUSE_GDAL=OFF`\noption. To install *richdem*:\n\n    $ cmake --install . --prefix /my/install/prefix\n\nIf you are using *conda*, `/my/install/prefix` should be `$CONDA_PREFIX`.\n\nRichDEM includes some programs to process extremely large digital elevation\nmodels, as well as for handling many DEM formats. Special prerequisites,\nautomatically detected by cmake, are needed for these to compile: GDAL, MPI, and\nBoost. To install these on a Debian machine use:\n\n    sudo apt install openmpi-bin libgdal-dev libopenmpi-dev libboost-iostreams-dev\n\n\n\nAs A Python Package\n-------------------\n\n### From source\n\nAfter installing the *richdem* library (as described above), you can build\n*richdem* as a Python package. To do this, you will of course need Python\n(3.7+), which you can install with *conda*,\n\n    $ conda install python\n\nYou can now build the *richdem* Python package,\n\n    $ cd wrappers/pyrichdem\n    $ pip install pybind11\n    $ python3 setup.py install --user\n\n### From conda\n\nTo install a pre-built version of *richdem* using *conda*,\n\n    $ conda install richdem -c conda-forge\n\n### From Google Colabs\n\nYou can compile and run RichDEM from source in Google Colabs by placing these\ncommands into a cell and running it.\n\n    !pip install pybind11\n    !git clone --recursive https://github.com/r-barnes/richdem.git ghrichdem\n    !cd ghrichdem/wrappers/pyrichdem \u0026\u0026 pip install .\n\n### From PyPI using pip\n\nGet the package with:\n\n    $ pip install richdem\n\nAnd use:\n\n    \u003e\u003e\u003e import richdem\n\nThe command:\n\n    \u003e\u003e\u003e help(richdem)\n\nprovides all the relevant documentation.\n\n\n\nAs A Command-line Tool\n----------------------\n\nTo get the command-line tools, install the Python package with:\n\n    pip3 install richdem\n\nThe command-line tools are all named `rd_*`, so typing `rd_` on your command-\nline and hitting tab a few times should give you the full list of what's\navailable.\n\n\n\nAs A Library\n------------\n\nUpon compilation, point your library search path to the `include` directory.\nInclude various files using, e.g.\n\n    #include \"richdem/common/Array2D.hpp\"\n\nAll files include extensive documentation. At this stage the location of certain\nfunctions may be subject to change. This will be noted in the `NEWS` file. (TODO)\n\n\n\nAs A Handy Collection of Tools\n------------------------------\n\nRunning `make` in the `apps` directory will produce a large number of useful\nscripts which are essentially wrappers around standard uses of the RichDEM\nlibraries. The [apps/README.md](apps/README.md) file and the apps themselves\ncontain documentation explaining what they all do.\n\n\n\nFor Processing Large Datasets\n-----------------------------\n\nThe `programs` directory contains several programs which have not been converted\nto libraries. This is usually because their functionality is specific and they\nare unlikely to be useful as a library. Each directory contains a makefile and a\nreadme explaining the purpose of the program.\n\n\n\nDocumentation\n-------------\n\nDocumentation is available at [richdem.com](https://richdem.com/).\nThe documentation is auto-generated from the many `README.md` files throughout\nthe codebase and the extensive comments in the source code.\n\n\n\nDesign Philosophy\n=================\n\nThe design of RichDEM is guided by these principles:\n\n* **Algorithms will be well-tested.** Every algorithm is verified by a rigorous\n  testing procedure. See below.\n\n* **Algorithms will be fast, without compromising safety and accuracy.** The\n  algorithms used in RichDEM are state of the art, permitting analyses that\n  would take days on other systems to be performed in hours, or even minutes.\n\n* **Algorithms will be available as libraries, whenever possible.** RichDEM is\n  designed as a set of header-only C++ libraries, making it easy to include in\n  your projects and easy to incorporate into other programming languages.\n  RichDEM also includes apps, which are simple wrappers around the algorithms,\n  and a limited, but growing, set of algorithms which may have special\n  requirements, like MPI, that make them unsuitable as libraries. These are\n  available as programs.\n\n* **Programs will have a command-line interface, not a GUI.** Command-line\n  interfaces are simple to use and offer extreme flexibility for both users and\n  programmers. They are available on every type of operating system. RichDEM\n  does not officially support any GUI. Per the above, encapsulating RichDEM in\n  a high-level interface of your own is not difficult.\n\n* **Algorithms and programs will be portable.** Linux, Mac, and Windows should\n  all be supported.\n\n* **The code will be beautiful.** RichDEM's code utilizes sensible variable\n  names and reasonable abstractions to make it easy to understand, use, and\n  design algorithms. The code contains extensive internal documentation which is\n  DOxygen compatible.\n\n* **Programs and algorithms will provide useful feedback.** Progress bars will\n  appear if desired and the output will be optimized for machine parsing.\n\n* **Analyses will be reproducible.** Every time you run a RichDEM command that\n  command is logged and timestamped in the output data, along with the version\n  of the program you created the output with. Additionally, a history of all\n  previous manipulations to the data is kept. Use `rd_view_processing_history`\n  to see this.**\n\n\n\nTesting Methodology\n===================\n\nSimple algorithms are shown to be correct through visual inspection and\ncomparison against hand-crafted examples. Correctness for more complex\nalgorithms is often \"boot-strapped\" by comparing the results of simple\nalgorithms versus the complex algorithms on a large number of randomly-generated\ndatasets.\n\nThis is a work in progress. TODO\n\n\nCorrectness\n===========\n\nCorrectness is established via a number of methodologies building from code\ninspection in the simplest cases to output comparison between simple and complex\nimplementations.\n\nCorrectness is noted in source code comments under `@correctness` sections.\nThese are, in turn, printed to the Doxygen documentation output.\n\nA master list of how correctness was established for each algorithm is available\nat [tests/README.md](tests/README.md).\n\n\n\nParsable Output\n===================\n\nEvery line of output from RichDEM begins with one of the following characters,\nmaking it easy to parse with a machine.\n\n * **A**: Algorithm name\n\n * **a**: Analysis command: the command line used to run the program\n\n * **c**: Configuration information: program version, input files, and command\n          line options, \u0026c.\n\n * **C**: Citation for algorithm\n\n * **d**: Debugging info\n\n * **E**: Indicates an error condition\n\n * **i**: I/O: Amount of data loaded from disk\n\n * **m**: Miscallaneous counts\n\n * **n**: I/O: Amount of data transferred through a network\n\n * **p**: Progress information: inform the user to keep calm because we're\n          carrying on.\n\n * **r**: Amount of RAM used\n\n * **t**: Timing information: How long stuff took\n\n * **W**: Indicates a warning\n\n\nAll output data shall have the form:\n\n    \u003cINDICATOR CHARACTER\u003e \u003cMESSAGE/MEASUREMENT NAME\u003e [= \u003cVALUE\u003e [UNIT]]\n\nThe amount of whitespace may very for aesthetic purposes.\n\n\n\nSpecific Algorithms\n===================\nMany of the algorithms used in RichDEM are documented in journal or conference\npublications. In the case of older algorithms by other authors, it is often\npossible to find the paper in the literature. Some of the newer algorithms I\ndeveloped have not yet had a chance to be widely utilized. These algorithms are\nlisted below.\n\nAdditionally, each publication has its own GitHub repository featuring\neasily-compiled, minimum working examples of the algorithms, along with examples\nand test data sets.\n\nThese are available as follows:\n\n * Flat-resolution algorithm. [Link](https://github.com/r-barnes/Barnes2013-FlatSurfaces)\n * Depression-filling algorithm. [Link](https://github.com/r-barnes/Barnes2013-Depressions)\n * Large dataset depression-filling algorithm. [Link](https://github.com/r-barnes/Barnes2016-ParallelPriorityFlood)\n * Large dataset flow accumulation algorithm. [Link](https://github.com/r-barnes/Barnes2016-ParallelFlowAccum)\n\n\n\nPublications\n============\nThe algorithms used in RichDEM have been published in the following articles. Every algorithm/program will provide its relevant citation information when run.\n\n* Barnes, R., 2017. Parallel non-divergent flow accumulation for trillion cell digital elevation models on desktops or clusters. Environmental Modelling \u0026 Software 92, 202–212. doi:[10.1016/j.envsoft.2017.02.022](https://doi.org/10.1016/j.envsoft.2017.02.022)\n\n* Barnes, R., 2016. Parallel priority-flood depression filling for trillion cell digital elevation models on desktops or clusters. Computers \u0026 Geosciences 96, 56–68. doi:[10.1016/j.cageo.2016.07.001](https://doi.org/10.1016/j.cageo.2016.07.001)\n\n* Barnes, R., Lehman, C., Mulla, D., 2014a. An efficient assignment of drainage direction over flat surfaces in raster digital elevation models. Computers \u0026 Geosciences 62, 128–135. doi:[10.1016/j.cageo.2013.01.009](https://doi.org/10.1016/j.cageo.2013.01.009)\n\n* Barnes, R., Lehman, C., Mulla, D., 2014b. Priority-flood: An optimal depression-filling and watershed-labeling algorithm for digital elevation models. Computers \u0026 Geosciences 62, 117–127. doi:[10.1016/j.cageo.2013.04.024](https://doi.org/10.1016/j.cageo.2013.04.024)\n\n* Barnes, Lehman, Mulla. 2011. \"Distributed Parallel D8 Up-Slope Area Calculation in Digital Elevation Models\". Intn'l Conf. on Parallel \u0026 Distributed Processing Techniques \u0026 Applications. [Link](http://rbarnes.org/section/sci/2011_barnes_distributed.pdf)\n\n* Horn, B.K.P., 1981. Hill shading and the reflectance map. Proceedings of the IEEE 69, 14–47. doi:[10.1109/PROC.1981.11918](http://dx.doi.org/10.1109/PROC.1981.11918)\n\n* Mulla et al. including Barnes. 2012. \"Strategic Planning for Minnesota’s Natural and Artificial Watersheds\". Report to the Minnesota LCCMR.\n\n* Tarboton, D.G. 1997. A new method for the determination of flow directions and upslope areas in grid digital elevation models. Water Resources Research. Vol. 33. pp 309-319.\n\n* Zevenbergen, L.W., Thorne, C.R., 1987. Quantitative analysis of land surface topography. Earth surface processes and landforms 12, 47–56.\n\n* Zhou, G., Sun, Z., Fu, S., 2016. An efficient variant of the Priority-Flood algorithm for filling depressions in raster digital elevation models. Computers \u0026 Geosciences 90, Part A, 87 – 96. doi:[10.1016/j.cageo.2016.02.021](http://dx.doi.org/10.1016/j.cageo.2016.02.021)\n\n\n\nCredits\n=======\n\nRichDEM has been developed and tested using computational resources provided by\nthe [Minnesota Supercomputing Institute](https://www.msi.umn.edu/) (MSI) and the\nU.S. National Science Foundation's [XSEDE](https://www.xsede.org/).\n\nFunding for the development of RichDEM has been provided by the [Legislative-Citizen Commission on Minnesota Resources](http://www.lccmr.leg.mn/) (LCCMR), the U.S. National Science\nFoundation [Graduate Research Fellowship](https://www.nsfgrfp.org/), and the U.S. Department of Energy\n[Computational Science Graduate Fellowship](https://www.krellinst.org/csgf/).\n\n\n\nFeedback\n========\n\n_If you see something, say something._\n\nUsers are encouraged to report any issues experienced with the code via Github's\nissue tracker. Feedback is also accepted via email (rbarnes@umn.edu), though\nthis is highly discouraged as it does not provide a resource for others.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-barnes%2Frichdem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr-barnes%2Frichdem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-barnes%2Frichdem/lists"}