Table of Contents
- See also
- python.workflows.hydThalweg
Aim of script
Computes the thalweg of a river using datasets derived from Airborne Laser Bathymetry (ALB) and the river axis.
General description
This script creates an ESRI-shapefile containing the thalweg of a river. The thalweg of a river is defined as the line of the deepest points of the riverbed in flow-direction.
The implementation of this script is based on datasets derived from Airborne Laser Bathymetry (ALB) using topo-bathymetric scanners. As ALB can penetrate water, a topo-bathymetric scanner creates a 3D point cloud which contains reflected points from the terrain around the river as well as from the riverbed. However, only riverbed-points are essential for the thalweg computation.
Therefore, Python script hydThalweg offers the possibility to narrow down the number of ALB-points which are used for the thalweg derivation. If requested by the user, the script classifies the ALB-data into ground- and non-ground-points, out of which only ground-points are chosen for the thalweg derivation. Moreover, it is possible to provide a file with water surface heights and their position along the river to restrict possible thalweg points to the water surface and the main river channel. By using these two mechanisms, the thalweg computation is optimized. Not using them, without implementing a classification/point-restriction beforehand instead, can even lead to an erroneous thalweg.
Apart from that, the method for the thalweg computation itself is based on the extraction of cross-sections along the river, the calculation of one thalweg point per section and the connection of these points to form the thalweg shapefile.
Basic algorithm
The algorithm consists of the following steps:
- Import of the ALB-data using Module Import, restriction of the dataset to an area around the river axis using an automatically created buffer-shapefile.
- If indicated by classifyGroundPoints: Classification of point cloud into ground- and non-ground-points using Module TerrainFilter.
- Extraction of cross-sections based on the (classified) point cloud with Module Section.
- Creation of a spline in each section, following the (ground)-points.
- If parameter waterSurface is set: restriction of each spline to the water surface height and the main river channel.
- Computation of the spline point with minimum elevation in each section. These are the thalweg points if smoothing is set to zero.
- If indicated by smoothing: Median of 3/5/7 consecutive deepest spline points forms the thalweg point of each section.
- Execution of a similarity transformation to transfer the local section-coordinates of the thalweg points to a global coordinate system.
- Creation of an ESRI-shapefile containing a linestring with the global thalweg points. This is the final thalweg.
Usage of script
There are two mandatory input files. First, infile accepts single files or a list of files with 3D point cloud(s) or grid data. Second, an ESRI-shapefile containing the river axis of the surveyed river section is expected for axisfile. This river axis should approximately follow the main course of the river.
The output folder for storage of the final thalweg shapefile is specified by outfile (default: current working directory/hydThalweg). Apart from that, there are two main intermediate outputs, namely the plots of the conducted cross-sections and a shapefile with the section-outlines. They are stored in the tempdir directory (default: current working directory/tempHydThalweg). The buffer shapefile and the thereby restricted ALB-data can be found in tempdir as well.
Next, if there is no (usable) already existing classification, it is recommended to set classifiyGroundPoints to 1 or 2, else the thalweg computation might be erroneous.
Additionally, providing a waterSurface file is highly recommended. If the required stationings and water surface heights are not known beforehand, the following processing strategy is possible: First, run Python script hydThalweg without waterSurface. Second, look up stationings and corresponding water surface heights for waterSurface in the stored cross-section plots.
Apart from that, a default configuration-file (cfg) is provided by the OPALS distribution. It contains default parameters for OPALS modules which are used in the script. If there is no cfg-file set by the user, the default cfg-file is used. However, it is advised to create an own cfg-file to adapt the module-parameters to individual datasets. To give an example, filters for the classification or the cross-sections can be specified in the cfg-file.
Parameter description
Remark : mandatory
Description: As input file either the relative or the absolute path(s) to LAS/LAZ/TIF/ODM file(s) are accepted. The file(s) should contain the course of a river.
Remark : optional
Description: Relative or absolute path to the output directory of the thalweg shapefile, which will be created.If not specified: path = current working directory/hydThalweg
Remark : mandatory
Description: Relative or absolute path to a shapefile. This shapefile contains the river-axis of the river section covered by the input file(s).
Remark : optional
Description: Relative or absolute path to a txt-file. This file contains only pairs of numbers.Each row in the txt-file lists one pair. There is a blank between the two numbers of the pair. The pair consists, first, of a stationing (int) and second, of a water surface height (float). The stationing is the distance along the river axis (m) in axis direction. The water surface height is the river water surface height (m) corresponding to the stationing. The file has to contain at least two pairs, as the water surface height along the whole river axis is linearly interpolated on the basis of this txt-file.
Remark : optional, default: 0
Description: 0...no classification, 1...classification into ground- and non-ground-points, 2...reset of every already existing classification, then classification into ground- and non-ground-points
Remark : optional, default: 2
Description: Number of thalweg-points out of which the median is computed. 0...no smoothing, no median computation, 1/2/3...median of the current thalweg point and the 1/2/3 preceding and subsequent thalweg points along the river axis forms a final thalweg point.This works like a moving average. Thus, there is no reduction of total thalwegpoints.
Remark : optional, default: tempHydThalweg
Description: Specifies the directory where all intermediate results are stored. If not specified, a TEMP subdirectory is created in the current working directory. Additional subdirectories (one per involved module) are created.
Remark : optional, default: $OPALS_ROOT/cfg/hydThalweg.cfg
Description: The name of a configuration file containing all relevant calculation parameters is expected. If not specified, the default cfg files as provided by the OPALS distribution are used.
Remark : optional, default: current directory
Description: The default project directory is the current working directory, but can be easily changed by this parameter. All path parameters, if not specified as absolute paths, are interpreted relative to the project directory.
Remark : optional, default: True
Description: Skip processing if result already exists. In order to re-run current script it is useful to repeat the processing only if the respective output does not already exist. This allows for incremental processing of large projects.
| possible input | evaluates to |
|---|---|
| 1, true, yes, Boolean(True), True | Boolean(True) |
| 0, false, no, Boolean(False), False | Boolean(False) |
Remark : optional
Description: according to the number chosen as the value, independent processes are being started to parallelise (parts of) the program and therefore enhance the runtime.
Remark : optional, default: info
Remark : optional, default: info
Remark : optional
Description: Logger is usually provided by the opals framework.The user may provide their own logger object, but it has to function in the same way as the opals Logger.
Examples
The data used in the following example can be found in the $OPALS_ROOT/demo/ directory.
Example 1
This example shows the implementation of the hydThalweg script on the point cloud strip149.las. During its execution a classification in ground- and non-ground-points (see classifiyGroudPoints) and a restriction of the spline to the water surface (see waterSurface) is carried out. Moreover, a cfg-file which is adapted to the point cloud strip149.las is used.
Below, the content of strip149_wsurf.txt corresponding to the parameter waterSurface is printed. As strip149.las covers a rather short river section, strip149_wsurf.txt contains only few rows with stationings which are very close to each other. The overall necessary length of the txt-file for waterSurface depends on the length of the surveyed river section and the variability of its water surface height. The file contains two columns: stationings (left column) and water surface heights (right column).
Figure 2 shows a cross-section plot at a stationing of 49.0 m extracted from strip149.las. The classification, the spline restriction and the thalweg point are well recognisable.
In figure 3 the thalweg of the river section in strip149.las is displayed. This is the final result of Python script hydThalweg. Additionally, the section outline of the cross-section at a stationing of 49 m (see figure 2) is visible.
Example 2
Example 2 also uses the ALB point cloud strip149.las from example 1. However, neither a classification nor a spline restriction is performed. The cfg-file remains the same as in example 1.
The effects of not using the parameters classifyGroundPoints and waterSurface can be seen in figure 4. Similar to figure 2, it shows the cross-section plot at a 49.0 m stationing. As the section points were not classified, all points were used to calculate the spline. In addition, the spline was not cut at its first intersection with the water surface, so it also extends across the river bank.
Figure 5 depicts the thalweg of the river section in strip149.las derived without classifyGroundPoints and waterSurface. There are noticeable differences to the thalweg in figure 3 in the lower half of the image.
Comparison of examples
The above conducted examples demonstrated how to apply Python script hydThalweg. They also showed the influence of different parameters on the thalweg calculation. From the variation of the parameters it becomes visible that the spline in the cross-sections of example 2 is generally not representative for the riverbed (see Fgure 4). This is due to skipping the parameters classifyGroundPoints and waterSurface without providing another classification or point restriction beforehand. Theerefore, the thalweg in example 1 is overall more accurate than the thalweg in example 2, which might even contain false thalweg points. Hence, the use of the parameters classifyGroundPoints and waterSurface is again recommended. The differences of the two thalweg lines can be seen in Figure 6.
Author C. Damm, GM
Date 29.06.2023
References
Damm, C. (2023). Automatische Ableitung des Thalwegs aus Laserbathymetriepunktwolken für einen naturnahen Abschnitt der Pielach [Automatic derivation of the thalweg from laser bathymetry point clouds for a near-natural section of the Pielach river] [Unpublished bachelor's thesis]. Vienna University of Technology.
1.8.17