in3Utils: Various Utilities Modules

geoTrans

The in3Utils.geoTrans module provides useful functions to operate transformations, comparison or interpolation on rasters, lines, points… Further information about the available functions can be found in in3Utils.geoTrans

Generate Topography

The in3Utils.generateTopo module provides functions to generate DEM files for idealized/generic topographies that can be used for snow avalanche simulations.

This module can generate the following topographies:

flat plane (FP)
inclined plane of constant slope (IP)
parabola - parabolic slope transitioning into a flat foreland (PF)
hockey stick - inclined plane of constant slope with a smooth transition to a flat foreland (HS)
bowl-shaped topography (BL)
helix-shaped topography (HX)
pyramid-shaped topography (PY)

Extra features can be added to the above topographies:

a channel can be introduced (then set channel=True).
This channel can also be set to widen towards the top and bottom of the channel (then set narrowing=True). The channel can be added by either adding a ‘channel layer’ (max thickness=channel depth) on top of the topography (topoAdd=True) or by cutting them into the original topography (topoAdd=False).

in case of the parabola topography, a dam can be added by setting ``dam=True``.

This modules returns a 3D plot of the generated topography as well as an .asc file of the DEM data. The input parameters are defined in the respective configuration file in3Utils.generateTopoCfg.ini. Detailed information on the individual functions used to create the topographies can be found in in3Utils.generateTopo

To run generateTopo

first go to AvaFrame/avaframe
copy in3Utils/generateTopoCfg.ini to in3Utils/local_generateTopoCfg.ini and set the desired parameter values (if not, the default values are used)
run:
```
python3 runScripts/runGenerateTopo.py
```

Theory

Topographies are generated using inclined and flat planes, parabolas, spheres and circles. Channels are introduced as half-sphere shaped features with smooth transition from the no-channel area to the channel using cumulative distribution functions.

Configuration parameters

In the case of the pyramid-shaped topography, the domain extent is defined by the max elevation (z0 - elevation of the appex point) and the slope of the pyramid facets (meanAlpha)

Domain parameters:

dx: DEM spatial resolution [m]
xEnd: total horizontal extent of the domain [m]
yEnd: total vertical extent of the domain [m]

Topography parameters:

flens: distance to the point where the slope transitions into a flat plane [m]
meanAlpha: slope angle from the max. elevation to the start of the flat plane [°] - or slope of the inclined plane [°]
C: total fall height [m]
rBowl: bowl radius [m]
rHelix: radius for helix [m]
z0: max elevation [m]
zElev: elevation of the flat plane [m]
rCirc: radius of the smoothing circle [m]
demType: topography types (FP, IP, PF, HS, BL, HX, PY - explanation given in the introductory description)
flatx: extent of the flat foreland for the pyramid in x
flaty: extent of the flat foreland for the pyramid in y
phi: rotation angle for the pyramid

Flags for channels and plotting:

channel: True - introduce channel; False - no channel
narrowing: True - channel is wide at start and end and narrow in the middle part; False - channel is uniform
topoAdd: True - add channel layer; False: cut channel into original topography;
flagRot: True - rotate pyramid along z-axis

Channel parameters:

cRadius: standard channel radius
cInit: start and end half width of channel that is narrower in the middle part
cff: standard deviation sigma
cMustart: mean mu - represents upper part of the channel
cMuend: mean mu - represents lower part of the channel

Get Release Area

in3Utils.getReleaseArea generates a release area for a topography created with in3Utils.generateTopo, this function is available for the following topographies:

flat plane (FP)
inclined plane (IP)
parabola (PF)
hockey stick (HS)

The release areas are defined as rectangular features build by four corner points, which are based on the following conditions:

prescribed vertical stretch in meters (difference in altitude)
prescribed volume of the release area
lower margin is located where the slope angle falls below 30°
if slope does not fall below 30 °, the upper margin is located xStart away from the upper margin of the DEM

The release areas can be saved as shapefile, .nxyz and .txt file. The required input parameters can be set in the respective configuration files in3Utils/getReleaseAreaCfg.ini and in3Utils.generateTopoCfg.ini. Detailed information on the individual functions used to create the release areas can be found in in3Utils.getReleaseArea

To run getReleaseArea

Following these steps, you can generate an avalanche test case including a DEM and a simple release area.

first go to AvaFrame/avaframe
copy in3Utils/generateTopoCfg.ini and in3Utils/getReleaseAreaCfg.ini to in3Utils/local_generateTopoCfg.ini and in3Utils/local_getReleaseAreaCfg.ini and set desired parameter values (if not, the default values are used)
run:
```
python3 runGenProjTopoRelease.py
```

Parameters:

hr: release area vertical stretch [m]
vol: volume of snow in release area [m3]
dh: release snow thickness [m]
xStart: upper margin of the release area distance in x from origin [m]
lenP: number of release area polygon points
outputtxt: True - copy the output to txt file
xExtent: horizontal extent of release area for flat plane
alphaStop: slope angle that defines lower margin of release area
relNo: number of release area for name
relName: name of release area feature in shapefile

Initialize Project

in3Utils.initializeProject provides functions to initialize a project, create the required directory structure and delete specified files or directories.

The main function in3Utils.initializeProject.initializeFolderStruct(), creates the folder structure required to perform avalanche simulations:

NameOfAvalanche/
        Inputs/
                ENT/            - entrainment areas
                LINES/          - avalanche paths
                POINTS/         - split points
                REL/            - release area scenario
                RES/            - resistance areas
                SECREL/ - secondary release areas
                .asc            - DEM
        Outputs/
        Work/

The path to this folder is specified in the configuration file avaframeCfg.ini, with the parameter avalancheDir.

To run

first go to AvaFrame/avaframe
copy avaframeCfg.ini to local_avaframeCfg.ini and set your desired avalanche directory name
run:
```
python3 runInitializeProject.py
```

fileHandlerUtils

in3Utils.fileHandlerUtils gathers useful functions to create directories, read log files, extract information from logs, fetch and export data and fetch simulation info into a dataFrame. Details on these functions can be found in in3Utils.fileHandlerUtils.