Developing a MATLAB Toolbox for Digital Elevation Model Analysis

About 10 years ago, my research into the evolution of the earth’s surface led me to a computational challenge: Given a digital elevation model (DEM) of a region’s surface terrain, was there a fast and elegant way to calculate how much water flows through any given landscape during and after precipitation?

The answer was to use MATLAB^® to solve the problem as a system of linear equations. This approach was the genesis of TopoToolbox, a set of MATLAB functions that I developed for analyzing flow pathways in DEMs (Figure 1).

I have used MATLAB and TopoToolbox to accelerate my own research, including studies that predict where landslides are most likely to occur, how extreme floods spread through mountain valleys, and explorations of geologic phenomena such as rapid uplift and divide migration. Researchers around the world have used the toolbox to study water flows in glaciers, the formation of supraglacial lakes and fjords, and the way stream networks are deformed when tectonic plates shift laterally. To date, TopoToolbox has been cited in more than 180 published papers in peer-reviewed scientific journals.

Creating and Sharing TopoToolbox Version 1

When I began looking for ways to calculate water flows across a landscape, I was new to MATLAB and to programming. My initial solution to the problem was far from elegant—for example, it used numerous loops instead of vectorized operations to perform the calculations. Looking for help, I posed a question to the MATLAB community on MATLAB Central. One contributor suggested using a large sparse matrix and solving linear equations. This suggestion opened my eyes to the elegance and efficiency of matrix algebra in MATLAB. When I implemented this approach in MATLAB, I recognized that it had several potential applications. For example, it could be used to calculate the distance that each raindrop would travel before arriving at a catchment or to delineate the catchments themselves. That was when I decided to create the first version of TopoToolbox.

I made TopoToolbox available via the University of Colorado Community Surface Dynamics Modeling System (CSDMS) site, and it became that site’s most downloaded tool. I have also published TopoToolbox via GitHub and via the File Exchange on MATLAB Central, where it is downloaded dozens of times every month.

Adopting an OOP Approach for Version 2

For TopoToolbox version 2, I decided to take advantage of the object-oriented programming (OOP) capabilities in MATLAB. In version 1, I did not use objects. As a result, the code was quite difficult for me to maintain and difficult for others to understand, particularly as sophisticated new features were added. Adopting an OOP approach made my job as a developer much easier. For example, I took advantage of the ability to overload functions in MATLAB to make some existing MATLAB functions work with my own user-defined classes.

The OOP approach made the code more intuitive for end users. In a typical workflow, for example, a researcher loads a gridded DEM into MATLAB using the toolbox GRIDobj and then generates a FLOWobj, which derives the local flow directions for each pixel in the DEM. The researcher might then focus on the fluvial domain—the areas where enough water has accumulated for rivers to flow—by using the flow directions to derive a STREAMobj that describes the geometry and topology of a river network. At a later stage, this linear workflow might become more complex as information is exchanged between the different objects (Figure 2).

Improving the Toolbox with Help from the Research Community

My decision to use OOP made it much easier for users to contribute improvements to the toolbox code. For example, my colleague Dirk Scherler, who is a co-developer of TopoToolbox, added a user interface (Figure 3) for analyzing landscapes in regions of active deformation. Phillipe Steer, a researcher from University of Rennes 1, who studies the interplay of tectonics and surface processes, contributed a comprehensive set of functions that enable peers to replicate his work in other regions of the world.

Some improvements to the toolbox were implemented following the introduction of new features in MATLAB, some of which were introduced at my suggestion. Several years ago, for example, I submitted an enhancement request to MathWorks for a function that computes a gray-weighted distance transform for a grayscale image. In the next major release of Image Processing Toolbox™, MathWorks developers included a new function, graydist, which computes this transform. I subsequently incorporated it into TopoToolbox. TopoToolbox relies on Image Processing Toolbox because image processing has so much in common with DEM analysis. Users can use TopoToolbox with Mapping Toolbox™ to integrate with other geographic information system (GIS) software, but that toolbox is not required.

Recent Developments and Next Steps

I recently packaged the latest version of TopoToolbox (2.2) as a MATLAB toolbox file. Creating a single installation file (TopoToolbox.mltbx) makes it easier for new users to install TopoToolbox: They simply double-click the file after downloading it and follow the on-screen instructions. Moreover, I increasingly include tools that make use of the graph theory algorithms and web mapping capabilities in MATLAB.

In addition to maintaining and updating TopoToolbox with contributions from others, I continue to add my own enhancements. I am currently working on new functions that incorporate machine learning features, such as multinomial logistic regression, Bayesian optimization, and the Hamiltonian Markov Chain Monte Carlo sampler class in Statistics and Machine Learning Toolbox™.