Add `excesstopography`

[ktlenz]

Implementation should wait for the GRIDobj

excesstopography has two modes:
"The fast sweeping method is simpler than the fast marching method, requires less memory, and can be faster, particularly when the threshold slopes are constant or change infrequently across the domain."

Comments

• The threshold input for excesstopography.R can be a scalar, a matrix, an array or a GRIDobj. A scalar input needs to be assigned to a matrix for each cell of the DEM.

Mode 1: Fast sweeping
Requires a wrapper to libtt's excesstopography_fsm2d.c function with the following arguments

• [output] excess (float, dims[0] x dims[1])
• [input] dem (float, dims[0] x dims[1])
• [input] threshold_slopes (float, dims[0] x dims[1])
• [input] cellsize (float, 1)
• [input] dims (ptrdiff_t, 2)

Mode 2: Fast marching
Requires a wrapper to libtt's excesstopography_fmm2d.c function with the following arguments

• [output] excess (float, dims[0] x dims[1])
• [input] heap (ptrdiff_t, dims[0] x dims[1])
• [input] back (ptrdiff_t, dims[0] x dims[1])
• [input] dem (float, dims[0] x dims[1])
• [input] threshold_slopes (float, dims[0] x dims[1])
• [input] cellsize (float, 1)
• [input] dims (ptrdiff_t, 2)

Comments

• heap and back can be allocated in the wrapper (e.g. wrap_excesstopography_fmm2d.c) and do not need to be exported.

Further information

• libtt's API documentation: https://topotoolbox.github.io/libtopotoolbox/api.html
• pytts implementation: https://github.com/TopoToolbox/pytopotoolbox/blob/main/src/topotoolbox/grid_object.py