REM Module#

This module can be used to automatically produce visualizations of river relative elevation models (REMs) from an input DEM.

River centerlines#

River centerlines used to create REMs are automatically retrieved from the OpenStreetMap (OSM) API. If a desired river segment is not listed on OSM, a new river centerline can be created/edited on the OSM site (clear the OSM cache folder after using the OSM editor to get the updated centerline). Alternatively, if OSM is up to date but the input DEM has older river topography, a user-provided centerline shapefile can be input, overriding the OSM centerline.

Points sampled along the river centerline(s) are output as a shapefile along with each output REM raster. These points can be viewed to help ensure that the applied centerline is accurate.

Handling large datasets#

For very large/high resolution DEMs, interpolation can take a long time. While this module is designed to work well using the default settings on a variety of datasets, interpolation can be sped up by changing the following parameters from default values:

  • decreasing interp_pts (fewer total centerline sample points)

  • decreasing k (fewer centerline samples per interpolation)

  • increasing eps (less accurate interpolation)

  • increasing workers (if more CPU threads are available)

  • increasing chunk_size (if more RAM is available)

REMMaker module#

riverrem.REMMaker.clear_osm_cache()#

Clear the OSM cache folder (./.osm_cache). This is useful if the OSM Editor has been used to update river centerlines.

class riverrem.REMMaker.REMMaker(dem, centerline_shp=None, out_dir='./', interp_pts=1000, k=None, eps=0.1, workers=12, chunk_size=1000000.0, cache_dir='./.cache')#

Handler to automatically make a river REM from an input DEM.

Parameters:

  • dem (str) – path to input DEM raster.

  • centerline_shp (str) – (optional) river centerline shapefile to use. If given, overrides OpenStreetMap centerline.

  • out_dir (str) – output file directory. Defaults to current working directory.

  • interp_pts (int) – maximum number of points to use for interpolation of river centerline elevation. Actual number of points is limited by number of DEM pixels along centerline, so less points may be used for lower resolution DEMs.

  • k (int) – number of nearest neighbors to use for IDW interpolation. If None, an appropriate value is estimated. The estimation routine uses k between 5-100 points (0.5-10% of the river length) depending on the sinuosity of the river of interest. Greater values of k are used for more sinuous rivers.

  • eps (float) – fractional error tolerance for finding nearest neighbors in KD tree query. Higher values allow faster interpolation at the expense of accuracy.

  • workers (int) – number of CPU threads to use for interpolation. -1 uses all threads.

  • chunk_size (int) – how many raster cells to process through KD tree per chunk. Higher values run faster but use more RAM.

  • cache_dir (str) – cache directory

make_rem()#

Make a relative elevation model (REM). Note that this method creates a raw REM raster and doesn’t apply color-relief/shading for visualization.

Returns:

path to output REM raster.

Return type:

str

make_rem_viz(cmap='topo', z=4, blend_percent=25, make_png=True, make_kmz=False, *args, **kwargs)#

Create REM visualization by blending the REM color-relief with a DEM hillshade to make a pretty finished product.

Parameters:

  • cmap (str) – name of matplotlib/seaborn/cmocean named colormap to use for REM coloring (see https://matplotlib.org/stable/gallery/color/colormap_reference.html). Note the applied colormap is logarithmically scaled in order to emphasize elevations differences close to the river centerline.

  • z (float >1) – z factor for exaggerating vertical scale differences of hillshade.

  • blend_percent (float [0-100]) – Percent weight of hillshdae in blended image, color-relief takes opposite weight.

  • make_png (bool) – Specify whether to make a georeferenced png image of the visualization in addition to a GeoTIFF.

  • make_kmz (bool) – Specify whether to make a kmz file of the visualization (e.g. for Google Earth) in addition to a GeoTIFF.

Returns:

path to output raster

Return type:

str