rvt.vis#

Relief Visualization Toolbox – Visualization Functions

Contains functions for computing the visualizations.

rvt.vis.byte_scale(data, c_min=None, c_max=None, high=255, low=0, no_data=None)[source]#

Remade old scipy function. Byte scales an array (image). Linear scale.

Byte scaling means converting the input image to uint8 dtype and scaling the range to (low, high) (default 0-255).

Parameters:

data (numpy.ndarray) – Input data (visualization) as 2D or multi-D numpy array.
c_min (int or float) – Scalar, Bias scaling of small values. Default is data.min().
c_max (int or float) – Scalar, Bias scaling of large values. Default is data.max().
high (int) – Scalar, Scale max value to high. Default is 255.
low (int) – Scalar, Scale min value to low. Default is 0.
no_data (int or float) – Value that represents no_data, it is changed to np.nan .

Returns:

img_array – The byte-scaled array.

Return type:

uint8 numpy.ndarray

rvt.vis.slope_aspect(dem, resolution_x=1, resolution_y=1, output_units='radian', ve_factor=1, no_data=None)[source]#

Procedure can return terrain slope and aspect in radian units (default) or in alternative units (if specified). Available alternative units are ‘degree’ and ‘percent’. Slope is defined as 0 for horizontal plane and pi/2 for vertical plane. Aspect is defined as geographic azimuth: clockwise increasing, 0 or 2pi for the North direction.

0

270 90
180

Currently applied finite difference method.

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
resolution_x (int) – DEM resolution in X direction.
resolution_y (int) – DEM resolution in Y direction.
output_units (str) – Output units, you can choose between: percent, degree, radian. Default value is radian.
ve_factor (int or float) – Vertical exaggeration factor.
no_data (int or float) – Value that represents no_data, all pixels with this value are changed to np.nan. Only has to be specified if a numerical value is used for nodata (e.g. -9999).

Returns:

dict_out – Returns {“slope”: slope_out, “aspect”: aspect_out}; slope_out, slope gradient : 2D numpy array (numpy.ndarray) of slope; aspect_out, aspect : 2D numpy array (numpy.ndarray) of aspect.

Return type:

dict

rvt.vis.roll_fill_nans(dem, shift, axis)[source]#

Uses numpy.roll() function to roll array, then checks element-wise if new array has NaN value, but there was a numerical value in the source array, then use the original value instead of NaN. It is equivalent to edge padding.

https://numpy.org/doc/stable/reference/generated/numpy.roll.html#numpy.roll

rvt.vis.hillshade(dem, resolution_x, resolution_y, sun_azimuth=315, sun_elevation=35, slope=None, aspect=None, ve_factor=1, no_data=None)[source]#

Compute hillshade.

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
resolution_x (int) – DEM resolution in X direction.
resolution_y (int) – DEM resolution in Y direction.
sun_azimuth (int or float) – Solar azimuth angle (clockwise from North) in degrees.
sun_elevation (int or float) – Solar vertical angle (above the horizon) in degrees.
slope (numpy.ndarray) – Slope arr in radians if you don’t input it, it is calculated.
aspect (numpy.ndarray) – Aspect arr in radians if you don’t input it, it is calculated.
ve_factor (int or float) – Vertical exaggeration factor.
no_data (int or float) – Value that represents no_data, all pixels with this value are changed to np.nan.

Returns:

hillshade_out – Result hillshade 2D numpy array.

Return type:

numpy.ndarray

rvt.vis.multi_hillshade(dem, resolution_x, resolution_y, nr_directions=16, sun_elevation=35, slope=None, aspect=None, ve_factor=1, no_data=None)[source]#

Calculates hillshades from multiple directions.

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
resolution_x (int) – DEM resolution in X direction.
resolution_y (int) – DEM resolution in Y direction.
nr_directions (int) – Number of solar azimuth angles (clockwise from North).
sun_elevation (int or float) – Solar vertical angle (above the horizon) in degrees.
slope (numpy.ndarray) – Slope in radians if you don’t input it, it is calculated.
aspect (numpy.ndarray) – Aspect in radians if you don’t input it, it is calculated.
ve_factor (int or float) – Vertical exaggeration factor.
no_data (int or float) – Value that represents no_data, all pixels with this value are changed to np.nan .

Returns:

multi_hillshade_out – Result multiple direction hillshade multidimensional (nr_directions=dimensions) numpy array.

Return type:

numpy.ndarray

rvt.vis.mean_filter(dem, kernel_radius)[source]#: Applies mean filter (low pass filter) on DEM. Kernel radius is in pixels. Kernel size is 2 * kernel_radius + 1. It uses matrix shifting (roll) instead of convolutional approach (works faster). It returns mean filtered dem as numpy.ndarray (2D numpy array).

rvt.vis.slrm(dem, radius_cell=20, ve_factor=1, no_data=None)[source]#

Calculates Simple local relief model.

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
radius_cell (int) – Radius for trend assessment in pixels.
ve_factor (int or float) – Vertical exaggeration factor.
no_data (int or float) – Value that represents no_data, all pixels with this value are changed to np.nan .

Returns:

slrm_out – Simple local relief model 2D numpy array.

Return type:

numpy.ndarray

rvt.vis.horizon_shift_vector(num_directions=16, radius_pixels=10, min_radius=1)[source]#

Calculates Sky-View determination movements.

Parameters:

num_directions (int) – Number of directions as input.
radius_pixels (int) – Radius to consider in pixels (not in meters).
min_radius (int) – Radius to start searching for horizon in pixels (not in meters).

Returns:

shift –

Dict with keys corresponding to the directions of search azimuths rounded to 1 decimal number

for each key, a subdict contains a key “shift”:
values for this key is a list of tuples prepared for np.roll - shift along lines and columns
the second key is “distance”:
values for this key is a list of search radius used for the computation of the elevation angle

Return type:

dict

rvt.vis.sky_view_factor_compute(height_arr, radius_max=10, radius_min=1, num_directions=16, compute_svf=True, compute_opns=False, compute_asvf=False, a_main_direction=315.0, a_poly_level=4, a_min_weight=0.4)[source]#

Calculates horizon based visualizations: Sky-view factor, Anisotropic SVF and Openness.

SVF processing is using search radius, that looks at values beyond the edge of an array. Consider using a buffered array as an input, with the buffer size equal to the radius_max. To prevent erosion of the edge, function applies mirrored padding in all four directions, however, this means that edge values are “averaged over half of the hemisphere”. Similarly, the edges of the dataset (i.e. areas with NaN values), will be considered as fully open (SFV angle 0, Openness angle -90).

Input array should use np.nan as nodata value.

Parameters:

height_arr (numpy.ndarray) – Elevation (DEM) as 2D numpy array.
radius_max (int) – Maximal search radius in pixels/cells (not in meters).
radius_min (int) – Minimal search radius in pixels/cells (not in meters), for noise reduction.
num_directions (int) – Number of directions as input.
compute_svf (bool) – If true it computes and outputs svf.
compute_asvf (bool) – If true it computes and outputs asvf.
compute_opns (bool) – If true it computes and outputs opns.
a_main_direction (int or float) – Main direction of anisotropy.
a_poly_level (int) – Level of polynomial that determines the anisotropy.
a_min_weight (float) –

Weight to consider anisotropy:
0 - low anisotropy, 1 - high anisotropy (no illumination from the direction opposite the main direction)

Returns:

dict_out – Return {“svf”: svf_out, “asvf”: asvf_out, “opns”: opns_out}; svf_out, skyview factor : 2D numpy array (numpy.ndarray) of skyview factor; asvf_out, anisotropic skyview factor : 2D numpy array (numpy.ndarray) of anisotropic skyview factor; opns_out, openness : 2D numpy array (numpy.ndarray) openness (elevation angle of horizon).

Return type:

dictionary

rvt.vis.sky_view_factor(dem, resolution, compute_svf=True, compute_opns=False, compute_asvf=False, svf_n_dir=16, svf_r_max=10, svf_noise=0, asvf_dir=315, asvf_level=1, ve_factor=1, no_data=None)[source]#

Prepare the data, call sky_view_factor_compute, reformat and return back 2D arrays.

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
compute_svf (bool) – Compute SVF (True) or not (False).
compute_opns (bool) – Compute OPENNESS (True) or not (False).
resolution (float) – Pixel resolution.
svf_n_dir (int) – Number of directions.
svf_r_max (int) – Maximal search radius in pixels.
svf_noise (int) – The level of noise remove (0-don’t remove, 1-low, 2-med, 3-high).
compute_asvf (bool) – Compute anisotropic SVF (True) or not (False).
asvf_level (int) – Level of anisotropy, 1-low, 2-high.
asvf_dir (int or float) – Direction of anisotropy.
ve_factor (int or float) – Vertical exaggeration factor.
no_data (int or float) – Value that represents no_data, all pixels with this value are changed to np.nan. Use this parameter when nodata is not np.nan.

Returns:

Return type:

dictionary

rvt.vis.local_dominance(dem, min_rad=10, max_rad=20, rad_inc=1, angular_res=15, observer_height=1.7, ve_factor=1, no_data=None)[source]#

Compute Local Dominance dem visualization. Adapted from original version that is part of the Lidar Visualisation Toolbox LiVT developed by Ralf Hesse.

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
min_rad (int) – Minimum radial distance (in pixels) at which the algorithm starts with visualization computation.
max_rad (int) – Maximum radial distance (in pixels) at which the algorithm ends with visualization computation.
rad_inc (int) – Radial distance steps in pixels.
angular_res (int) – Angular step for determination of number of angular directions.
observer_height (int or float) – Height at which we observe the terrain.
ve_factor (int or float) – Vertical exaggeration factor.
no_data (int or float) – Value that represents no_data, all pixels with this value are changed to np.nan .

Returns:

local_dom_out – 2D numpy array of local dominance

Return type:

numpy.ndarray

rvt.vis.horizon_generate_coarse_dem(dem_fine, pyramid_scale, conv_from, conv_to, max_radius)[source]#

rvt.vis.horizon_generate_pyramids(dem, num_directions=4, max_fine_radius=100, max_pyramid_radius=7, pyramid_scale=3)[source]#

rvt.vis.sky_illumination(dem, resolution, sky_model='overcast', compute_shadow=False, shadow_horizon_only=False, max_fine_radius=100, num_directions=32, shadow_az=315, shadow_el=35, ve_factor=1, no_data=None)[source]#

Compute topographic corrections for sky illumination.

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
resolution (float) – DEM pixel size.
sky_model (str) – Sky model, it can be ‘overcast’ or ‘uniform’.
compute_shadow (bool) – If True it computes and adds shadow.
shadow_horizon_only (bool) – Returns dict {“shadow”: shadow, “horizon”: horizon}
max_fine_radius (int) – Max shadow modeling distance in pixels.
num_directions (int) – Number of directions to search for horizon.
shadow_az (int or float) – Shadow azimuth.
shadow_el (int or float) – Shadow elevation.
ve_factor (int or float) – Vertical exaggeration factor.
no_data (int or float) – Value that represents no_data, all pixels with this value are changed to np.nan .

Returns:

sky_illumination – 2D numpy result array of Sky illumination.

Return type:

numpy.ndarray

rvt.vis.shadow_horizon(dem, resolution, shadow_az=315, shadow_el=35, ve_factor=1, no_data=None)[source]#

Compute shadow and horizon.

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
resolution (float) – DEM pixel size.
shadow_az (int or float) – Shadow azimuth.
shadow_el (int or float) – Shadow elevation.
ve_factor (int or float) – Vertical exaggeration factor.
no_data (int or float) – Value that represents no_data, all pixels with this value are changed to np.nan .

Returns:

dict_out – Returns {“shadow”: shadow, “horizon”: horizon}; shadow : 2D binary numpy array (numpy.ndarray) of shadows; horizon; 2D numpy array (numpy.ndarray) of horizon.

Return type:

dict

rvt.vis.msrm(dem, resolution, feature_min, feature_max, scaling_factor, ve_factor=1, no_data=None)[source]#

Compute Multi-scale relief model (MSRM).

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
resolution (float) – DEM pixel size.
feature_min (float) – Minimum size of the feature you want to detect in meters.
feature_max (float) – Maximum size of the feature you want to detect in meters.
scaling_factor (int) – Scaling factor, if larger than 1 it provides larger range of MSRM values (increase contrast and visibility), but could result in a loss of sensitivity for intermediate sized features.
ve_factor (int or float) – Vertical exaggeration factor.
no_data (int or float) – Value that represents no_data, all pixels with this value are changed to np.nan .

Returns:

msrm_out – 2D numpy result array of Multi-scale relief model.

Return type:

numpy.ndarray

rvt.vis.integral_image(dem, data_type=<class 'numpy.float64'>)[source]#

Calculates integral image (summed-area table), where origin is left upper corner.

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
data_type (np.__class__) – dtype as numpy data type class (np.float64, np.int8, etc.)

Returns:

msrm_out – Cumulative sum of the elements along each axis of a 2D array.

Return type:

numpy.ndarray

References

https://en.wikipedia.org/wiki/Summed-area_table

Examples

In: print(integral_image(np.array([[7, 4, 7, 2], … [6, 9, 9, 5], … [6, 6, 7, 6]])))

Out: [[ 7. 11. 18. 20.]: [13. 26. 42. 49.] [19. 38. 61. 74.]]

rvt.vis.topographic_dev(dem, dem_i_nr_pixels, dem_i1, dem_i2, kernel_radius)[source]#

Calculates topographic DEV - Deviation from mean elevation. DEV(D) = (z0 - zmD) / sD. Where D is radius of kernel, z0 is center pixel value, zmD is mean of all kernel values, sD is standard deviation of kernel.

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
dem_i_nr_pixels (numpy.ndarray) – Summed area table (integral image) of number of pixels.
dem_i1 (numpy.ndarray) – Summed area table (integral image) of dem.
dem_i2 (numpy.ndarray) – Summed area table (integral image) of dem squared (dem**2).
kernel_radius (int) – Kernel radius (D).

Returns:

dev_out – 2D numpy result array of topographic DEV - Deviation from mean elevation.

Return type:

numpy.ndarray

rvt.vis.max_elevation_deviation(dem, minimum_radius, maximum_radius, step)[source]#

Calculates maximum deviation from mean elevation, dev_max (Maximum Deviation from mean elevation) for each grid cell in a digital elevation model (DEM) across a range specified spatial scales.

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
minimum_radius (int) – Minimum radius to calculate DEV (topographic_dev).
maximum_radius (int) – Maximum radius to calculate DEV (topographic_dev).
step (int) – Step from minimum to maximum radius to calc DEV (topographic_dev).

Returns:

dev_out – 2D numpy result array of maxDEV - Maximum Deviation from mean elevation.

Return type:

numpy.ndarray

rvt.vis.mstp(dem, local_scale=(3, 21, 2), meso_scale=(23, 203, 18), broad_scale=(223, 2023, 180), lightness=1.2, ve_factor=1, no_data=None)[source]#

Compute Multi-scale topographic position (MSTP).

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
local_scale (tuple(int, int, int)) – Input local scale minimum radius (local_scale[0]), maximum radius (local_scale[1]), step (local_scale[2]).
meso_scale (tuple(int, int, int)) – Input meso scale minimum radius (meso_scale[0]), maximum radius (meso_scale[1]), step (meso_scale[2]).
broad_scale (tuple(int, int, int)) – Input broad scale minimum radius (broad_scale[0]), maximum radius (broad_scale[1]), step (broad_scale[2]).
lightness (float) – Lightness of image.
ve_factor (int or float) – Vertical exaggeration factor.
no_data (int or float) – Value that represents no_data, all pixels with this value are changed to np.nan .

Returns:

msrm_out – 3D numpy RGB result array of Multi-scale topographic position.

Return type:

numpy.ndarray

rvt.vis.fill_where_nan(dem, method='idw')[source]#

Replaces np.nan values, with interpolation (extrapolation).

Parameters:

dem (numpy.ndarray) – Input digital elevation model as 2D numpy array.
method ({'linear_row', 'idw_r_p', 'kd_tree', 'nearest_neighbour'}) – ‘linear_row’, Linear row interpolation, array is flattened and then linear interpolation is performed. This method is fast but very inaccurate. ‘idw_r_p’, Inverse Distance Weighting interpolation. If you only input idw it will take default parameters (r=20, p=2). You can also input interpolation radius (r) and power (p) for weights. (Example: idw_5_2 means radius = 5, power = 2.) ‘kd_tree’, K-D Tree interpolation. ‘nearest_neighbour’, Nearest neighbour interpolation.