Ways To Use It¶
Python package from PyPI¶
Get the package with:
pip3 install richdem
And use:
import richdem
The command:
help(richdem)
provides all the relevant documentation.
Python package from source¶
Enter the wrappers/pyrichdem
directory and run:
python3 setup.py install --user
As A Command-line Tool¶
To get the command-line tools, install the Python package with:
pip3 install richdem
The command-line tools are all named rd_*
, so typing rd_
on your command-
line and hitting tab a few times should give you the full list of what’s
available.
As A Library¶
As an overview, upon compilation, point your library search path to the
richdem/include
directory. Include various files using, e.g.
#include "richdem/common/Array2D.hpp"
All files include extensive documentation. At this stage the location of certain
functions may be subject to change. This will be noted in the NEWS
file. (TODO)
More concretely, there are a number of compilation options to consider. With the
GCC compiler the flag FLAG
is activated by passing the -DFLAG
command-line
argument.
NOPROGRESS
turns off progress barsRICHDEM_DEBUG
turns on line numbers and filenames in RichDEM’s outputRICHDEM_LOGGING
turns on outputs such as notices about memory allocation, intermediate products, various progress indicators, and so on. Enabling this requires inclusion of therichdem.cpp
file.RICHDEM_GIT_HASH
. this should be set to the git hash of the code you checked out. A value ofRICHDEM_GIT_HASH=$(git rev-parse HEAD)
is usually good.RICHDEM_COMPILE_TIME
. Date and time the code was compiled. A value ofRICHDEM_COMPILE_TIME=$(date -u +'%Y-%m-%d %H:%M:%S UTC')
is usually good.USEGDAL
. Indicates that GDAL functionality should be included in the library. This allows reading/writing rasters from various file types. It also complicates compilation slightly, as discussed below.NDEBUG
turns off a bunch of range-checking stuff included in the standard library. Increases speed slightly, butm akes debugging crashes and such more difficult.
Setting up compilation works like this:
CXXFLAGS="--std=c++11 -g -O3 -Wall -Wno-unknown-pragmas -Irichdem/include"
CXXFLAGS="$CXXFLAGS -DRICHDEM_LOGGING"
C++11 or higher is necessary to compile. Include other RichDEM flags as desired.
Note that the -g
flag doesn’t slow things down, though it does increase the
size of your executable somewhat. It’s inclusion is always recommended for
anything other than distributed production code because it makes debugging much
easier. The -O3
flag should be replaced by an optimization level or set of
your choice. -Wno-unknown-pragmas
hides warning messages from OpenMP if you
choose not to compile with it. -Wall
produces many helpful warning messages;
compiling without -Wall
is foolish. -Irichdem/include
connects your code
with RichDEM.
If you plan to use GDAL, include the following:
GDAL_LIBS="`gdal-config --libs`"
GDAL_CFLAGS="`gdal-config --cflags` -DUSEGDAL"
LIBS="$GDAL_LIBS"
CXXFLAGS="$CXXFLAGS $GDAL_CFLAGS"
If you plan to use RichDEM’s parallel features include the following:
LIBS=”$LIBS -fopenmp”
Finally, put it all together:
g++ $CXXFLAGS -o my_program.exe my_program.cpp $LIBS
As A Handy Collection of Tools¶
Running make
in the apps
directory will produce a large number of useful
scripts which are essentially wrappers around standard uses of the RichDEM
libraries. The [apps/README.md](apps/README.md) file and the apps themselves
contain documentation explaining what they all do.
For Processing Large Datasets¶
The programs
directory contains several programs which have not been converted
to libraries. This is usually because their functionality is specific and they
are unlikely to be useful as a library. Each directory contains a makefile and a
readme explaining the purpose of the program.