RSGISLib Elevation

Slope and Aspect

rsgislib.elevation.slope(input_img, output_img, gdalformat, unit)

Calculates a slope layer given an input elevation model.

Parameters:

input_img – is a string containing the name and path of the input DEM file.
output_img – is a string containing the name and path of the output file.
gdalformat – is a string with the output image format for the GDAL driver.
unit – is a string specifying the output unit (‘degrees’ or ‘radians’).

rsgislib.elevation.slope_pxl_res_img(in_dem_img, in_pxl_res_img, output_img, gdalformat, unit)

Calculates a slope layer given an input elevation model and external pixel resolution image, which allows the slope to be calculated for images in projections (e.g., EPSG:4326) which do not use the same units as the elevation values (e.g., metres).

Parameters:

in_dem_img – is a string containing the name and path of the input DEM file.
in_pxl_res_img – is a string containing the name and path of the input image. specifying the image pixel resolutions. Band 1: East-West resolution and Band 2 is the North-South resolution.
output_img – is a string containing the name and path of the output file.
unit – is a string specifying the output unit (‘degrees’ or ‘radians’).
gdalformat – is a string with the output image format for the GDAL driver.

rsgislib.elevation.aspect(input_img, output_img, gdalformat)

Calculates a aspect layer given an input elevation model

Parameters:

input_img – is a string containing the name and path of the input DEM file.
output_img – is a string containing the name and path of the output file.
gdalformat – is a string with the output image format for the GDAL driver.

rsgislib.elevation.aspect_pxl_res_img(in_dem_img, in_pxl_res_img, output_img, gdalformat)

Calculates a aspect layer given an input elevation model and external pixel resolution image, which allows the slope to be calculated for images in projections (e.g., EPSG:4326) which do not use the same units as the elevation values (e.g., metres).

Parameters:

in_dem_img – is a string containing the name and path of the input DEM file.
in_pxl_res_img – is a string containing the name and path of the input image. specifying the image pixel resolutions. Band 1: East-West resolution and Band 2 is the North-South resolution.
output_img – is a string containing the name and path of the output file.
gdalformat – is a string with the output image format for the GDAL driver.

rsgislib.elevation.catagorise_aspect(input_img, output_img, gdalformat)

Creates an aspect layer which is categorised into 8 catergories from 0-45, 45-90, 90-135, 135-180, 180-225, 225-270, 270-315 and 315-360.

Parameters:

input_img – is a string containing the name and path of the input aspect (in degrees) file.
output_img – is a string containing the name and path of the output file.
gdalformat – is a string with the output image format for the GDAL driver.

Flitering

rsgislib.elevation.dtm_aspect_median_filter(in_dem_img, in_aspect_img, output_img, aspect_range, win_h_size, gdalformat)

Filter the DTM for noise using a median filter with an aspect restriction (i.e., only pixels within the aspect range of the centre pixel will be used within the median filter).

Parameters:

in_dem_img – is a string containing the name and path of the input DTM file.
in_aspect_img – is a string containing the name and path of the input Aspect file (in degrees).
output_img – is a string containing the name and path of the output file.
aspect_range – is a float with the range of from the centre pixel in degrees.
win_h_size – is an integer for half the window size.
gdalformat – is a string with the output image format for the GDAL driver.

rsgislib.elevation.fill_dem_soille_gratin_1994(in_dem_img, in_vld_img, output_img, gdalformat)

Filter the local minima in a DEM using the Soille and Gratin 1994 algorithm.

Soille, P., and Gratin, C. (1994). An efficient algorithm for drainage network extraction on DEMs. J. Visual Communication and Image Representation. 5(2). 181-189.

Parameters:

in_dem_img – is a string containing the name and path of the input DEM file.
in_vld_img – is a string containing the name and path to a binary image specifying the valid data region (1 == valid)
output_img – is a string containing the name and path of the output file.
gdalformat – is a string with the output image format for the GDAL driver.

import rsgislib.elevation
inputDEMImage = 'DEM.kea'
validMaskImage = 'ValidRegionMask.kea'
outFilledImage = 'DEM_filled.kea'
rsgislib.elevation.fill_dem_soille_gratin_1994(inputDEMImage, validMaskImage, outFilledImage, 'KEA')

rsgislib.elevation.plane_fit_detreat_dem(input_img, output_img, gdalformat, win_size)

An algorithm to detread a DEM using local plane fitting. The winSize will define the scale at which the DEM will be detreaded.

Parameters:

input_img – is a string containing the name and path of the input DEM file.
output_img – is a string containing the name and path of the output file.
gdalformat – is a string with the output image format for the GDAL driver.
win_size – is an integer with the window size within which the plane is fitted.

import rsgislib.elevation
inputDEMImage = 'DEM.kea'
outDEMImage = 'DEM_Detread.kea'
rsgislib.elevation.plane_fit_detreat_dem(inputDEMImage, outDEMImage, 'KEA', 11)

rsgislib.elevation.resampling_detread_dem(input_img: str, output_img: str, resmp_res: int, gdalformat: str, no_data_val: float = None, datatype: int = None, tmp_dir: str = None, low_resmp_mthd: int = 5, up_smpl_mthd: int = 3)

A function which using image resampling to down sample the input DEM (image) to the specified resolution and then up samples it back to the original resolution.

Parameters:

input_img – Input image - note only band 1 is used
output_img – Output image path
resmp_res – The intermediate down sample resolution.
gdalformat – output image format (e.g., KEA, GTIFF).
no_data_val – the DEM no data value. If None then read from input image header.
datatype – The output image data type. If None then the same as the input image.
tmp_dir – A temp directory for intermediate outputs. If None then one is created.
low_resmp_mthd – The method used to down sample the input image. Default: rsgislib.INTERP_AVERAGE
up_smpl_mthd – The method used to up sample the down sampled image. Default: rsgislib.INTERP_CUBICSPLINE

Masking

rsgislib.elevation.shadow_mask(input_img, output_img, azimuth, zenith, max_height, gdalformat)

Calculates a shadow mask given an input elevation model

Parameters:

input_img – is a string containing the name and path of the input DEM file.
output_img – is a string containing the name and path of the output file.
azimuth – is a float with the solar azimuth in degrees.
zenith – is a float with the solar zenith in degrees.
max_height – is a float with the maximum height for the ray tracing (should be above the maximum elevation within the scene).:param gdalformat: is a string with the output image format for the GDAL driver.

Incidence / Existance Angle

rsgislib.elevation.local_incidence_angle(input_img, output_img, azimuth, zenith, gdalformat)

Calculates a local solar incidence angle layer given an input elevation model

Parameters:

input_img – is a string containing the name and path of the input DEM file.
output_img – is a string containing the name and path of the output file.
azimuth – is a float with the solar azimuth in degrees.
zenith – is a float with the solar zenith in degrees.
gdalformat – is a string with the output image format for the GDAL driver.

rsgislib.elevation.local_existance_angle(input_img, output_img, azimuth, zenith, gdalformat)

Calculates a local solar existance angle layer given an input elevation model

Parameters:

input_img – is a string containing the name and path of the input DEM file.
output_img – is a string containing the name and path of the output file.
azimuth – is a float with the solar azimuth in degrees.
zenith – is a float with the solar zenith in degrees.
gdalformat – is a string with the output image format for the GDAL driver.

Visualisation

rsgislib.elevation.hillshade(input_img, output_img, azimuth, zenith, gdalformat)

Calculates a hillshade layer given an input elevation model

Parameters:

input_img – is a string containing the name and path of the input DEM file.
output_img – is a string containing the name and path of the output file.
azimuth – is a float with the solar azimuth in degrees (Good value is 315).
zenith – is a float with the solar zenith in degrees (Good value is 45).
gdalformat – is a string with the output image format for the GDAL driver.

rsgislib.elevation.hillshade_pxl_res_img(in_dem_img, in_pxl_res_img, output_img, azimuth, zenith, gdalformat)

Calculates a hillshade layer given an input elevation model and external pixel resolution image, which allows the slope to be calculated for images in projections (e.g., EPSG:4326) which do not use the same units as the elevation values (e.g., metres).

Parameters:

in_dem_img – is a string containing the name and path of the input DEM file.
in_pxl_res_img – is a string containing the name and path of the input image. specifying the image pixel resolutions. Band 1: East-West resolution and Band 2 is the North-South resolution.
output_img – is a string containing the name and path of the output file.
azimuth – is a float with the solar azimuth in degrees (Good value is 315).
zenith – is a float with the solar zenith in degrees (Good value is 45).
gdalformat – is a string with the output image format for the GDAL driver.

Fusion

rsgislib.elevation.fft_dem_fusion(high_res_dem_img: str, low_res_dem_img: str, fused_dem_img: str, c_size: int = 20)

This function merges DEMs (any single band file) using a fourier transformation where the low frequency component is taken from the lower resolution DEM and the high frequency component is taken from the higher resolution DEM.

This is an implementation ideas from:

Karkee, M., Steward, B. L., & Aziz, S. A. (2008). Improving quality of public domain digital elevation models through data fusion. Biosystems Engineering, 101(3), 293–305.

Parameters:

high_res_DEM_img – is an input image file for the high resolution DEM file.
low_res_DEM_img – is an input image file for the low resolution DEM file.
fused_DEM_img – is an output image file for the resulting fused DEM.
c_size – is the threshold (int) defining the high and low frequencies.

import rsgislib
from rsgislib import elevation

high_res_DEM_img = "N09E009_TDX_12m_EGM08.tif"
low_res_DEM_img = "N09E009_SRTM_30m_EGM08.tif"
fused_DEM_img = "NO9E009_SRTM_TDX_EGM08_fusion.tif"
c_size = 10

elevation.fft_dem_fusion(highResDEMImg, lowResDEMImg, fusedDEMImg, cSize=20)

Roughness

rsgislib.elevation.roughness.calc_simple_roughness_profile_metrics(input_img: str, vec_file: str, vec_lyr: str, out_vec_file: str, out_vec_lyr: str, out_format: str = 'GPKG', interp_method: int = 2, angle_col: str = None, x_box_col: str = 'xbox', y_box_col: str = 'ybox', no_data_val: float = None, detrend: bool = True, detrend_poly_order: int = 1, export_plot_path: str = None)

A function which uses the CalcProfileRoughMetrics class to calculate roughness metrics in x and y axis of the window of data provided. The metrics calculated are:

Average roughness (RA): Average of profile height deviations from the mean

Random roughness (RR)

Quadratic mean roughness (RQ) - Sum of absolute slopes.

The microrelief index (MIF)

Maximum valley depth below the mean line (RV)

Maximum peak height above the mean line (RP)

Maximum peak to valley height of the profile (RZ)

Skewness, or measure of asymmetry of the profile about the mean line (RSK)

Kurtosis, or measure of peakedness (or tailedness) of the profile about the mean line (RKU)

See https://en.wikipedia.org/wiki/Surface_roughness for more information.

Parameters:

input_img – input image file.
vec_file – input vector file - needs to be a point type.
vec_lyr – input vector layer name.
out_vec_file – output vector file path.
out_vec_lyr – output vector layer name.
out_format – output vector file format (e.g., GeoJSON)
interp_method – the interpolation method used when reorientating the image data. Default: rsgislib.INTERP_CUBIC
angle_col – name of the column within the vector attribute table defining the rotation (relative to north; 0 = North) for each point. If None (Default) then no rotation applied. (Unit is degrees)
x_box_col – name of the column within the vector attribute table defining the size of the bbox in the x axis. Note, this is half the bbox width. (Unit is image pixels)
y_box_col – name of the column within the vector attribute table defining the size of the bbox in the y axis. Note, this is half the bbox height. (Unit is image pixels)
no_data_val – the image no data value. If None then taken from the input image header.
detrend – Boolean to specify whether to detrend the surface or not. Default: True
detrend_poly_order – the order of the polynomial used to detrend the surface.
export_plot_path – If a directory path is provided then plots will be created for each of the sample windows. This is expected to be a debugging and data exploration tool as it significantly slows processing. If None (default) then no plots will be exported.

rsgislib.elevation.roughness.calc_munro_roughness_profile_metrics(input_img: str, vec_file: str, vec_lyr: str, out_vec_file: str, out_vec_lyr: str, out_format: str = 'GPKG', interp_method: int = 2, angle_col: str = None, x_box_col: str = 'xbox', y_box_col: str = 'ybox', no_data_val: float = None, detrend: bool = True, detrend_poly_order: int = 1, export_plot_path: str = None)

A function which uses the CalcMunroRoughnessMetric class to calculate the munro Z0 roughness metrics in x and y axis of the window of data provided.

Parameters:

input_img – input image file.
vec_file – input vector file - needs to be a point type.
vec_lyr – input vector layer name.
out_vec_file – output vector file path.
out_vec_lyr – output vector layer name.
out_format – output vector file format (e.g., GeoJSON)
interp_method – the interpolation method used when reorientating the image data. Default: rsgislib.INTERP_CUBIC
angle_col – name of the column within the vector attribute table defining the rotation (relative to north; 0 = North) for each point. If None (Default) then no rotation applied. (Unit is degrees)
x_box_col – name of the column within the vector attribute table defining the size of the bbox in the x axis. Note, this is half the bbox width. (Unit is image pixels)
y_box_col – name of the column within the vector attribute table defining the size of the bbox in the y axis. Note, this is half the bbox height. (Unit is image pixels)
no_data_val – the image no data value. If None then taken from the input image header.
detrend – Boolean to specify whether to detrend the surface or not. Default: True
detrend_poly_order – the order of the polynomial used to detrend the surface.
export_plot_path – If a directory path is provided then plots will be created for each of the sample windows. This is expected to be a debugging and data exploration tool as it significantly slows processing. If None (default) then no plots will be exported.

rsgislib.elevation.roughness.calc_smith_roughness_metrics(input_img: str, vec_file: str, vec_lyr: str, out_vec_file: str, out_vec_lyr: str, out_format: str = 'GPKG', interp_method: int = 2, angle_col: str = None, x_box_col: str = 'xbox', y_box_col: str = 'ybox', no_data_val: float = None, detrend: bool = True, export_plot_path: str = None)

A function which uses the CalcSmithRoughnessMetric class to calculate the smith et al 2016 Z0 roughness metrics in x and y axis of the window of data provided.

Parameters:

input_img – input image file.
vec_file – input vector file - needs to be a point type.
vec_lyr – input vector layer name.
out_vec_file – output vector file path.
out_vec_lyr – output vector layer name.
out_format – output vector file format (e.g., GeoJSON)
interp_method – the interpolation method used when reorientating the image data. Default: rsgislib.INTERP_CUBIC
angle_col – name of the column within the vector attribute table defining the rotation (relative to north; 0 = North) for each point. If None (Default) then no rotation applied. (Unit is degrees)
x_box_col – name of the column within the vector attribute table defining the size of the bbox in the x axis. Note, this is half the bbox width. (Unit is image pixels)
y_box_col – name of the column within the vector attribute table defining the size of the bbox in the y axis. Note, this is half the bbox height. (Unit is image pixels)
no_data_val – the image no data value. If None then taken from the input image header.
detrend – Boolean to specify whether to detrend the surface or not. Default: True
export_plot_path – If a directory path is provided then plots will be created for each of the sample windows. This is expected to be a debugging and data exploration tool as it significantly slows processing. If None (default) then no plots will be exported.

rsgislib.elevation.roughness.calc_all_roughness_profile_metrics(input_img: str, vec_file: str, vec_lyr: str, out_vec_file: str, out_vec_lyr: str, out_format: str = 'GPKG', interp_method: int = 2, angle_col: str = None, x_box_col: str = 'xbox', y_box_col: str = 'ybox', no_data_val: float = None, detrend: bool = True, detrend_poly_order: int = 1)

A function which uses the CalcProfileRoughMetrics and CalcMunroRoughnessMetric classes to calculate roughness metrics in x and y axis of the window of data provided.

Parameters:

input_img – input image file.
vec_file – input vector file - needs to be a point type.
vec_lyr – input vector layer name.
out_vec_file – output vector file path.
out_vec_lyr – output vector layer name.
out_format – output vector file format (e.g., GeoJSON)
interp_method – the interpolation method used when reorientating the image data. Default: rsgislib.INTERP_CUBIC
angle_col – name of the column within the vector attribute table defining the rotation (relative to north; 0 = North) for each point. If None (Default) then no rotation applied. (Unit is degrees)
x_box_col – name of the column within the vector attribute table defining the size of the bbox in the x axis. Note, this is half the bbox width. (Unit is image pixels)
y_box_col – name of the column within the vector attribute table defining the size of the bbox in the y axis. Note, this is half the bbox height. (Unit is image pixels)
no_data_val – the image no data value. If None then taken from the input image header.
detrend – Boolean to specify whether to detrend the surface or not. Default: True
detrend_poly_order – the order of the polynomial used to detrend the surface.