You can happily use LSDTopoTools oblivious to the inner-workings of the code and how it all connects together to produce a suite of topographic analyses at your disposal. Ignorance is, as they say, bliss. No knowledge of Classes, Drivers, Objects, and so on, is needed to run the basic analyses supplied in the distribution of this software. However, you might wish to write your own driver functions, and may even be considering contributing to the core parts of the code. This way you can make your topographic techniques and algorithmic awesomeness available to like-minded geoscientists. Earlier, we mentioned breifly how the code is structured in the main body of this documentation. For those intrepid interrogators of empirical inquisition who have made it four levels down into the Appendix section, first of all, we salute you, and we reward you with a deeper look into how the code is structured, should you wish to contribute your own additions to the repository.
There are two main parts of the LSDTopoTools source code: the driver functions and the core component source files. The core files contain the implementations of topographic analyses, and many other functions for creating rasters, sorting data, performin file operations, writing output, and so on. All the core source files are name like LSDSomeFile. pp. They also come in pairs: a LSDSomeClass.cpp source file comes with a LSDSomeClass.hpp header file. The header file describes the interface to a parituclar source file. In other words, LSDSomeClass.hpp tells us what all the methods and data structures of a particular source file (LSD.cpp) are. For functions (or class methods to be precise…) the header file tells us what type of parameters the functions take as arguments, and what data types (if any) these functions return. They also describe how data structures are stored. For example, we could look in LSDRaster.hpp to see how the data members of a Raster are defined. We would see that an LSDRaster object has some meta-data telling us about the extent and coordinates of the the raster data, and an array that stores each pixel value in the raster. It would also tell us which functions (methods) would return information about the LSDRaster object. If we wanted to know the number of rows in a raster object we would see in the header file there is a getNRows() function, and so on. The .cpp files tell us how these functions are implemented, e.g. what exactly each function does when parameters are passed to it, and how it maniplulates the data stored with the object.
In general, although it is not required, we have kept one Class to one pair of header and implementation files. (Although there are a couple of exceptions to this). So in the LSDRaster.hpp and LSDRaster.cpp core files, you will find the declaration and implementation of the LSDRaster class, respectively. In short, hpp tells us what is there and how to use it, cpp tells us how it works. For a full description of all the LSDTopoTools objects and classes you can visit the automatically generated doxygen documentation.
The driver files are separated off into their own folder(s) and as their name suggests, they are responsible for driving a particular analysis by calling on different objects and functions defined in the core source files. The core LSDFooBar-type files we talked about previously don’t actually do much on their own — they are just a bunch of class data structures and methods. This is where the driver files come in: driver files are written to perform a certain kind of topographic analysis or model simulation using some form of input data created by you, the user. Driver files call upon different parts of the object files to perform topographic analyses. An example driver file may call upon LSDRaster to create a Raster object to store data from an input DEM, then it might pass this LSDRaster object to LSDFlowInfo to calculate the flow routing paths in the raster, and so on, until we have completed a useful analysis and written some output data to analyse.
Since there is such a variety of functions defined in the source code, there are potentially hundreds if not thousands of possible analyses that could be performed with the code. The driver files provided with the TopoTools distribution are designed to accomplish some of the more common topographic analysis tasks, e.g. extracting basins from a raster, calculating the location of channel heads in a landscape, running a chi-analysis on river channels, or extracting swath profiles, and so on. However, you are free to write your own driver files of course! What’s more, they provide an exact record of the analysis you have just done, and so are inherrently reproducible if you want to share your findings with others.
|
Tip
|
Another way to think of drivers, if you are familiar with C or C++ programming, is that they contain the int main() { } bit of a typical program. I.e. the main workflow of a program.
|
LSDRaster is the class that contains methods for mainipulating arrays of raster data loaded from a DEM file. There are also data members that store metadata about the raster, such as the typical header data you would find in a DEM file. It can perform typical analyses such as creating a hillshade raster, calculating curvature of ridgetops, calculating the location of channel heads in a landscape, filling sinks and pits in a DEM and so on — mainly analyses that are performed on the entire raster dataset. It also does the basic reading and writing to DEM files.
A simple and fairly short class that stores rasters data as integers, used for indexing of raster data, calculating bounding boxes for rasters with lots of NoData values around the edge (or surounding basins). Very similar to LSDRaster class except is only used for when an index or mask of a given raster is needed.
This class performs operations such as calculating flow direction, calculating upstream contributing pixels in a raster, calculating sources based on threshold pixel methods, and other flow related information (based on topographic analysis — not based on any particular hydrological fluid flow calculations). Note how this object has include statements for LSDRaster and LSDIndexRaster — it returns these type of objects from many of its methods. It uses the FastScape algorithm of Braun and Willet (2014).
This object contains the node indexes as well as the row and col indices for individual channel segments.
LSDChannel is our first class that inherits the public methods and data members of another, namely LSDIndexChannel. This means we have direct access to the public members of that class. Note, in the source code:
class LSDChannel: public LSDIndexChannel
{
public:
// Some method declarationsIndicates this class inherits from LSDIndexChannel. LSDChannel stores information about the actual channel characteristics, e.g. elevation etc.
JunctionNetwork contains the main parts of the implemented FastScape algorithm for creating channel junction networks that can be searched for network connectivity. The main inputs are a FlowInfo object and list of source nodes. It also contains functions for returning IndexChannel objects after calculating the layout of channel networks.
This object spawns vectors of LSDIndexChannels. They can be indexed by the LSDChannel network, but can also be independent of the channel network, storing longest channels from sources, for example. The class is designed to be flexible, it can be used either with the LSDFlowInfo or LSDJunctionNetwork classes.
This object is principally used to identify segments of differing channel steepness in chi-zeta space. It contains the implementation of the segment fitting algorithm, including the statistical model that determines the most likely partitionining combination of channels.