[ana5] Add extBottomOption to extend the DFA path to the deposit front

[NUForever]

What this adds

A new option extBottomOption in DFAPathGeneration controlling how the
mass-averaged path is extended at the bottom:

• extBottomOption = 0 (default, unchanged): the current fixed-length
  extrapolation (extendProfileBottom), which extends the path in the
  direction of its last points by factBottomExt * sMax, clipped at the
  DEM border.
• extBottomOption = 1 (new): extend the path to the front of the
  simulated deposit.

Motivation

The mass-averaged path ends short of the deposit once the front
decelerates. The default bottom extension extrapolates a straight line of
fixed relative length, independently of where the avalanche actually
stopped, so the path end does not coincide with the simulated runout.
Targeting the deposit front yields a path that ends at the simulated
runout, which is useful for corridor-scale and road-crossing analyses.

How it works

1. The front of the deposit is located in the peak flow thickness field
   (pft) as the flow-thickness-weighted centroid of the flow cells in the
   lowest part of the flow elevation range (findFlowFront), with a
   lowest-cell fallback for flat deposits and a snap to the deposit when the
   centroid falls between disjoint lobes.
2. The path end is connected to that front by a Dijkstra least-cost path
   over the DEM (leastCostPath). The cost of a step is its horizontal
   length plus a penalty on the positive elevation gain and on the distance
   from the flow footprint, so the extension descends along the deposit.
   Distances use meters (distance_transform_edt with sampling=cellsize)
   so the penalties are resolution independent.
3. If the front cannot be located or reached, or no flow thickness field is
   available, the path falls back to the fixed-length extension, so the
   AIMEC buffer is preserved.

The option is dispatched in extendDFAPath (which gains an optional
fieldFT argument, mirroring the existing extTopOption); the pft field
is read in generatePathAndSplitpoint only when the option is active. New
parameters live in DFAPathGenerationCfg.ini (ftThreshold,
lowFrontFraction, upSlopePenalty, flowDistPenalty) and resType
gains pft.

Default behaviour

Unchanged. With extBottomOption = 0 (the default) the existing pipeline
is not affected.

Tests

Unit tests added for findFlowFront (front band, flat deposit, two-lobe
snap, no flow), leastCostPath (channel routing, unreachable goal behind
nodata), extendProfileToFront (extension to the front, both fallbacks)
and readPeakFT (lookup by name and by hash, missing field). Docs updated
in docs/moduleAna5Utils.rst.

Context

Developed for the corridor-scale thalweg extraction on Route 115-CH (Chile)
and validated there against 208 manually delineated reference thalwegs
(median endpoint distance 64 m).

[fso42]

Thank you Ivan for your PR. I have 2 comments, one is only minor.

[awirb]

Does the new extension need peak flow thickness or is also just flow thickness of the final time step sufficient? the fieldFT variable is initialized with the peak flow thickness and pft has also been added as a required simulation result but later on when used in docstring also referred to as flow thickness field? I guess the peak flow thickness field is needed as otherwise the computation of the lowBand (lowest part of the flow elevation range) is changed

[NUForever]

Thanks for the review, Anna. To your question: it is the peak flow thickness (pft). The flow thickness of the final time step could be used to locate the front as well, but I went with pft because it is a default com1DFA output that is always computed, independent of whether the path is built from the particles or from the fields, while the final time step thickness would depend on that choice. The pft also covers the full extent the flow reached, which is what we need to place the front. I also renamed nrows/ncols to nRows/nCols in leastCostPath for camelCase consistency, as you suggested. All points are addressed in 331c543, with replies in the inline threads.

[fso42]

Standardtests ok (apart from known com5)