CM.generatePolygon: Generate polygon from bank points
In AntoniusGolly/cmgo: Derive principle Channel metrics from bank points

Description Usage Arguments Details Value Author(s) Examples

Generates an object of type polygon from the bank points. The bank points must be ordered and must have an attribute "left" or "right".

1	CM.generatePolygon(cmgo.obj)

cmgo.obj

the global object of type list containing data and parameters created with CM.ini()

CM.generatePolygon() creates a polygon from the bank points which were previously loaded with CM.ini(). The polygon generation is mainly a type conversion but involves also the chaining of the points in the correct order. That is, taking all bank points from the left bank and chain them with all reversed points of the right bank. The bank points from the right side have to be reversed so that a valid, circular polygon results (see figure). Since this process is prone to error when the points are not provided in the expected order, there is a visual feedback of this process. An overview of the generated polygon will be plotted to check the polygon's consistency. This plot is by default enabled but can be suppressed by setting par$plot.polygoncheck to FALSE.

Figure: check polygon Figure 5: The plot shows the polygon check plot for two data sets (two rows). The columns are: overview of the full channel (left), start of the polygon (middle) and end of the polygon (right). For the first data set everything looks fine. The polygon is circular and the ends look consistent (note, the starting end (middle) is open). The second data set is corrupt. You can see a line crossing the entire channel (left). Also, at the start and end of the channel there are discrepancies. This means that the order of bank points was not given properly. In this case, run CM.ini() again after re-arranging the channel bank points.

CM.generatePolygon() also applies a linear interpolation to the bank points if desired. The spacing of the bank points directly affects the resolution of the centerline (see paragraph "Work flow" of package documentation). Generally, a high resolution of the centerline represents the channel course better but leads to more data points and higher computational costs. The linear interpolation will insert equidistant points in between existing bank points where the added points have a maximum distance defined by the parameter bank.interpolate.max.dist. This value is by default 6 and needs to be adjusted to the individual geometry. As a rule of thumb it is advised to change bank.interpolate.max.dist to the value of the expected channel width! Note, that the units of this value is always the same unit as your input coordinates. The best resolution of the centerline, however, depends also on the shape of the channel. If you experience problems with the chosen interpolation distance read the paragraph "Technical fails and how to prevent them" of the package documentation).

CM.generatePolygon() requires the global data object as argument and – within this – a list of bank points. The list of bank points must be previously created with CM.ini(). See the example section for the structure of the expected input. If multiple data sets (time series) are available, the polygon generation will be performed on each data set.

returns the global data object extended by the polygon data $polygon for the respective data set(s)

Antonius Golly

# get demo data (find instructions on how to use own data in the documentation of CM.ini())
cmgo.obj = CM.ini("demo")

# check structure of the required input for CM.generatePolygon()
set = "set1"
print(str(cmgo.obj$data[[set]]$channel))

#List of 4
# $ x   : num [1:396] 401601 401587 401568 401558 401552 ...
# $ y   : num [1:396] 3106437 3106407 3106384 3106364 3106329 ...
# $ z   : NULL
# $ bank: chr [1:396] "right" "right" "right" "right" ...

# generate the polygon from the bank points
cmgo.obj = CM.generatePolygon(cmgo.obj)