Category:CliffMetrics

CliffMetrics

CliffMetrics is an advanced software tool crafted to precisely determine the positions of cliff tops and toes along highly irregular coastlines using nothing but a Digital Elevation Model (DEM). Its innovative functionality includes an automated coastline delineation feature, which can be fine-tuned with various smoothing options to generate a streamlined coastline points layer. This layer serves as the foundation for customizable transects of variable lengths, while leveraging coastline orientation to accurately portray the coastline's normal direction. For users seeking to constrain specific locations, the tool seamlessly integrates input coastline points layers. In CliffMetrics, the concepts of cliff top and toe are rigorously defined in purely geometric terms, denoting a sharp transition in elevation along the coastaline. This definition is established through an initial detrended elevation process, followed by the specification of an input threshold, as illustrated in Fig. 1. In addition, the tool operates under the assumption that the cliff represents the predominant feature along the elevation transect. At present, CliffMetrics can be used within a GIS environment (via SAGA GIS software) or programmatically via the Linux version.

Fig. 1. CliffMetrics extracts the profile elevations and detects the locations at the cliff top and toe (left) from Detrended elevation (right)

Getting Started

SAGA WINDOWS INTEGRATION

CliffMetrics has been seamlessly integrated into the System for Automated Geoscientific Analyses (SAGA), a robust and open-source Geographic Information System (GIS) software. As of August 2019, it became an official component of the SAGA Repository, featuring firstly in version v7.3.0. CliffMetrics can be accessed in two ways:

• in Geoprocessing menu, go to “Terrain Analysis” >> “Coastal Morphology” >> “CliffMetrics”,
• in the Tools pane as it is shown in Fig. 2, “Tools”>> “Terrain Analysis” >> “CliffMetrics”.

Fig.2. Integration of CliffMetrics into SAGA software

INPUTS

The SAGA-CliffMetrics-input window is divided into the “Data Objects” and the “Options” inputs sections. Data-Objects-values are indicated by the symbol “>>” before the name and by <not set> or <create> in value box. Fig. 3 shows the default Options-values, and all inputs are explained below.

Fig. 3. The CliffMetrics input data window

The “Data Objects” section is composed by the “Elevation” (bellow “Grids”>> “Grids System”) in “Grid System” subsection and the “User Defined Coastline Points” in “Shapes” subsection. Optional parameters need to be defined in “Options” section. In more detail:

- Grid System:

• Elevation: Define the Grid System used in SAGA, and it is the primary elevation source. All types of DEM files supported in SAGA can be used. IMPORTANT! For the automatic coastline delineation option (no User Defined Coastline Points as input), the user-defined DEM must NOT have non-data values around the edges. CliffMetrics starts searching for the coastline by traversing the edges of the DEM.

- Shapes:

• User Defined coastline points: This layer sets the starting points of transect positions on the coastline if you include it. All vector file types supported in SAGA can be used. CliffMetrics only read the coordinates of the point and the ordinal (sequential order of saving to the file). Ordinals identify the Start (n=1) and End (n=last) points of User Defined Coastline Points, so the points must have been stored along the coastline. If the starting point is outside of the DEM domain, the first user-defined shoreline point within the DEM boundaries is automatically selected as the starting point. The User Defined Coastline Points are used as an initial reference to find the centre of the raster DEM cell closest to them. This center will be the starting point for the transects. In addition, it is necessary to define three aspects in advance:

1. Sea handiness: This parameter establishes which DEM side of the coastline is the sea if a person is imagined walking from the starting point to the end of the user defined coastline, see Fig.4.
2. Start edge coastline: Defines which DEM edge (North, East, South, West) the user defined coastline starts at, see Fig. 4.
3. End edge coastline: This parameter identifies which DEM edge (North, East, South, West) the user defined coastline ends at, see Fig. 4.

- Options:

• Still Water Level: the user-defined vertical elevation for the automatically delineated coastline. Default is 1 m above the datum used for the DEM. This will likely be different for your DEM.
• Coastline Smoothing Algorithm: Smoothing algorithm to apply. There are three options: “None”, “running mean” or “Savitsky-Golay”, see Fig. 4. The default is “running mean” (https://en.wikipedia.org/wiki/Moving_average).
• Coastline Smoothing Window Size: The number of selected points to smooth the coastline. Smoothing the coastline produces normals that are more parallel to each other, see Fig. 4. The default value is “30” points.

Fig.4. Examples of three options of the shoreline smoothing algorithm with the size of the 30-point shoreline smoothing window and the effect on transects. The User Defined Coastline Points parameters in this example are Sea handiness= “Left”, Start edge coastline = “North” and End edge coastline = “South”

• Scale Raster Output Values: If necessary, GIS raster output values are scaled to the Coordinate Reference System used, in this case select “Active”.
• Random Edge for Coastline Search: Select “Active” if the first edge used to search for the coastline is randomly selected each time the tool is run.
• Length of Coastline Normal: The default length is 500 m. The minimum recommended length is three times the planimetric resolutions. For example, if the raster cell size is 10 meters, the minimum length of normal is 30 meters.
• Vertical Tolerance: Minimum abrupt change in elevation on the coast to detect a toe or top cliff. The default value is 0.5 m.
• Main Output File Directory: Output folder for saving the results.

OUTPUTS

The outputs use the symbol "<<" before the name and the value <create> in the CliffMetrics “Data Objects” box, see Fig. 3. After clicking "Okay", some of the outputs are uploaded by default to the SAGA workspace as virtual layers (see the "Data" label window in “Manager” pane), and others are saved directly in the user-defined output folder. Virtual layers are particularly useful in case you want to fine-tune user-defined parameters. To facilitate the screening of model results, CliffMetrics produces a set of shapefiles and ASCII files in a format readable by most GIS and spreadsheet software. More in detail:

• coast.shp: A line shapefile contains a smoothed coastline resulting from applying the user defined smoothing. The “coast” field is the identifier for each continuous line in the study.
• coast_point.shp: A point shapefile with the location of raster DEM cells closest to user defined “Still Water Level”. These points are used as the start of the transect and the coastline orientation is used to draw the coastline normal. The “ncoast” field is linked to “coast” field as the identifier value in “coast.shp”, the “nProf” field is linked to the field with the same name in the “normal.shp” layer, the “bisOK” field is a Boolean variable to indicate whether the point is within the DEM spatial scope (1) or outside (0), the “CoastEl” field is the value of the DEM elevation point and the “Chainage” field is the horizontal distance from the start of the transect.
• normals.shp: A line shapefile that including the transects. The number of normal/transects will vary with the resolution of the DEM and the number of defined or calculated coast points. Transects should not be crossed, the longer they are, the more the number of transects will be reduced to avoid this. The “Normal” field is the unique identifier and is linked to the “nProf” field value in “coast_point.shp”, the “StartCoast” field is true (1) if the profile is at the start point of the coastline and false (0) otherwise, the “EndCoast” field is true (1) if the profile is at the end point of the coastline and false (0) otherwise, “HitLand” is 1 if the transect hit the dry land (e.g. land at higher elevation than the Still Water Level), “HitCoast” is true (1) if the transect cross the coastline in more than the start point and false (0) otherwise, “HitNormal” is 1 is the transect cross with another transect and “nCoast” is linked to “coast” field in “coast.shp”.
• cliff_toe.shp: a point shapefile with the planimetric position of the cliff toes. The “nCoast” field is linked to “nCoast” in “coast_point.shp” and the “coast” field in “coast.shp”. “nProf” field is the same in “normal.shp” and in “coast_point.shp”. The “bisOk” field is a Boolean variable to indicate whether the point is within the DEM spatial scope (1) or outside (0), “nPoint” is the number of points along this transect, “CliffToeEl” is the DEM elevation at the toe of the cliff.
• cliff_top.shp: a point shapefile with the planimetric position of the cliff tops. The fields are the same as for Cliff_toe.shp but refer to the cliff top location.
• coast_0_profile_XX.csv: The group of transect/normal/elevation profiles are saved as CSV files. The filename includes the coastline identifier after “coast” and ends with a number equal to “nProf” after “profile” with the value linked to “nProf” field in “coast_point.shp” or the “normal” field in “normal.shp”. For example, the file “coast_2_profile_523.csv” is the profile num. 523 in coastline num. 2. These CSV files contain 5 fields: a “Dist” field such as the horizontal distance from their point in “coast_point.shp”, the positive landward, the “X”, “Y,” and “Z” coordinates in the DEM reference and the elevation value “detrendZ” after removing the linear trend, see Fig. 1. In addition, the first line is also including a string at the end of the line with the profile number and coastline identifier, e. g. “For profile 4 from coastline 0”.
• Data.mtab: Input data used in the SAGA application.
• Data.txt: All profile data in a single file with “COASTLINE”, “PROFILE”, “DISTANCE”, “X”, “Y”, “Z” and “Z_DETREND”.
• Sediments Top elevation.sg-grd-z: A copy of the DEM input in SAGA format.

You can test the different options with the top and toe locations until your results are satisfactory and fine tune the user-defined parameters. The order of importance for the delineation results is as follows:

1. Digital Elevation Model (DEM): Its resolution directly affects to coastline definition.
2. Length of Coastline Normal (transect): Transects should not intersect, the longer they are, the more the number of transects will be reduced.
3. Coastline Smoothing Window Size: The degree of smoothing of the coastline defined as a number of points used for that purpose.
4. Still Water level: Elevation for coastline delineation.
5. User defined Coastline point: with a constrained location, the initial number of transects is predefined.

When finished, save the project (“File”>>” Project”>>”Save project”), a window will appear with the unsaved data. Check “Save all” and the project folder will be selected to save the output data for CliffMetrics (Fig. 5).

Fig. 5. The window to save unsaved or modified data in SAGA software.

LINUX VERSION

GitHub repository

The Linux version is available via the dedicated GitHub repository here: https://github.com/apayo/CliffMetrics/

INPUTS

The SAGA Linux version 1.0 requires 18 inputs, as shown below. The format of the input file is an ASCII file, with comments preceded by a semi-colon as the following file:

; SIMPLE TEST DATA
Run information -----------------------------------------------------------------------------------------------------
1 Main output/log file names [omit path and extension]: simple

2 DTM file (DTM MUST BE PRESENT) [path and name]: in/simple_fast/two_bays.asc

3 Still water level (m) used to find the shoreline  : 75

4 Coastline smoothing [0=none, 1=running mean, 2=Savitsky-Golay]: 1

5 Coastline smoothing window size [must be odd]: 55

6 Polynomial order for Savitsky-Golay coastline smoothing [2 or 4]: 4

If user wants to use a given shoreline vector instead of extracting it from the DTM

7 Shoreline shape file (OPTIONAL GIS FILES) [path and name]: in/simple_fast/chain_coastline.shp

8 Sea handiness (which side of shoreline the sea is? )[right = 0 or left = 1]: 0

9 On which Edge is the start of user shoreline? [N = 1, E = 2, S = 3, W = 4]: 1

10 On which Edge is the end of user shoreline? [N = 1, E = 2, S = 3, W = 4]: 3

Advance Run information -----------------------------------------------------------------------------------------------------

11 GIS raster output format [blank=same as DEM input]: gtiff  ; gdal-config --formats for others

12 If needed, also output GIS raster world file? [y/n]: y

13 If needed, scale GIS raster output values? [y/n]: y

14 GIS vector output format  : ESRI Shapefile  ; ogrinfo --formats for others

15 Random edge for coastline search? [y/n]: n

16 Random number seed(s)  : 280761

17 Length of coastline normals (m)  : 50

18 Vertical tolerance to consider to elevation different (m)  : 0.5

END OF FILE ----------------------------------------------------------------------------------------------------------

To run the software, follow instruction at GitHub website.

OUTPUTS

The Linux version of CliffMetrics produces the same results as the SAGA GIS version. Outputs are saved in the user defined folder, as explained in the README file in the dedicated GitHub repository.

Example SAGA WINDOWS

Download input data from https://bgs.sharefile.eu/share/getinfo/s9001cf5659546359

The study area is St Bees head (3.6252W; 54.5128N) in Cumbria County in northwest England (UK) and defined in EPSG 27700 (OSGB36 / British National Grid). The Inputs.zip file contains: - a 5 m resolution DEM model in geotiff format (DEM.tif) from NEXTMap dataset (https://catalogue.ceda.ac.uk/uuid/8f6e1598372c058f07b0aeac2442366d) derived by airborne radar technology, - a coastline as a line shapefile (coastline.shp), - a user defined coastline points in shapefile format (coastline_points.shp) obtained from the previous file (coastline.shp).

Follow these steps:

- Open SAGA software - Load the data in SAGA:

• DEM: “File”>>” Grid”>>”Load”, browse the folder and select the “DEM.tif” file and click on “Open”
• Load the Shapefiles: “File”>>”Shapes”>>”Load”, navigate to the folder and select the coastline_points.shp (not necessary in the case of automatic delineation) and then, the coastline.shp (remember, this last line shape is for a better coastal representation of the coast and is included as auxiliary information). The Shapefile format is composed by several files, but the main file to load is *.shp

NOTE: Another load option could be to use the “Data Sources” panel. Find the folder in this panel and right click button on each file and select “Open”. - View the data: you can now select the “Data” window tab in the “Manager” box and view the data by double-clicking on the names. When choosing the second layer, be sure to select the same map window as the first layer. SAGA will probably show you a warning about a different coordinate system and the option to turn on projection On-the-fly, in this case click “Yes” (Fig. 6). You can change the symbology and colour by opening “Object Properties” window. - Save the project in this step with an arbitrary name: “File”>>”Project”>>”Save Project”.

Fig. 6. Visualize the example data. This DEM shows the lowest elevation in blue and the highest elevations in red. Sea cells have been assigned as 0 m (dark blue)

- Open CliffMetrics tool (“Geoprocessing”>> “Terrain Analysis” >> “Coastal Morphology” >> “CliffMetrics”). From this step, we explain the two different input options in Cliffmetrics: an automatic delineation of the coastline or using a layer of coastline points.