Contents.m

% TopoToolbox
% Version 2.4  14-June-2022
%
% TopoToolbox provides a set of Matlab functions that support the analysis
% of relief and flow pathways in digital elevation models. The major 
% aim of TopoToolbox is to offer helpful analytical GIS utilities in a 
% non-GIS environment in order to support the simultaneous application
% of GIS-specific and other quantitative methods.
%
% If you have any questions or remarks, please contact the authors:
%
% Wolfgang Schwanghart
% w.schwanghart[at]geo.uni-potsdam.de
%
% Dirk Scherler
% scherler[at]gfz-potsdam.de
% 
% When you use TopoToolbox in your work, please reference one of these 
% publications:
% 
% 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]
% 
% 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]
%
%
% Objects
%
%     GRIDobj         - object for gridded, geospatial data
%     FLOWobj         - object for flow direction
%     STREAMobj       - object for stream (channel) networks
%     DIVIDEobj       - object for drainage divide networks
%     SWATHobj        - object for swath profiles
%     PPS             - object for point patterns on stream networks
%
% Graphical user interfaces
%
%     flowpathapp     - Map, visualize and export flowpaths that start at manually set channelheads                     
%     slopeareatool   - Interactively create slope area plots and fit power laws                    
%     mappingapp      - Map points combining river planform and profile view
%
% GRIDobj methods
%
%     GRIDOBJ            : Create instance of a GRIDobj
%     GRIDOBJ2ASCII      : write/export GRIDobj to ESRI ArcGIS ASCII file
%     GRIDOBJ2GEOTIFF    : Exports an instance of GRIDobj to a geotiff file
%     GRIDOBJ2IM         : GRIDOBJ2IM Create image from GRIDobj
%     GRIDOBJ2MAT        : convert GRIDobj to matrix and coordinate vectors
%     GRIDOBJ2PM         : combine several GRIDobj into a predictor matrix
%     GRIDOBJ2POLYGON    : Conversion from drainage basin grid to polygon or polyline
%     GRIDOBJ2RGB        : Convert GRIDobj to RGB image
%     ACV                : Anisotropic coefficient of variation (ACV) 
%     AGGREGATE          : resampling a GRIDobj using aggregation
%     ARCSLOPE           : mean gradient from a digital elevation model sensu ArcGIS
%     ASPECT             : angle of exposition from a digital elevation model (GRIDobj)
%     CASTSHADOW         : cast shadow
%     CELLAREA           : calculate cell areas of a GRIDobj in geographic coordinate system
%     CLIP               : clip a GRIDobj with a polygon or another GRIDobj
%     CONTOUR            : contour plot of an instance of GRIDobj
%     COORD2IND          : convert x and y coordinates to linear index
%     COORD2SUB          : convert x and y coordinates to subscripts into a GRIDobj
%     CREATEMASK         : create a binary mask using polygon mapping
%     CROP               : crop an instance of GRIDobj with axis-aligned minimum bounding box
%     CURVATURE          : 8-connected neighborhood curvature of a digital elevation model 
%     DEMAREA            : Calculate the corrected surface area of a DEM
%     DEMPROFILE         : get profile along path
%     DIFFUSION          : Solve the diffusion equation
%     DILATE             : morphological dilation
%     DIST2CURVE         : labels pixels in a GRIDobj by their directed distance to a curved line
%     DIST2LINE          : labels pixels in a GRIDobj by their distance to a straight line
%     DISTANCE           : distance transform
%     ELEVATEMINIMA      : elevate regional minima in a DEM to their lowest neighbor
%     ERODE              : morphological erosion
%     EVANSSLOPE         : Calculate surface slope using Evans method
%     EXCESSTOPOGRAPHY   : reconstruct surface with threshold-slope surface
%     FILLSINKS          : fill/remove pits, sinks or topographic depressions
%     FILTER             : 2D-filtering of DEMs with different kernels 
%     FIND               : Find indices of nonzero elements in GRIDobj
%     FINDCOORD          : Find coordinates of nonzero elements in GRIDobj
%     GETCOORDINATES     : get coordinate vectors of an instance of GRIDobj
%     GETEXTENT          : return extent of a GRIDobj
%     GETOUTLINE         : get or plot extent of GRIDobj
%     GRADIENT8          : 8-connected neighborhood gradient of a digital elevation model
%     GRIDDEDCONTOUR     : plot contours on grid
%     HILLSHADE          : create hillshading from a digital elevation model (GRIDobj)
%     HISTOGRAM          : Plot frequency distribution of values in GRIDobj
%     HYPSCURVE          : plot hypsometric curve of a digital elevation model
%     IDENTIFYFLATS      : identify flat terrain in a digital elevation model
%     IMAGESC            : Scale data in GRIDobj and display as image object
%     IMAGESCHS          : plot hillshade image with overlay
%     IND2COORD          : convert linear index to x and y coordinates
%     INFO               : detailed information on GRIDobj instance
%     INPAINTNANS        : Interpolate or fill missing values in a grid (GRIDobj)
%     INPAINTNANSORDFILT : DEM inpainting using 2D order-statistics filtering
%     INTERP             : interpolate to query locations
%     INTERP2GRIDOBJ     : Interpolate scattered data to GRIDobj
%     INTERPWITHBARRIERS : Laplace interplation with barriers
%     ISNAN              : returns array elements that are NaNs as logical grid
%     KSDENSITY          : kernel density estimator for GRIDobj
%     LATLON             : returns grid lines of latitudes and longitudes
%     LINE2GRIDOBJ       : convert line to a grid
%     LOCALTOPOGRAPHY    : Local topography
%     MEASURE            : take interactive measurements along a polyline
%     MINMAXNORM         : min-max normalization with optional percent clipping
%     MPOWER             : overloaded power for GRIDobj
%     MRDIVIDE           : overloaded right division for GRIDobj
%     MTIMES             : overloaded multiplication for GRIDobj
%     PAD                : add or remove a border of pixels around a GRIDobj
%     POLYGON2GRIDOBJ    : convert polygon to a grid
%     POSTPROCFLATS      : postprocess flat terrain for visualization purpose
%     PRCCLIP            : percentile clipping
%     PROJECT            : transforms a GRIDobj between projected coordinate systems
%     PROMINENCE         : Calculate the prominence of mountain peaks
%     RAND               : Compute a GRIDobj with random numbers
%     RANDOMSAMPLE       : Uniform random sampling of a GRIDobj
%     RECLABEL           : labels GRIDobj by rectangular fields
%     RECLASSIFY         : generate univariate class intervals for an instance of GRIDobj
%     REPROJECT2UTM      : Reproject DEM with WGS84 coordinate system to UTM-WGS84 
%     RESAMPLE           : change spatial resolution of a GRIDobj
%     ROUGHNESS          : terrain ruggedness, position and roughness indices of DEMs
%     SHUFFLELABEL       : shufflelabel randomly relabels a label matrix
%     SNAP2STREAM        : snap gauges or pour points to stream raster
%     SUB2COORD          : convert subscripts to x and y coordinates
%     SURF               : surface plot for GRIDobj
%     TANAKACONTOUR      : Relief depiction using Tanaka contours
%     TOPOSHIELDING      : topographic shielding from cosmic rays
%     VALIDATEALIGNMENT  : validates whether instances of GRIDobj are spatially aligned
%     ZSCORE             : standardized z-scores for GRIDobj
% 
% FLOWobj methods
% 
%     FLOWOBJ             : create flow direction object
%     FLOWOBJ2GRIDOBJ     : create ESRI ArcGIS flow direction grid from FLOWobj
%     FLOWOBJ2M           : convert instance of FLOWobj to flow direction matrix 
%     FLOWOBJ2CELL        : return cell array of FLOWobjs for individual drainage basins
%     CROP                : crop an instance of FLOWobj
%     DBASYMMETRY         : Drainage basin asymmetry
%     DBENTROPY           : entropy of drainage basin delineation
%     DEPENDENCEMAP       : upslope area for specific locations in a DEM
%     DRAINAGEBASINS      : drainage basin delineation/catchments
%     DRAINAGEBASINSTATS  : zonal statistics on drainage basins
%     FIND                : find indices and values of edges in the flow direction graph
%     FLIPDIR             : Flip direction of flow
%     FLOWACC             : flow accumulation (upslope area, contributing area)
%     FLOWCONVERGENCE     : compute flow convergence of a digital elevation model
%     FLOWDISTANCE        : flow distance in upstream and downstream direction
%     FLOWPATHEXTRACT     : extract linear indices of a single flowpath in a DEM
%     FLOWVEC             : velocity vectors from FLOWobj
%     GRADIENT            : gradient along flow direction
%     IMPOSEMIN           : minima imposition (carving) along drainage network
%     IND2COORD           : convert linear index to x and y coordinates
%     INFLUENCEMAP        : downslope area for specific locations in a digital elevation model
%     ISGEOGRAPHIC        : Determines if FLOWobj has a geographic coordinate system
%     ISMULTI             : check if FD is multi or single flow direction
%     MAPFROMNAL          : map values from node-attribute list to nearest upstream grid
%     MELTONRUGGEDNESS    : Melton ruggedness
%     MULTI2SINGLE        : converts multiple to single flow direction
%     MULTI_NORMALIZE     : create flow direction object
%     MULTI_WEIGHTS       : create flow direction object
%     PLOTDBFRINGE        : Plot semitransparent fringe around each drainage basin
%     QUANTCARVE          : quantile carving
%     RANDOMIZE           : randomize multiple flow directions
%     SAVEOBJ             : create flow direction object
%     SLOPEAREATOOL       : Interactively create slope area plots and fit power laws
%     STREAMORDER         : calculates a stream order GRIDobj from FLOWobj
%     STREAMPOI           : stream points of interest
%     TFACTOR             : Transverse topographic symmetry (T-)factor
%     UPDATETOPOSORT      : update topological sorting
%     UPSLOPESTATS        : upslope statistics computed in flow directions
%     VALIDATEALIGNMENT   : validates whether instances of FLOWobj and GRIDobj are spatially aligned
%     VERTDISTANCE2STREAM : vertical distance to streams 
% 
% STREAMobj methods
% 
%     STREAMOBJ           : Create stream object (STREAMobj)
%     STREAMOBJ2GRIDOBJ   : convert an instance of STREAMobj to an instance of GRIDobj
%     STREAMOBJ2SWATHOBJ  : Create swath profile (SWATHobj) from stream network
%     STREAMOBJ2XY        : convert instance of STREAMobj to NaN-separated X and Y coordinates
%     STREAMOBJ2CELL      : convert instance of STREAMobj to cell array of stream objects
%     STREAMOBJ2KML       : Convert STREAMobj to kml (Google Earth)
%     STREAMOBJ2LATLON    : convert instance of STREAMobj to NaN-separated geographic coordinates
%     STREAMOBJ2MAPSTRUCT : convert instance of STREAMobj to mapstruct
%     STREAMOBJ2SHAPE     : Convert STREAMobj to geoshape or mapshape
%     AGGREGATE           : Summarizing values within segments of the stream network
%     BINARIZE            : Make a stream network a strictly binary tree
%     CHIPLOT             : CHI analysis for bedrock river analysis
%     CHITRANSFORM        : Coordinate transformation using the integral approach
%     CLEAN               : Create stream object (STREAMobj)
%     CONNCOMPS           : labels of connected components (individual trees) in a stream network
%     CRS                 : constrained regularized smoothing of the channel length profile
%     CRSAPP              : interactive smoothing of river long profiles
%     CRSLIN              : constrained regularized smoothing of the channel length profile
%     CUMMAXUPSTREAM      : cumulative maximum in upstream direction
%     CUMSUM              : cumulative sum on stream network
%     CUMTRAPZ            : Cumulative trapezoidal numerical integration along a stream network
%     CURVATURE           : curvature or 2nd derivative of a STREAMobj
%     DENSIFY             : Increase number of vertices in stream network using splines
%     DIFF                : Differences between adjacent pixels in a stream network
%     DISTANCE            : return node attribute list with distances along the stream network
%     DRAINAGEDENSITY     : drainage density of a stream network
%     EXTEND2DIVIDE       : Grow STREAMobj upstream to extend to the divide
%     EXTRACTCONNCOMPS    : interactive stream network selection
%     FASTSCAPE           : Simulation of the stream power incision model
%     GETLOCATION         : Get locations along a stream network
%     GETNAL              : get node-attribute list
%     GETVALUE            : retrieve value from node-attribute list
%     GRADIENT            : along-stream gradient
%     HILLSLOPEAREA       : upslope hillslope area for each stream pixel 
%     IDENTIFYFLATS       : identify flat sections in a river profile
%     IMPOSEMIN           : minima imposition (carving) along stream network
%     INFO                : meta information about STREAMobj
%     INPAINTNANS         : inpaint missing values (nans) in a node attribute list
%     INTERP              : interpolate data on STREAMobj (single river only)
%     INTERPSMOOTH        : Interpolate and smooth values measured along a stream network
%     INTERSECT           : intersect different instances of STREAMobj 
%     INTERSECTLOCS       : Derive locations where two STREAMobj start to have a common network
%     ISEMPTY             : Determine whether a STREAMobj is empty
%     ISEQUAL             : Determine whether two STREAMobjs are equal
%     ISGEOGRAPHIC        : Determines if STREAMobj has a geographic coordinate system
%     ISNAL               : test whether a vector is a node attribute list of a STREAMobj
%     ISSUBGRAPH          : Create stream object (STREAMobj)
%     ISTRUNK             : Determines whether STREAMobj consists of trunk streams
%     KLARGESTCONNCOMPS   : retain k largest connected components in an instance of STREAMobj
%     KNICKPOINTFINDER    : find knickpoints in river profiles
%     KSN                 : normalized steepness index
%     LABELREACH          : create node-attribute list with labelled reaches
%     LOESSKSN            : Loess-smoothed river steepness
%     MAPLATERAL          : map values of regions adjacent to streams to stream network
%     MCHI                : gradient of stream profile in chi space (M_chi)
%     MEANUPSTREAM        : mean (weighted) upstream  values
%     MINCOSTHYDROCON     : minimum cost hydrological conditioning
%     MNOPTIM             : Bayesian optimization of the mn ratio
%     MNOPTIMVAR          : optimize the mn ratio using minimum variance method
%     MODIFY              : modify instance of STREAMobj to meet user-defined criteria
%     NAL2NAL             : map one node-attribute list to another 
%     NETDIST             : distance transform on a stream network
%     NETWORKSEGMENT      : Identify river segments and compute segment geometry
%     ORIENTATION         : stream orientation
%     PLOT                : plot instance of STREAMobj
%     PLOT3               : 3d-line plot of a STREAMobj
%     PLOT3D              : 3D plot of a stream network
%     PLOTC               : plot a colored stream network
%     PLOTDZ              : plot upstream distance version elevation of a stream network
%     PLOTDZSHADED        : plot upstream distance version elevation of a stream network
%     PLOTSEGMENTGEOMETRY : Plot segment geometry obtained from the function networksegment
%     PLOTSTREAMORDER     : calculate stream order from STREAMobj
%     PSITRANSFORM        : Psi-transformation of river network elevations
%     QUANTCARVE          : quantile carving
%     RANDLOCS            : Random locations along the stream network
%     REMOVEEDGEEFFECTS   : remove potential edge effects
%     REMOVESHORTSTREAMS  : Remove first order streams with a length less than specified
%     RMEDGE              : Create stream object (STREAMobj)
%     RMNODE              : Create stream object (STREAMobj)
%     SIDEBRANCHING       : side branching classification according to Tokunaga (1978)
%     SINUOSITY           : sinuosity coefficient 
%     SLOPEAREA           : slope-area relation of a stream network
%     SMOOTH              : smoothing of node-attribute lists
%     SNAP2STREAM         : snap locations to nearest stream location
%     SPLIT               : split drainage network at predefined locations
%     STACKEDPLOTDZ       : plot several stacked variables along the stream networks
%     STREAMORDER         : calculate Strahler Stream Order from STREAMobj
%     STREAMPOI           : stream points of interest
%     STREAMPROJ          : project stream elevations based on slope-area scaling
%     SUBGRAPH            : Create stream object (STREAMobj)
%     TRANSFORMCOORDS     : transform coordinates of stream network
%     TRIBDIR             : direction of inflow of tributary
%     TRUNK               : extract trunk stream (longest stream) 
%     UNION               : merge different instances of STREAMobj into a new instance
%     VALIDATEALIGNMENT   : is an instance of STREAMobj is spatially aligned with another object of TopoToolbox
%     WIDENSTREAM         : level elevations adjacent to the stream network
%     WMPLOT              : plot stream network in the webmap browser
%     ZEROBASELEVEL       : set base level to zero
%
% DIVIDEobj methods
%
%     DIVIDEOBJ           : Create divide object (DIVIDEobj)
%     DIVIDEOBJ2MAPSTRUCT : obtain divide properties from GRIDobj
%     ASYMMETRY           : directional asymmetry of divide segments
%     CLEANEDGES          : Delete divides on the edges of DEM
%     COORD2IND           : convert x and y coordinates to linear index
%     DIST2NODE           : network distance to nodes
%     DIVDIST             : DIVDIST   Assign distance to divide segments
%     DIVNET              : Create divide object (DIVIDEobj)
%     DIVORDER            : Assign order to divide segments
%     GETVALUE            : get grid values adjacent to divides
%     IND2COORD           : convert linear index to x and y coordinates
%     JCTANGLE            : angles between divide segments at junctions
%     JCTCON              : compute junction connectivity
%     PLOT                : plot the divide network 
%     PLOTC               : Create colored plot of drainage divide network
%     REMOVESHORTDIVIDES  : Remove short first-order divides
%     SHRINK              : Shrink divide network
%     SORT                : Sort divide segments by network structure.
% 
% SWATHobj methods
% 
%     SWATHOBJ2GRIDOBJ : create a GRIDobj with swath-specific information
%     SWATHOBJ2GDS     : create a geographic data structure from a SWATHobj
%     CONVERT2LATLON   : convert spatial fields in SWATHobj to lat,lon
%     MAPSWATH         : obtain Z values along a SWATHobj from an arbitrary GRIDobj
%     PLOT             : plot instance of SWATHobj
%     PLOTDZ           : create distance-elevation plot of SWATHobj
%     PLOTDZM          : create color-coded distance-elevation plot from SWATHobj and GRIDobj
%     PROFILES         : obtain profiles from a SWATHobj
%     TIDY             : remove overlapping points from SWATHobj
%
% PPS methods
%
%     PPS              : Point patterns on stream networks
%     AGGREGATE        : Aggregate points in PPS to new point pattern
%     AS               : Convert PPS object into various data formats 
%     CLUSTER          : hierarchical clustering of points in PPS
%     CONVHULL         : convex hull around points in PPS
%     DENSITY          : nonparametric density estimation on network
%     ECDF             : Empirical cumulative distribution function of a covariate 
%     EXTENDEDNETWORK  : extend network to account for duplicate points
%     FITLOGLINEAR     : fit loglinear model to point pattern
%     GETMARKS         : extract point marks
%     GFUN             : G-function (nearest inter-point distance distribution)
%     HASDUPLICATES    : checks whether there are duplicate points
%     HISTOGRAM        : histogram of point pattern on stream network
%     INTENSITY        : calculate intensity (density) of points on the stream network
%     NETDIST          : Shortest network distance
%     NPOINTS          : number of points in the point pattern
%     PLOT             : plot instance of PPS
%     PLOTC            : plot a colored stream network
%     PLOTDZ           : plot upstream distance version elevation or covariate of a PPS
%     PLOTEFFECTS      : Plot of slices through fitted generalized linear regression
%     PLOTPOINTS       : plot points of PPS
%     POINTDISTANCES   : inter-point distance
%     POINTS           : extract a list of points from the point pattern
%     QUADRATCOUNT     : Quadrat count and chi2 test
%     RANDOM           : random realisation of a (inhomogeneous) point process
%     REGULARPOINTS    : Generate non-random points on stream network
%     REMOVEDUPLICATES : removes duplicate points
%     REMOVEPOINTS     : Remove points in point pattern
%     RHOHAT           : nonparametric estimation of point pattern dependence on covariate
%     ROC              : receiver-operating characteristics of point pattern
%     SHAPEWRITE       : write point pattern to shapefile
%     SIMULATE         : simulate point pattern using random thinning
%     TLENGTH          : total length of the stream network
%     VORONOI          : nearest neighbor search on a stream network
%     WMPLOT           : plot instance of PPS in webmap browser
%
% TTLEM (TopoToolbox Landscape Evolution Model)
%
%     TTLEM            : TopoToolbox Landscape Evolution Model: TTLEM
%     TTLEMSET         : set options and parameters for TTLEM
%
% Other tools (utitilies)
%
%     compilemexfiles - compile mex-functions that come with TopoToolbox 2
%     coord2ind       - convert xy coordinates to linear index
%     exaggerate      - elevation exaggeration in a 3D surface plot
%     getdistance     - cumulative distance along path defined by vertice coordinates
%     getextent       - get current axis extent
%     interpline      - distribute vertices evenly along line with irregularly spaced vertices
%     ixneighbors     - neighbor indexing in a matrix
%     label2poly      - plot region outlines with polyline
%     landcolor       - colormap for the display of DEMs
%     setextent       - set current axis extent    
%     showmethods     - displays class method names and H1 lines in the command line
%     egm96heights    - read and resample EGM96 geoid heights
%     dpsimplify      - Douglas-Peucker line simplification
%     zonalstats      - Zonal statistics
%
% Documentation
%
%   usersguide_1_intro      - introductory script to the toolbox
%   usersguide_2_mfd        - how to calculate Multiple Flow Direction in
%                             TopoToolbox 2
%   usersguide_3_ksn        - calculate ksn values with TopoToolbox 2
%
%
%   ---------------------------------------------------------------------
%     TopoToolbox is free software: you can redistribute it and/or modify
%     it under the terms of the GNU General Public License as published by
%     the Free Software Foundation, either version 3 of the License, or
%     (at your option) any later version.
% 
%     This program is distributed in the hope that it will be useful,
%     but WITHOUT ANY WARRANTY; without even the implied warranty of
%     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%     GNU General Public License for more details.
% 
%     You should have received a copy of the GNU General Public License
%     along with this program.  If not, see <http:https://www.gnu.org/licenses/>.