TopoToolbox is a MATLAB-based software designed for the analysis and visualization of topographic data. It provides a comprehensive set of tools for processing Digital Elevation Models (DEMs), extracting drainage networks, analyzing river profiles, and performing geomorphometric calculations. In addition, TopoToolbox facilitates hydrological modeling and landscape evolution studies. Its efficient algorithms and interactive visualization capabilities allow for detailed analysis of terrain features, helping to understand landscape processes and topographic changes over time.
Primary uses of TopoToolbox are in the field of geomorphology, hydrology, structural geology and tectonics, but there are many other applications ranging from meteorology to glaciology.
If you have any questions or remarks, please contact the authors:
TopoToolbox v3 is plat-form independent and requires MATLAB R2023b or higher and the Image Processing Toolbox. The Mapping Toolbox is not mandatory, but good to have to facilitate easy data exchange with GIS software. Some functions support parallelisation using the Parallel Toolbox. Few functions require the Optimization or Statistics and Machine Learning Toolbox.
If you are using an older version of MATLAB (< R2023b), use TopoToolbox 2.
The easiest way to get started with TopoToolbox 3 is to download the topotoolbox.mltbx file from the GitHub repository releases area. Double-click on the downloaded file to run the MATLAB add-on installer. This will copy the files to your MATLAB add-ons area and add TopoToolbox to your MATLAB search path.
Later, you can use the MATLAB Add-On Manager to uninstall.
As a developer, we recommend to fork and clone the TopoToolbox3 GitHub repository. Start by navigating to the original repository on GitHub and clicking the Fork button in the top right. This creates a copy of the repository in your own GitHub account. Next, clone the forked repository to your computer. Please read the contributor guidelines more about how to contribute code to TopoToolbox.
Alternatively, you can download the repository and save it to some folder on your harddrive. Before working with TopoToolbox the directories and functions must be on the search path of MATLAB. To do this, navigate your working directory to the topotoolbox3/toolbox folder and run the command:
tt2path
To make these paths permanent, use the command (this may require system administrator privileges).
savepath
The documentation will not be included in the code. To build the documentation, go to the folder docs and run the command
publishtthelp2html
This will build html-files that can be viewed in MATLABs documentation. You'll find the TopoToolbox documentation in the section Supplemental Software, once you restart MATLAB. The documentation contains several user's guides that will help you getting started. In addition, TopoToolbox functions have extensive help sections (e.g. help gradient8 or help STREAMobj/modify. An additional resource for code and examples is the TopoToolbox blog.
Finally, TopoToolbox comes with bindings to libtopotoolbox, a C-library for terrain analysis. Currently, all TopoToolbox functions will work also without libtopotoolbox. To compile libtopotoolbox, navigate to the topotoolbox3-folder and run the command
buildtool compile
To check whether compilation ran successfully, the following command
haslibtopotoolbox
should return true.
Once you have TopoToolbox installed, you should get started with reading a DEM into a GRIDobj, the numerical class containing single-band raster datasets. TopoToolbox comes with an example file which you can read using the following command.
DEM = GRIDobj('srtm_bigtujunga30m_utm11.tif');
Now plot this data using imageschs.
imageschs(DEM)
Well done. If this works, your TopoToolbox installation should run. Now, check what TopoToolbox has to offer and open the gettingStarted.mlx file which is found in the toolbox folder.
When you use TopoToolbox in your work, please reference following publication:
- Schwanghart, W., Scherler, D. (2014): TopoToolbox 2 – MATLAB-based software for topographic analysis and modeling in Earth surface sciences. Earth Surface Dynamics, 2, 1-7. DOI: 10.5194/esurf-2-1-2014
If you are using version 1, then please refer to this publication:
- Schwanghart, W., Kuhn, N.J. (2010): TopoToolbox: a set of MATLAB functions for topographic analysis. Environmental Modelling & Software, 25, 770-781. DOI: 10.1016/j.envsoft.2009.12.002
In addition, various models and algorithms implemented in TopoToolbox have been published in the following articles.
-
Schwanghart, W., Groom, G.B., Kuhn, N.J., Heckrath, G., 2013: Flow network derivation from a high resolution DEM in a low relief, agrarian landscape. Earth Surface Processes and Landforms, 38, 1576-1586. DOI: 10.1002/esp.3452
-
Schwanghart, W., Scherler, D., 2017. Bumps in river profiles: uncertainty assessment and smoothing using quantile regression techniques. Earth Surface Dynamics, 5, 821-839. DOI: 10.5194/esurf-5-821-2017
-
Campforts, B., Schwanghart, W., Govers, G. (2017): Accurate simulation of transient landscape evolution by eliminating numerical diffusion: the TTLEM 1.0 model. Earth Surface Dynamics, 5, 47-66. DOI: 10.5194/esurf-5-47-2017
-
HyLands: Campforts B., Shobe M.C., et al. (2020): HyLands 1.0: a Hybrid Landscape evolution model to simulate the impact of landslides and landslide-derived sediment on landscape evolution. Geosci. Model Dev., 13, 3863–3886. DOI: 10.5194/gmd-13-3863-2020
- Blöthe, J.H., Korup, O., Schwanghart, W., 2015: Large landslides lie low: Excess topography in the Himalaya-Karakorum ranges. Geology, 43, 523-526. DOI: 10.1130/G36527.1
- Stolle, A., Schwanghart, W., Andermann, C., Bernhardt, A., Fort, M., Jansen, J.D., Wittmann, H., Merchel, S., Rugel, G., Adhikari, B.R., Korup, O., 2019. Protracted river response to medieval earthquakes. Earth Surface Processes and Landforms, 44, 331-341. DOI: 10.1002/esp.4517 (The description here is very terse, yet)
-
Scherler, D., Schwanghart, W., 2020. Drainage divide networks – Part 1: Identification and ordering in digital elevation models. Earth Surface Dynamics, 8, 245–259. DOI: 10.5194/esurf-8-245-2020
-
Scherler, D., Schwanghart, W., 2020. Drainage divide networks – Part 2: Response to perturbations. Earth Surface Dynamics, 8, 261-274. DOI: 10.5194/esurf-8-261-2020
- Schwanghart, W., Molkenthin, C., & Scherler, D. (2020). A systematic approach and software for the analysis of point patterns on river networks. Earth Surface Processes and Landforms, 46, 9, 1847-1862. DOI: 10.1002/esp.5127
- new function: GRIDobj/randomsample - Create a spatially uniform sample based on a GRIDobj
- new function: tthelp - Search for keywords on the TopoToolbox blog
- new function: meltonruggedness (thanks for pointing out the bug, Kerry Leith!)
- new function: PPS/cdftest
- new function: GRIDobj/evansslope - calculate surface gradient using Evans method
- new function: GRIDobj/GRIDobj2rgb
- new function: getgriddedline(see utilities)
- new function: table2STREAMobj (see IOtools)
- new function: STREAMobj/bifurcationratio
- new function: GRIDobj/createrectmask
- STREAMobj2kml does not require the kml toolbox anymore.
- HyLands 1.0 added: see paper: Campforts, B. et al. (2020): HyLands 1.0: a Hybrid Landscape evolution
model to simulate the impact of landslides and landslide-derived sediment on landscape evolution
Geoscientific Model Development. DOI:10.5194/gmd-13-3863-2020 - new class: DIVIDEobj Paper 1 DOI: 10.5194/esurf-8-245-2020 Paper 2 DOI: 10.5194/esurf-8-261-2020
- new class: PPS DOI: 10.1002/esp.5127
- modification: update to ttscm to Scientific Colormaps 7.0 see Fabio Crameri's website
- new function: FLOWobj/plotdbfringe
- new function: FLOWobj/tfactor
- new function: private in FLOWobj graydistparallel
- new function: GRIDobj/diffusion
- new function: GRIDobj/histogram
- new function: GRIDobj/rand
- new function: PPS/extractvaluesaroundpoints
- new function: STREAMobj/extend2divide
- new function: STREAMobj/binarize
- modification: STREAMobj/modify
- modification: STREAMobj/wmplot
- new function: STREAMobj/loessksn
- new function: STREAMobj/STREAMobj2shape
- new function: STREAMobj/isequal
- new function: STREAMobj/isempty
- new function: STREAMobj/STREAMobj2kml
- new function: STREAMobj/getlocation
- new function: STREAMobj/fastscape
- modification: STREAMobj/smooth
- new function: STREAMobj/mnoptimvar
- modification: STREAMobj/STREAMobj2cell
- modification: STREAMobj/netdist and PPS/netdist
- new function: STREAMobj/istrunk
- modification: STREAMobj/trunk - added second output argument
- modification: GRIDobj/demprofile
- new function: ScaleBar
- new function: xlinerel and ylinerel
- new function: gif by Chad Greene see here
- topoapp was removed from this version
- updates to readopentopo
- updates to utilities: setextent and getextent
- new function: padextent
- new function: ukrainecolor
- Documentation in the documentation browser
- new function: ttcmap for creating nice colormaps for DEMs, particularly if DEMs include topography and bathymetry
- FLOWobj2gradient renamed to gradient
- new function: ttscm for access to scientific colormaps; see Fabio Crameri's website
- new function: mappingapp (lightweighed GUI for mapping points simultaneously in planform and profile view) still beta!
- new function: FLOWobj/mapfromnal
- enhancement: FLOWobj/multi2single allows area thresholding
- new function: STREAMobj/getvalue
- new function: STREAMobj/hillslopearea
- new function: STREAMobj/zerobaselevel
- new function: STREAMobj/knickpointfinder
- new function: STREAMobj/stackedplotdz
- new function: STREAMobj/sinuosity
- new function: STREAMobj/clean
- new function: STREAMobj/nal2nal
- new function: STREAMobj/netdist
- new function: STREAMobj/tribdir
- new function: GRIDobj/clip
- new function: GRIDobj/GRIDobj2im
- new function: GRIDobj/getextent
- new function: IOtools/readexample
- renamed GRIDobj/project2GRIDobj to GRIDobj/project. In addition, the function has a number of new functionalities.
- modification: STREAMobj/modify has new options for interactively modifying stream networks and to extract streams that confluence from a specified direction.
- changes to readopentopo, getcoordinates, getoutline, polygon2GRIDobj, line2GRIDobj
- new function: hydrosheds2FLOWobj (see in IOtools)
- new function: egm96heights including the grid ww15mgh.grd that contains global geoid undulations based on the EGM96 geoid.
- TTLEM is part of TopoToolbox; see our paper: Campforts, B., Schwanghart, W., Govers, G. (2017): Accurate simulation of transient landscape evolution by eliminating numerical diffusion: the TTLEM 1.0 model. Earth Surface Dynamics, 5, 47-66. DOI: 10.5194/esurf-5-47-2017
- new functions for smoothing and hydrological correction: STREAMobj/crs, STREAMobj/crsapp, STREAMobj/smooth, STREAMobj/crslin, STREAMobj/quantcarve, FLOWobj/quantcarve; see our paper: Schwanghart, W., Scherler, D., 2017. Bumps in river profiles: uncertainty assessment and smoothing using quantile regression techniques. Earth Surface Dynamics, 5, 821-839. DOI: 10.5194/esurf-5-821-2017
- modification: GRIDobj way to store referencing information was changed
- modification: FLOWobj now supports multiple flow directions and Dinf.
- modification: several new options for imageschs
- new function: FLOWobj/dbentropy
- new function: FLOWobj/updatetoposort
- new function: GRIDobj/aggregate
- new function: GRIDobj/createmask
- new function: GRIDobj/dist2line
- new function: GRIDobj/dist2curve
- new function: GRIDobj/line2GRIDobj
- new function: GRIDobj/GRIDobj2pm
- new function: GRIDobj/minmaxnorm
- new function: GRIDobj/reclabel
- new function: GRIDobj/zscore
- new function: GRIDobj/pad
- new function: STREAMobj/aggregate
- new function: STREAMobj/labelreach
- new function: STREAMobj/distance
- new function: STREAMobj/drainagedensity
- new function: STREAMobj/plotc
- new function: STREAMobj/plotdzshaded
- new function: STREAMobj/meanupstream
- new function: STREAMobj/plot3
- new function: STREAMobj/chitransform
- new function: STREAMobj/cumtrapz
- modification: STREAMobj/modify includes option rmconncomps
- new function: STREAMobj/mchi
- new function: STREAMobj/conncomps
- modification: STREAMobj/extractconncomps (new GUI and behavior)
- modification: STREAMobj/union (new syntax)
- modification: STREAMobj/intersect (new syntax)
- new function: STREAMobj/isnal
- new function: STREAMobj/info
- new function: STREAMobj/orientation
- new function: STREAMobj/plotstreamorder
- new function: STREAMobj/removeedgeeffects
- new function: STREAMobj/split
- new function: STREAMobj/streamproj
- new function: STREAMobj/networksegment
- new function: STREAMobj/maplateral
- new function: STREAMobj/plotsegmentgeometry
- new function: STREAMobj/randlocs
- new function: STREAMobj/zerobaselevel
- modification: STREAMobj/streamorder plotting option removed
- modification: STREAMobj/plotdz includes custom distance option
- modification: STREAMobj/distance includes option to derive distance from different STREAMobj
- modification: STREAMobj/STREAMobj2cell
- modification: STREAMobj/STREAMobj2mapstruct
- new function: STREAMobj/transformcoords
- new function: FLOWobj/FLOWobj2cell
- update to several FLOWobj methods to avoid speed loss for MATLAB versions newer than R2015b
- removed bug in GRIDobj/curvature
- new function: GRIDobj/excesstopography; see our paper Blöthe, J.H., Korup, O., Schwanghart, W. (2015): Large landslides lie low: Excess topography in the Himalaya-Karakorum ranges. Geology, 43, 523-526. DOI: 10.1130/G36527.1
- new function: GRIDobj/GRIDobj2polygon
- new function: STREAMobj/getnal
- new function: STREAMobj/sidebranching
- new function: STREAMobj/mincosthydrocon
- new function: STREAMobj/intersectlocs
- new function: STREAMobj/densify
- new function: STREAMobj/plot3d
- new function: STREAMobj/widenstream
- new function: demo_modifystreamnet
- modification of the function slopearea
- better performance of FLOWobj when converting from flow direction matrix by using dmperm to perform topological sort
- new function: GRIDobj/toposhielding
- new function: demarea (incorporation of Juernjakob Dugge's function: http://www.mathworks.com/matlabcentral/fileexchange/42204-calculate-dem-surface-area )
- new function: GRIDobj/getoutline
- removed a bug when some functions such log, log10 were called with integer GRIDobjs
- additional overloading of built-in functions for GRIDobjs. We added matrix arithmetics, which, however, perform element-wise operations (e.g. mtimes can be used with GRIDobj now, but performs times)
- the scope of the function GRIDobj/localtopography was enhanced (min, max, percentiles, etc in a disk-shaped neighborhood)
- FLOWobj/streampoi and STREAMobj/streampoi now return 'bconfluences', e.g. stream pixels that in downstream direction are located immediately before confluences.
- new function: STREAMobj/imposemin - limits downstream minima imposition to the stream network
- several bug fixes
- demo_modifystreamnet.m
- preprocessapp was removed
- removed bug in GRIDobj
- removed bug with case-sensitivity in some functions
- removed bug with internal drainage option in FLOWobj
- new functions STREAMobj/intersect, STREAMobj/union
- new interactive tools in STREAMobj/modify
- new interactive tool GRIDobj/measure
V2.0 introduces an object oriented approach towards grid representation, flow direction, stream networks and swath objects. The performance of various, inparticular flow related, functions was increased. Mex-files have been written to increase the speed of some functions and are delivered as 64bit Windows binaries. They have been compiled on Windows 7 with an Intel processor, so they should be compiled before using them, if your system differs. However, compiling is not mandatory, since m versions are available, too, which are a little slower. Please refer to the Contents.m file for a complete list of functions.
- new function: acv
- new function: cropmat
- new function: dbentropy
- new function: deminpaint
- new function: exaggerate
- new function: label2poly
- new function: routegeodesic (as optimal method for routing through flats and pits). Requires Matlab 2011b and will be made the default routing algorithm in future releases.
- new function: upslopesidelength
- new function: upslopestats
- new function: getextent and setextent
- function enhancements: rasterread and rasterwrite.
- function enhancements: roughness
- new users guide on processing flat areas
- the baranja_hill.mat dataset was added. It was obtained from here: http://geomorphometry.org/content/baranja-hill
- some of the functions now employ the function validateattributes to check input arguments. Note that this might return a warning on older versions than 2009a.
- a bug in routeflats was removed
- new function: M2UV
- new function: twi
- new function: aspect
- new function: ismulti
- new function: postprocflats
- new function: demsobel
- new function: hypscurve
- new function: roughness
- removed bug in flowacc. flowacc returned an error when called with three input arguments
- gradient8 allows you to output different angular units, major speed increase when called with gradient as sole output argument.
- functional enhancements to flowdistance (see help flowdistance)
- functional enhancements to identifyflats
- rasterread and rasterwrite now feature dialog boxes for reading and saving files if no filenames are supplied to the function
- flowdistanceds can now calculate the maximum downward flowpath distance for each cell at one step.
- a bug in flowacc_lm was removed. When a weight matrix W0 was supplied as additional input argument, W0 was set to dem.
- new function: imageschs
- minor changes to hillshade were made. The algorithm is now based on method proposed by Katzil and Doytsher, 2003.
- flowacc allows for another input argument (runoff ratio).
- sub-basin analysis has been added as new functionality (see sbstruct, sbplot, sbprops)
- new function: adjustgauges
- major speed enhancement for fillsinks with maximum fill depth
- hillshade plots the hillshade matrix when no output arguments are defined.
- flowacc_lm was optimized, so that large, flat areas are handled more memory efficiently.
- a bug in routeflats was removed.
- crossflats was updated to run most efficient on Matlab R2009a.
- drainagebasins functionality was enhanced to allow for the delineation of drainage basins of specified order. The former support of multiple flow direction has been removed.
- new function: drainagedensity
- new function: shufflelabel
- influencemap got a second output Mstreams
- release