Add drainagebasins

[ktlenz]

Implementation should wait for the GRIDobj
drainagebasins.R distinguishes two cases

Case 1: No outlets provided

libtopotoolbox's drainagebasins function employed which requires the following arguments:

• [output] basins (ptrdiff_t, size: dims[0] x dims[1])
• [input] source (ptrdiff_t, size: edge_count)
• [input] target (ptrdiff_t, size: edge_count)
• [input] edge_count (ptrdiff_t, size: 1)
• [input] dims (ptrdiff_t, size: 2)

Comments

• source and target arrays are outputs of flow_routing_d8_edgelist and a property of the FLOWobj (FLOWobj$source, FLOWobj$target)
• edge_count can be computed in drainagebasins.R from the length of the other arguments

Case 2: Outlets provided

libtopotoolbox's travers_up_u32_or_and function employed which requires the following arguments:

• [output] output (uint32_t, size: edge_count)
• [input] weights (uint32_t, size: edge_count)
• [input] source (ptrdiff_t, size: edge_count)
• [input] target (ptrdiff_t, size: edge_count)
• [input] edge_count (ptrdiff_t, size: 1)

Comments

• outlet indices need to be unravelled (unravel_index.FLOWobj)
• mimic the following python lines in R:
  basins[indices] = np.arange(1, len(outlets) + 1, dtype=np.uint32)
  weights = np.full(self.source.size, 0xffffffff, dtype=np.uint32)
• source and target arrays are outputs of flow_routing_d8_edgelist and a property of the FLOWobj (FLOWobj$source, FLOWobj$target)

Further information

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

[wkearn]

See TopoToolbox/libtopotoolbox#212 and TopoToolbox/pytopotoolbox#369: I want to remove drainagebasins from libtopotoolbox and always use traverse_up_u32_or_and or something equivalent. This requires finding the outlets first, which can be done using libtopotoolbox's edgelist_degree as seen here.