Nunataryuk

Basin delineation: 4 GRASS basin delineation

2020-10-28T00:00:00+00:00

Introduction

In this part (4) of the of the Basin delineation tutorial series you will run a GRASS command line script generated in part 3. The script delineates a vector polygon for each distilled outlet point generated from part 3. Then another command line script will call GDAL for assembling all polygons into a single data source. You need to manually inspect this file to determine if and what editing is required.

if you use the default ‘MOUTH’ process alternative, the script will first manipulate the input Digital Elevation Model (DEM) to better represented the flow path in river mouths and then use the manipulated DEM for identifying the extent of all larger river basins.

Prerequisites

You must have setup GRASS 7 and imported a DEM as described in Installation & Setup. Then you must have completed the GRASS watershed processing as outlined in part 2 and run the Python script Basin_extractor as described in part 3.

MOUTH processing

if you set the parameterization of basin_extract in part 3 to outlet=’MOUTH’, the generated GRASS command line script will be called “region”_grass_basin_mouth2.sh, where region is the study area. It will be saved in your project data directory where all other spatial datasets are exported. As defined in the xml file and following the general structure of KArttur’s GeoImagine Framework.

The GRASS shell script file start with commands for creating a virtual DEM and then rerunning r.watershed. Optionally the user can export intermediate raster layers by removing the ‘#’ sign. The generated commands for the Amazonia region used as example in this tutorial series are shown below. Your version will be similar, but with the regional identifier (amazonia in the example) replaced by your study region identifier. Also other parts of the file names may differ.

# Creating virtual DEM for directing hydrological flow in river basin mouths

# Import outlet points vector
v.in.ogr -o input=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-mouth2-outlet_drainage_amazonia_0_cgiar-250.shp output=basin_distil_mouth2_shorewall_pt --overwrite

# rasterize outlet points
v.to.rast input=basin_distil_mouth2_shorewall_pt output=basin_distil_mouth2_shorewall_pt type=point use=val value=1 --overwrite

# Add outlet points to river mouth DEM with all cells=1
r.mapcalc "basin_distil_mouth2_lowlevel_DEM = if(isnull(basin_distil_mouth2_shorewall_pt),lowlevel_outlet_costgrow+1,basin_distil_mouth2_shorewall_pt)" --overwrite

# cost grow analysis from new outlets over river mouth DEM
r.cost -n input=basin_distil_mouth2_lowlevel_DEM output=basin_distil_mouth2_mouth_dist start_points=basin_distil_mouth2_shorewall_pt max_cost=228 --overwrite

# export cost grow analysis (optional)
# r.out.gdal -f input=basin_distil_mouth2_mouth_dist format=GTiff type=Int16 output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-distil-mouth2-mouth-dist_drainage_amazonia_0_cgiar-250.tif --overwrite

# Invert cost grow to create mouth flow route DEM directing flow towards outlet point
r.mapcalc "basin_distil_mouth2_routing_dem = int(basin_distil_mouth2_mouth_dist-230)" --overwrite

# export the mouth flow route DEM (optional)
# r.out.gdal -f input=basin_distil_mouth2_routing_dem format=GTiff type=Int16 output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-distil-mouth2-routing-dem_drainage_amazonia_0_cgiar-250.tif --overwrite

# combine mouth flow route DEM with original DEM and add the shorewall
r.mapcalc "basin_distil_mouth2_basin_dem = if(isnull(basin_distil_mouth2_routing_dem),(if(isnull(DEM@PERMANENT),shorewall,DEM@PERMANENT)),basin_distil_mouth2_routing_dem)" --overwrite

# export the hydrological corrected DEM (optional)
# r.out.gdal -f input=basin_distil_mouth2_basin_dem format=GTiff type=Int16 output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-distil-mouth2-basin-dem_drainage_amazonia_0_cgiar-250.tif --overwrite

# run r.watershed for the new outlet points and the virtual (hydrologically corrected) DEM
r.watershed -a convergence=5 elevation=basin_distil_mouth2_basin_dem accumulation=basin_distil_mouth2_wshed_acc drainage=basin_distil_mouth2_wshed_draindir_draindir threshold=2000

# convert updrain accumulation raster to byte format (optional)
# r.mapcalc "basin_distil_mouth2_wshed_acc_ln = 10*log(basin_distil_mouth2_wshed_acc)" --overwrite

# Set color ramp for upstream accumulation raster (optional)
# set color ramp for byte version of updrain accumulationr.colors map=basin_distil_mouth2_wshed_acc_ln color=ryb

# export the visualised upstream accumulation raster (optional)
# r.out.gdal -f input=basin_distil_mouth2_wshed_acc_ln format=GTiff type=Byte output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-distil-mouth2-wshed-acc-ln_drainage_amazonia_0_cgiar-250.tif --overwrite

# add column "updrain" to the new outlet vector
v.db.addcolumn map=basin_distil_mouth2_shorewall_pt columns="updrain DOUBLE PRECISION"

# extract data from r.watersehd updrain to the column "updrain" in the outlet point map
v.what.rast map=basin_distil_mouth2_shorewall_ptc column=updrain raster=basin_distil_mouth2_wshed_acc

Run the shell script from your GRASS terminal with the active mapset being the same as when you processed the data in part 2. Before you can run the commands you have to change the permission of the shell file (.sh) itself. To change the permissions to an executable script, type at the terminal:

> chmod 777 “region”_grass_basin_mouth2.sh .

Tu run the file you need to give either the relative or full path, where the relative path would be:

> ./”region”_grass_basin_mouth2.sh .

The full path depends on where you put the GRASS location.

You can run the script now, as it will take several hours or even days to run. But that is not because of the commands above, but the commands following that create polygons of full river basins for each outlet point.

GRASS script for basin polygon delineation

For each identified outlet point from the Python script basin_extract in part 2 the delineation of the associated river basin contains the following steps:

identify all upstream cells from the outlet coordinates
convert the identified cell region to a polygon
clean the polygon form errors
build the polygon attribute table
export the polygon vector to an ESRI shape file

To save disk space, the raster version of the basin, created in the very first step, is deleted once the raster is vectorized in the second step. The actual GRASS commands for each outlet looks like the example below:

r.water.outlet input=basin_distil_mouth2_wshed_draindir output=basin_mouth2_000001 coordinates=-7928554.691232,1295538.184247 --overwrite
r.to.vect input=basin_mouth2_000001 output=basin_mouth2_000001 type=area --overwrite
g.remove -f type=raster name=basin_mouth2_000001 --quiet
v.clean input=basin_mouth2_000001 output=basin_mouth2_000001c type=area tool=prune,rmdupl,rmbridge,rmline,rmdangle thresh=0,0,0,0,-1 --overwrite
v.db.addcolumn map=basin_mouth2_000001c columns="x_mouth DOUBLE PRECISION"
v.db.addcolumn map=basin_mouth2_000001c columns="y_mouth DOUBLE PRECISION"
v.db.update map=basin_mouth2_000001c column=x_mouth value=-7928554.691232
v.db.update map=basin_mouth2_000001c column=y_mouth  value=1295538.184247
v.db.addcolumn map=basin_mouth2_000001c columns="mouth_id INT"
v.db.addcolumn map=basin_mouth2_000001c columns="basin_id INT"
v.db.update map=basin_mouth2_000001c column=mouth_id  value=1
v.db.update map=basin_mouth2_000001c column=basin_id  value=1
v.to.db map=basin_mouth2_000001c type=centroid option=area columns=area_km2 units=kilometers
v.out.ogr input=basin_mouth2_000001c type=area format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazoniax/0/basin_mouth2_000001c.shp --overwrite

As there can be thousands of outlet points the processing of the entire shell script might take a long time. But progress is reported int he Terminal window, indicating the number of the outlet under process. And as the outlets are sequential numbers you can always find out how far the processing has gone.

Assembling basin polygons to a single shape file

Looking at each polygon vector representing a river basin individually is not doable. To collect all the produced polygons into a single shape file, the Python package in part 2 produced another shell script, “region”_ogr2ogr_basin_mouth2.sh. This script requires that you have installed GDAL (see Installation & Setup). The command ogr2ogr is the vector processing tool of GDAL. The script simply assembles all the polygons into single vector file. In the first line, the first polygon is simply copied to a new file, all remaining commands then append data to the first file.

ogr2ogr -skipfailures -nlt MULTIPOLYGON /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-mouth2-outlet-area_drainage_amazonia_0_cgiar-250.shp /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazoniax/0/basin_mouth2_000001c.shp
ogr2ogr  -append -skipfailures -nlt MULTIPOLYGON /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-mouth2-outlet-area_drainage_amazonia_0_cgiar-250.shp /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazoniax/0/basin_mouth2_000002c.shp
ogr2ogr  -append -skipfailures -nlt MULTIPOLYGON /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-mouth2-outlet-area_drainage_amazonia_0_cgiar-250.shp /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazoniax/0/basin_mouth2_000003c.shp

the script will only take a few minutes, and then you should have a new ESRI shape file with all the delineated basins.

Inspect

Basin delineation: 3 Python distilling

2020-10-27T00:00:00+00:00

Introduction

Part 3 of the tutorial series on Basin delineation covers a custom written Python package, basin_extract. The outcome of the package is a vector map with distilled outlet point, and two shell scripts. One for GRASS to actually delineate all the preliminary basins, and one for GDAL to assemble all basins into one data source (polygon vector file). The scripts are then used in part 4.

Prerequisites

You must have setup GRASS 7 and imported a DEM as described in Installation & Setup of this blog. And then you must have completed the GRASS watershed processing as outlined in part 2.

Python processing

If you followed the Installation & Setup and part 2 of this series, you should have candidate basin outlets available as vector point files in shape format. You can use QGIS (or another GIS software) to inspect the data source.

The aim of this part of the basin delineation is threefold:

to identify outlet points to include for generating preliminary basins,
to retain only a single outlet point per separate mouth - including one point per mouth for rivers (basins) that have multiple mouths (like e.g. a river delta),
to generate the GRASS command line code for basin delineation.

For these tasks I have created a Python script called basin_extractor available through GitHub. This script will also be used in part 5 to join basins that belong to the same river and remove all basins that do no fall completely within the map region (as their complete basins are not represented in the map).

Default distillation method

Having experimented with different alternatives for creating a set of preliminary basins, the most resilient method is to create a virtual DEM directing flow out of the basin mouths towards a single outlet point (raster cell). Upstream basin delineation is rather problem free, given that the DEM is correct. As pointed out in part 2 it is the flow in wide channels and at outlets that cause problems. In particular if the basins are to be used for estimating water balances of entire basins (i.e. at the basin outflows).

The default method thus entails the following:

Candidate outlets defined from MFD and SFD combined,
virtual coastline walls enclosing the basin mouths,
a single cell punched hole in each wall for directing basin outflow,
changing outlet point from the “real” position to the punched hole,
virtually tilting basin mouths towards the punched hole.

This ensures that all basins above the user defined threshold size are identified. And that flow out of each river mouth of all identified basins is through a single cell (per mouth if the outlet is a delta with multiple mouths) and can be exactly accounted for.

There are, however, other alternatives relying on using either the SFD or the MFD generated outlets. For some cases it might be necessary to separate or complementing basins, and then you might need to use the alternatives outlined below.

Alternative basin distillations

There are 5 basic alternatives for how to start the distilling of your candidate basin outlet points:

Use the combined SFD-MFD (‘MOUTH’) default system with a virtual coastline wall,
Use all SFD identified outlets for generating preliminary basins,
Cluster SFD outlets based on adjacent MFD candidate outlets and distill to a single SFD outlet per cluster,
Use all MFD identified outlets for generating preliminary basins,
Cluster adjacent MFD outlets based on the MFD candidate outlets and distill to a single outlet per cluster.

Parameterisation

The Python script basin_extractor is parameterised from an XML file that follows the general structure of Karttur´s GeoImagine Framework:

<basindelineate>
	<userproj userid = 'karttur' projectid = 'karttur' tractid= 'amazonia' siteid = '*' plotid = '*' system = 'MODIS'></userproj>

	<!-- Define processing -->
	<process processid ='BasinDelineate'>
		<overwrite>Y</overwrite> # Y(es) or N(o)
		<delete>N</delete> # Y(es) or N(o)
		<parameters
		stage = '1' # 1, 2 or 3
		adjacentdist = '330' # any number in map distance units
		outlet = 'SFD' # MOUTH, SFD or MFD
		distill = '' # MFD or None (nothing)
		clusteroutlet = 'central' # central or max
		basinthreshold='2000' # any number is cells
		watershed='MFD5' # SFD, MFD or MFD? (? in range 1..10)
		verbose = '1' # 0, 1 or 2
		proj4CRS = '+proj=sinu +lon_0=0 +x_0=0 +y_0=0 +a=6371007.181 +b=6371007.181 +units=m +no_defs'
		>

		</parameters>
		<srcpath volume = "GRASS2020"></srcpath>
		<dstpath volume = "GRASS2020"></dstpath>

		<srccomp>
			<!-- the name <tag> and prefix must be the same and can not be altered. The script looks for which source data is included and compares that with the parameters, and then sets the processing method if these corresponds. Otherwise the script ends with an error message.
			-->
			<basin-mouth-outlet-pt source = "SRTM" product = "drainage" folder = "basin" band = "basin-mouth-outlet-pt" prefix = "basin-mouth-outlet-pt" suffix = "cgiar-250">
			</basin-mouth-outlet-pt>

			<basin-MFD-outlet-pt source = "SRTM" product = "drainage" folder = "basin" band = "basin-MFD-outlet-pt" prefix = "basin-MFD-outlet-pt" suffix = "cgiar-250">
			</basin-MFD-outlet-pt>

			<basin-SFD-outlet-pt source = "SRTM" product = "drainage" folder = "basin" band = "basin-SFD-outlet-pt" prefix = "basin-SFD-outlet-pt" suffix = "cgiar-250">
			</basin-SFD-outlet-pt>

			<shorewall-pt source = "SRTM" product = "drainage" folder = "basin" band = "shorewall-pt" prefix = "shorewall-pt" suffix = "cgiar-250">
			</shorewall-pt>
		</srccomp>

		<dstcomp>
			<basin-outlet>
			</basin-outlet>
			<!--
			To force a non-default destination path and name, you can enter all components explicitly, e.g.
			<basin-outlet band = "basin-mfd+mfd-max" prefix = "basin-mfd+mfd-max">
			</basin-outlet>
			-->
		</dstcomp>
	</process>

</basindelineate>

The core parameters include:

stage [1, 2 or 3] (this part is for stage = ‘1’)
adjacentdist [the maximum distance in map units used for clustering candidate outlet points] (only relevant if parameter distill=’MFD’)
outlet [‘SFD’, ‘MFD’ or ‘MOUTH’]
distill [‘MFD’ or ‘None’]
clusteroutlet [‘central’ or ‘maximum’]
basinthreshold [r.watershed parameter threshold, default= 2000]
watershed [flow direction setting for iterated run of r.watershed, only relevant if parameter distill=’MOUTH’]
verbose [0, 1 or 2]
proj4CRS [‘proj4CRS definition for output data if input layers lack proper projection information’]

MOUTH processing

outlet=’MOUTH’
distill is ignored
adjacentdist is ignored
watershed must be set

The following srccomp tags must be set:

basin-mouth-outlet-pt
shorewall-pt

The MOUTH processing is the most complex, but also generates the most consistent result. The processing includes the following steps:

identify one candidate outlet point per river mouth (either central or with maximum upstream as determined by the clusteroutlet parameter)
move candidate outlet point to the nearest cell in the shorewall
Create GRASS shell script for repeating the r.watershed analysis with the new outlet point and a hydrologically corrected DEM draining towards this point.

The ensuing processing (in part 4) thus includes creating a new, hydrologically adjusted virtual DEM and then redoing the r.watershed analysis.

If you want to run the MOUTH alternative for other data source (ie. for and SFD analysis), you do that by renaming the SFD shape file to the MOUTH equivalent.

Non-clustered SFD processing

outlet=’SFD’
distill=’None’
adjacentdist is ignored
watershed is ignored

The following srccomp tags must be set:

basin-SFD-outlet-pt

This is the simplest delineation method. It just takes all SFD outlets and delineates basins from these.

Clustered SFD processing

outlet=’SFD’
distill=’MFD’
adjacentdist must be set
watershed is ignored

The following srccomp tags must be set:

basin-SFD-outlet-pt
basin-MFD-outlet-pt

With this method, all MFD outlets are clustered and any if two or more SFD outlets are found within the same cluster, only one is retained. Which one to retain is determined by the parameter clusteroutlet. The parameter adjacentdist determines the maximum distance between points for belonging to the same cluster.

Non-clustered MFD processing

outlet=’MFD’
distill=’None’
adjacentdist is ignored
watershed is ignored

The following srccomp tags must be set:

basin-MFD-outlet-pt

With these parameter setting, basin_extract delineates basins from all MFD candidates.

Clustered MFD processing

outlet=’MFD’
distill=’MFD’
adjacentdist must be set
watershed is ignored

The following srccomp tags must be set:

basin-MFD-outlet-pt

With both outlet and distill parameters set to MFD, the MFD outlet candidates are first clustered. Within each cluster only one MFD outlet is retained. Which one to retain is determined by the parameter clusteroutlet. The parameter adjacentdist determines the maximum distance between points for belonging to the same cluster.

Editing the data source

The processing is determined by the default naming convention of the source data sets. But you can manually edit any of the source data prior to processing. If you only want to process a few of the candidates, simply delete all other candidates. You can for instance use QGIS to open the point vector file (in ESRI shape format), change to edit mode and delete the candidates you are not interested in. Then run basin_extract as usual.

You can also change the name of, say an SFD generated point vector file and change to the default MOUTH name, and then run the MOUTH analysis instead of the SFD analysis.

Output

The script basin_extractor will produce a point vector file in shape format containing the distilled outlet candidates points as requested in the parameterization. Alongside the point vector file, the script also produces a shell script (.sh) with the GRASS commands for delineating the basins from the selected candidate points. The name of the shell script file is defaulted to reflect which of the four main alternatives the parameterisation was set to.

Python script output

The main output of stage 1 of the Python script basin_extract is a GRASS command line script. Part 4 of this tutorial series will take you through he processing in that script.

Basin delineation: 2 GRASS watershed analysis

2020-10-26T00:00:00+00:00

Introduction

Part 2 of the Basin delineation tutorial series focuses on using GRASS7 for creating the initial watershed (or basin) files representing hydrological flow direction and upstream accumulation of each cell in the study region.

Prerequisites

You must have setup GRASS 7 and imported a DEM as described under Installation & Setup in this blog.

Watershed accumulation and basin area

The GRASS raster command r.watershed calculates a variety of hydrological parameters, including the upstream (accumulation) area and the drainage direction of each cell. Note that the accumulation area is calculated as number of cells.

r.watershed can be run assigning a Single Flow Direction (SFD) out of each cell, or Multiple Flow Directions (MFD). MFD is in general preferred and also the default. MFD can be parameterised for determining the flow convergence/divergence, with the recommended default being an average (parameter convergence=5). If you want to avoid negative numbers for upstream area, set the -a flag. r.watershed can be set up to produce a range of hydrologically related layers. For delineating basins you must produce layers for accumulation and drainage.

Single Flow Direction

To apply an SFD flow routing, set the flag -s. In the example below I have set both the -a and -s flags, and I have requested the production of layers for accumulation and drainage. I have set the cutoff threshold at 2000 cells:

With the original DEM (in the mapset PERMANENT):

> r.watershed -as elevation=DEM@PERMANENT accumulation=SFD_upstream drainage=SFD_drainage threshold=2000 –overwrite

With a patched up DEM from part 1:

> r.watershed -as elevation=hydroptfill_DEM accumulation=SFD_upstream drainage=SFD_drainage threshold=2000 –overwrite

It takes a rather long time to run an r.watershed analysis. GRASS thus offers a faster alternative, r.terraflow for massive grids. r.terraflow, however, produces less accurate results and I strongly recommend against using it.

Multiple Flow Directions (MFD)

Omitting the -s flag causes r.watershed to run in default mode, applying an MFD flow routing.

With the original DEM (in the mapset PERMANENT):

> r.watershed -a elevation=DEM@PERMANENT accumulation=MFD_upstream drainage=MFD_drainage threshold=2000 –overwrite

With a patched up DEM from part 1:

> r.watershed -a elevation=hydroptfill_DEM accumulation=MFD_upstream drainage=MFD_drainage threshold=2000 –overwrite

MFD alternative parameterizations

If you want to better capture the full width of wide rivers, you should set a smaller convergence factor for MFD:

> r.watershed -a convergence=1 elevation=DEM@PERMANENT accumulation=MFD01_upstream drainage=MFD01_drainage threshold=2000 –overwrite

Alternatively you can try to beautify flat areas (including wide channels) by setting the -b flag.

> r.watershed -ab convergence=1 elevation=DEM@PERMANENT accumulation=MFDab_upstream drainage=MFDab_drainage threshold=2000 –overwrite

Or even combine a maximum divergence and beautification of flat areas:

> r.watershed -ab convergence=1 elevation=DEM@PERMANENT accumulation=MFDab01_upstream drainage=MFDab01_drainage threshold=2000 –overwrite

Compare upstream accumulation

If you look at the accumulation layer, the major Rivers (e.g. the Amazon River) should have the largest accumulation values.

Upstream area calculated using (clockwise) Single Flow Direction (SFD), Multi Flow Direction (MFD) with convergence=5 (default), MFD with convergence=1 and MFD with convergence=1 and -b (beautify flat area) flag.

After having compared the result of different Flow Direction parameterisations, I decided to stick with the default settings. In the remaining part of this tutorial series I will rely on default outputs from both SFD and MFD. The reason for using both MFD and SFD is that I want to find all mouths of bifurcating rivers (with MFD) but also all basins that are larger than my set threshhold (regardless of the number of cells though which the basin empties itself in the terminal drainage).

Export upstream layers

You will need the raster layers showing the upstream accumulated areas for inspecting further processing. The upstream layer, however, contains very high numbers and is difficult to visualise. Thus it is better to first get the natural logarithm of the dataset and then export it in byte format. Apply the logarithmic conversion, including a multiplication with 10, with the GRASS command r.mapcalc. Set a colour ramp that is intuitive for interpreting water flow with the command r.colors. I choose red-yellow-blue (ryb). Then export the raster layer with the command r.out.gdal. That is how the 4 maps in the figure above were symbolised.

Start by creating the target directory:

> mkdir -p /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0

Export SFD

The combined commands for exporting a nicely symbolised SFD accumulation layer:

> r.mapcalc "SFD_ln_upstream = 10*log(SFD_upstream)" –overwrite

> r.colors map=SFD_ln_upstream color=ryb

> r.out.gdal -f input=SFD_ln_upstream format=GTiff type=Byte output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/upstream-ln-ryb-SFD_amazonia_0_cgiar-250.tif –overwrite

Export MFD

The combined commands for exporting a nicely symbolised MFD accumulation layer:

> r.mapcalc "MFD_ln_upstream = 10*log(MFD_upstream)" –overwrite

> r.colors map=MFD_ln_upstream color=ryb

> r.out.gdal -f input=MFD_ln_upstream format=GTiff type=Byte output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/upstream-ln-ryb-MFD_amazonia_0_cgiar-250.tif –overwrite

Identify terminal water body

Use r.mapcalc to create a layer where the terminal water body, into which the basins you want to delineate, drain. This is equal to setting all land areas (cells in your DEM layer with valid data) to NULL, and your terminal water body (e.g. the areas assigned with NULL in the DEM) to a value of 1.

With the original DEM (in the mapset PERMANENT):

> r.mapcalc "drain_terminal = if(isnull(‘DEM@PERMANENT’), 1, null())"

With a patched up DEM from part 1:

> r.mapcalc "drain_terminal = if(isnull(‘hydroptfill_DEM’), 1, null())"

Get shoreline

With the terminal water body identified, the shoreline with all the basin outlets will all be found in the neighbouring cells of the water body. In GRASS you can use the proximity analysis tool r.buffer to identify the shoreline from the terminal water body. To capture all shoreline cells set the distance to the length of the side of one cell * sqrt of 2 + plus a little extra. The spatial resolution of the DEM used in this example is 231.6 m. I thus set the distance threshold for the proximity analysis to 330 m.

> r.buffer input=drain_terminal output=shoreline distances=330 units=meters –overwrite

Extract accumulated drainage for shoreline

With both the shoreline and the flow accumulation identified on a per pixel level, you can once again apply r.mapcalc, but this time to mask out the layer with the accumulated upstream area to only include the shoreline (i.e. the potential basin outlets).

> r.mapcalc "shoreline_SFD_flowacc = if((shoreline > 1), SFD_upstream, null())"

> r.mapcalc "shoreline_MFD_flowacc = if((shoreline > 1), MFD_upstream, null())"

Threshold minimum drainage area

The map of the upstream (accumulated) cells masked to show only the shoreline contains the upstream area of every cell along the shoreline, regardless of the upstream area. But you only want the river basins, not the cells that empty directly into the terminal water body or via insignificant water courses. You need to r.reclass the raster layer showing the upstream area of the shoreline to retain only the cells above a given threshold. Remember that the accumulated upstream drainage is given in cells.

r.reclass can be parameterized in different ways, but to keep a memory of the processing it is best to do via a simple text file that is linked in the command. To retain all basins composed to 2000 cells or more, the file looks like this:

2000 thru 99999999 = 1
* = NULL

As the map has a spatial resolution of 231.6 m, 2000 cells equals approximately 100 (107 to be exact) square kilometres. Then run r.reclass with the text file used for parameterisation.

> r.reclass input=shoreline_SFD_flowacc output=basin_SFD_outlets rules=’/Volumes/GRASS2020/GRASSsupport/reclass/reclass_flow_acc_2000.txt’ –overwrite

> r.reclass input=shoreline_MFD_flowacc output=basin_MFD_outlets rules=’/Volumes/GRASS2020/GRASSsupport/reclass/reclass_flow_acc_2000.txt’ –overwrite

Combine the two basin outlet rasters

Distilling the candidate basin outlets to a final set is rather complex - in essence the remaining of parts 2, and parts 3 and 4 are required to get there. To capture all outlets of all basins, the MFD and SFD results need to be joined. Easiest done using r.mapcalc. Alternatively you can patch the vectorised outlets (shown further down) using v.patch.

> r.mapcalc "shoreline_flowacc = if ((shoreline_SFD_flowacc > shoreline_MFD_flowacc), shoreline_SFD_flowacc, shoreline_MFD_flowacc)" –overwrite

> r.reclass input=shoreline_flowacc output=basin_outlets rules=’/Volumes/GRASS2020/GRASSsupport/reclass/reclass_flow_acc_2000.txt’ –overwrite

Vectorize basin outlet candidates

You should now have raster layers with candidate basin outlets. These points are required for the further processing and you need to convert them to vector points. The default suggested processing chain in this tutorial will, however, use the combined SFD and MFD outlets and not the SFD and MFD points. But you can go ahead and convert the latter to vectors anyway. In GRASS you convert raster cells to vector points with the command r.to.vect.

> r.to.vect input=basin_outlets output=basin_outlet_pt type=point –overwrite

> r.to.vect input=basin_SFD_outlets output=basin_SFD_outlet_pt type=point –overwrite

> r.to.vect input=basin_MFD_outlets output=basin_MFD_outlet_pt type=point –overwrite

As mentioned above, you can use v.patch to join the SFD and MFD outlet points. But if you followed the suggested path above you already have a vector layer called basin_outlet_pt.

> v.patch input = basin_SFD_outlet_pt, basin_MFD_outlet_pt output = basin_outlet_pt

Upstream area and identified candidate basin outlets using Single Flow Direction (SFD) and Multi Flow Direction (MFD). The wider spread of the accumulated flow with MFD (right) causes the wide river mouths to show up. The accumulated flow with SFD forces flow to a channel with a width of only 1 cell - and is not really seen in the map at the presented scale. If you click in one of the maps you will get popups with mire details.

From point outlets to river mouths

From the illustrations above six different problems are evident:

The MFD analysis identifies multiple adjacent outlet points along wide river mouths of larger basins,
The MFD analysis only captures basins where the outflow over any single cell is above the threshold, regardless of the size of the basin,
The SFD analysis does not capture all outlet branches of large rivers that form multiple outlet channels (e.g. in river deltas),
Separate outlets belonging to the same river (as in 3 above), are not identified as being part of the same basin,
Both MFD, but in particular SFD, might identify multiple outlet points (or clusters of outlet points regarding MFD) in wide outlet mouths.
The flow path across flat surfaces differs greatly dependent on the parameterisation of r.watershed.

Problem 1 can be solved by clustering adjacent outlet points, problems 2 and 3 by joining MFD and SFD results. Problem 4 requires analysing the connectivity between adjacent and upstream connected, but along the shoreline topographically separated, river mouths. Problem 5 requires that the complete width of each separate mouth (regardless if part of a delta or not) be identified as a united entity. Issue 6 is only a problem if the identified basins are used for hydrological balancing or modeling (dealt with in parts 3 and 4 of this series).

These problems need to be addressed by combining spatial and database analysis. The solution that I chose accomplishes this by using GRASS and Python scripting. The next section in this part deals with the GRASS spatial analysis for identifying contiguous basin mouths. The Python scripting is the topic of part 3.

Identify contiguous basin mouths

Excluding the sea surface, you could simply reclass the DEM to only retain cells with an elevation of zero for identifying basin mouths. You will then, however, end up with cells along the shoreline that do not constitute a river mouth as well as landlocked regions at sea level. And then there are errors in the DEM and not all basin mouths have an elevation equal 0 (that will be fixed in parts 3 and 4). Instead you need to find all cells at sea level connected to at least one of your candidate outlet points. With the connection either being along the shoreline or via upstream bifurcations. The latter for finding rivers with multiple mouths, like in e.g. river deltas.

Cost growth analysis

Cost growth analysis calculates the accumulated travel cost over a friction surface from predefined starting points. You can use the GRASS cost grow tool r.cost as the first step for finding both the hydrological connectivity between adjacent river mouths and the complete width of the mouths of larger rivers. You have to use all outlet points (from MFD and SFD combined) as starting points and the DEM as a friction surface. Friction at sea surface level (DEM =0) will then be 0, and you let the cost grow analysis travel as long as it is frictionless, i.e. across all of the river mouths.

Identify basin river mouths

If you use the entire DEM for the cost grow analaysis, the result will connect all mouth cells (at sea level), even if not directly connected along the coast. Mouths across a a river delta will be linked (as long as the DEM shows that the water levels equals 0). The r.cost analysis for an entire basin can, however, take a rather long time.

To speed up the processing, you can r.mapcalc the input DEM to only include lower elevations and set higher elevations to NULL. To avoid problems with negative DEM values you can also set these to 0.

With the original DEM (in the mapset PERMANENT):

> r.mapcalc "lowlevel_DEM = if((DEM@PERMANENT <= 0), 0, null())"

With a patched up DEM from part 1:

> r.mapcalc "lowlevel_DEM = if((hydroptfill_DEM <= 0), 0, null())"

If you want to expand the connectivity you can set the “0” of lowlevel_DEM to include also positive elevation (e.g. > r.mapcalc "lowlevel_DEM = if((DEM@PERMANENT <= 2), 0, null())").

Then run r.cost on the more limited DEM. The -n flag retains the null values in the output layer.

> r.cost -n input=lowlevel_DEM output=lowlevel_outlet_costgrow start_points=basin_outlet_pt max_cost=0 –overwrite

To cluster the cells constituting basin mouths use the GRASS command r.clump. Each separate cluster will be assigned a unique id, and you can use that id for identifying river mouths that are separated at the shoreline but joined upstream. Set the -d flag to clump diagonal cells, and then export the raster data source as you will need it to inspect your basins in later parts.

> r.clump -d input=lowlevel_outlet_costgrow output=lowlevel_outlet_clumps –overwrite

> r.out.gdal -f input=lowlevel_outlet_clumps format=GTiff output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/lowlevel-outlet-clumps_amazonia_0_cgiar-250.tif –overwrite

Identify beachfront river mouths

To calculate cost growth for only the shoreline, apply r.mapcalc to extract the DEM only for the shoreline.

With the original DEM (in the mapset PERMANENT):

> r.mapcalc “shoreline_DEM = if((shoreline > 1 && DEM@PERMANENT <= 0), 0, null())” –overwrite

With a patched up DEM from part 1:

> r.mapcalc "shoreline_DEM = if((shoreline > 1 && hydroptfill_DEM <= 0), 0, null())" –overwrite

Then repeat the processing steps for identifying the basin mouths, but for the beachfront mouths.

> r.cost -n input=shoreline_DEM output=shoreline_outlet_costgrow start_points=basin_outlet_pt max_cost=0 –overwrite

> r.clump -d input=shoreline_outlet_costgrow output=shoreline_outlet_clumps –overwrite

> r.out.gdal -f input=shoreline_outlet_clumps format=GTiff output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/shoreline-outlet-clumps_amazonia_0_cgiar-250.tif –overwrite

If you compare the number of clumps reported (at the GRASS commandline), there should be more clumps produced for the shoreline compared to the basin (lowlevel). For the Amazonia region used in the example there are 1065 shoreline clumps and 1037 basin clumps. The difference, 28 mouths, belong to rivers that have two or more separate mouths at the shoreline.

Vectorize beachfront mouths

You should now have clumps of rasters with unique id’s for each separate beachfront mouth. What you ultimately need is a single point in each clump. That is because you want to let all the water from your basin to flow out of that particular cell and none other. To achieve this you need to prepare point data sources in GRASS, and then analyse these in Python.

Vectorize the beachfront mouths with the command r.to.vect.

> r.to.vect input=shoreline_outlet_clumps output=basin_mouth_outlet_pt type=point

Add columns to vector databases

For the database processing in Python, you need to add several columns and fill them with data. You only need to add columns and data to the outlet or mouth vector(s) to use in the next step. The default is to use the basin_mouths_pt point vector. But for convenience the processing of the SFD and MFD point vectors are also included.

Use GRASS vector command v.db.addcolumn to add columns to the vector attribute tables.

> v.db.addcolumn map=basin_mouth_outlet_pt columns=’upstream DOUBLE PRECISION’

> v.db.addcolumn map=basin_mouth_outlet_pt columns=’elevation INT’

> v.db.addcolumn map=basin_mouth_outlet_pt columns=’mouth_id INT’

> v.db.addcolumn map=basin_mouth_outlet_pt columns=’basin_id INT’

or with multiple columns added in one command:

> v.db.addcolumn map=basin_SFD_outlet_pt columns=’upstream DOUBLE PRECISION, elevation INT, mouth_id INT, basin_id INT’

> v.db.addcolumn map=basin_MFD_outlet_pt columns=’upstream DOUBLE PRECISION, elevation INT, mouth_id INT, basin_id INT’

Add basin data to vector databases

To transfer the cell data underlying each point to the vector attribute table, use the GRASS vector command v.what.rast.

> v.what.rast map=basin_mouth_outlet_pt raster=SFD_upstream column=upstream

> v.what.rast map=basin_mouth_outlet_pt raster=DEM@PERMANENT column=elevation

> v.what.rast map=basin_mouth_outlet_pt raster=hydroptfill_DEM column=elevation

> v.what.rast map=basin_mouth_outlet_pt raster=shoreline_outlet_clumps column=mouth_id

> v.what.rast map=basin_mouth_outlet_pt raster=lowlevel_outlet_clumps column=basin_id

> v.what.rast map=basin_SFD_outlet_pt raster=SFD_upstream column=upstream

> v.what.rast map=basin_SFD_outlet_pt raster=DEM@PERMANENT column=elevation

> v.what.rast map=basin_SFD_outlet_pt raster=hydroptfill_DEM column=elevation

> v.what.rast map=basin_SFD_outlet_pt raster=shoreline_outlet_clumps column=mouth_id

> v.what.rast map=basin_SFD_outlet_pt raster=lowlevel_outlet_clumps column=basin_id

> v.what.rast map=basin_MFD_outlet_pt raster=MFD_upstream column=upstream

> v.what.rast map=basin_MFD_outlet_pt raster=DEM@PERMANENT column=elevation

> v.what.rast map=basin_MFD_outlet_pt raster=hydroptfill_DEM column=elevation

> v.what.rast map=basin_MFD_outlet_pt raster=shoreline_outlet_clumps column=mouth_id

> v.what.rast map=basin_MFD_outlet_pt raster=lowlevel_outlet_clumps column=basin_id

Upload the x and y coordinates to the vector db

Some inherent vector properties can be added to the vector database without prior definition of the column. The command v.to.db creates the column(s) on the fly, for instance for adding point coordinates:

> v.to.db map=basin_mouth_outlet_pt option=coor columns=xcoord,ycoord

> v.to.db map=basin_SFD_outlet_pt option=coor columns=xcoord,ycoord

> v.to.db map=basin_MFD_outlet_pt option=coor columns=xcoord,ycoord

Export basin outlet candidates

Distillation of basin outlets from the candidates is done using a Python script and requires shape files as input. Export the outlet candidates with v.out.ogr.

> v.out.ogr type=point input=basin_mouth_outlet_pt format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-mouth-outlet-pt_drainage_amazonia_0_cgiar-250.shp –overwrite

> v.out.ogr type=point input=basin_SFD_outlet_pt format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-SFD-outlet-pt_drainage_amazonia_0_cgiar-250.shp –overwrite

> v.out.ogr type=point input=basin_MFD_outlet_pt format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-MFD-outlet-pt_drainage_amazonia_0_cgiar-250.shp –overwrite

Virtual direction of basin outflow

The r.watershed analysis is balancing the accumulated input and output through each cell. The results from r.watershed can thus be used for calculating hydrological balances for every cell in a watershed. In wide rivers, including the wide mouths we have dealt with above, the total flow across a section is difficult to retrieve. Also because it depends on the flow direction algorithm. To get the accurate flow along a river, ideally you need a single cell across which all water in the river is forced to pass. To estimate the total outflow of a basin that has a mouth wider than a single cell thus requires a special solution. This section demonstrates how to create a virtual wall across the basin mouth. In the next part a virtual hole will be punched in the wall forcing all flow though a single cell.

Build a virtual wall across the basin mouth

The virtual wall is built by buffering the identified shoreline mouths (shoreline_outlet_clumps) associated with river basins.

Apply an r.buffer analysis the width of 1 diagonal cell (330 m as caclualted above) and starting from the outlet mouths:

> r.buffer input=shoreline_outlet_clumps output=mouth_buffer distances=330 units=meters –overwrite

Overlay the buffer with the map of the terminal drainage, and only retain the buffer cells that fall in the terminal drainage (i.e. on the seaside of the shoreline):

> r.mapcalc "shorewall = if((drain_terminal == 1 && mouth_buffer > 1), 1, null())" –overwrite

Convert the shoreline to vectors - this is the data source you need for the Python processing in the next part.

> r.to.vect input=shorewall output=shorewall_pt type=point

Export the shorewall

Export the point vector version of the shorewall to an ESRI shape file.

> v.out.ogr type=point input=shorewall_pt format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/shorewall-pt_drainage_amazonia_0_cgiar-250.shp –overwrite

Optionally export the shorewall raster map as a geotiff to inspect it in e.g. QGIS.

> r.out.gdal -f format=GTiff type=Byte input=shorewall output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/shorewall_amazonia_0_cgiar-250.tif –overwrite

GRASS shell script

The complete GRASS processing chain in this post (after importing the DEM and creating a new mapset covered in part 1, can be run as a shell script. The shell script omits the trial of different MFD parameterisations discussed above.

# Basin delineation: GRASS watershed analysis

# Watershed accumulation and basin area

r.watershed -as elevation=DEM@PERMANENT accumulation=SFD_upstream drainage=SFD_drainage threshold=2000 --overwrite

# r.watershed -as elevation=hydroptfill_DEM accumulation=SFD_upstream drainage=SFD_drainage threshold=2000 --overwrite

r.watershed -a elevation=DEM@PERMANENT accumulation=MFD_upstream drainage=MFD_drainage threshold=2000 --overwrite

#r.watershed -a elevation=hydroptfill_DEM accumulation=MFD_upstream drainage=MFD_drainage threshold=2000 --overwrite

# Export upstream layers

mkdir -p /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0

r.mapcalc "SFD_ln_upstream = 10*log(SFD_upstream)" --overwrite

r.colors map=SFD_ln_upstream color=ryb

r.out.gdal -f input=SFD_ln_upstream format=GTiff type=Byte output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/upstream-ln-ryb-SFD_amazonia_0_cgiar-250.tif --overwrite

r.mapcalc "MFD_ln_upstream = 10*log(MFD_upstream)" --overwrite

r.colors map=MFD_ln_upstream color=ryb

r.out.gdal -f input=MFD_ln_upstream format=GTiff type=Byte output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/upstream-ln-ryb-MFD_amazonia_0_cgiar-250.tif --overwrite

# Identify terminal water body

r.mapcalc "drain_terminal = if(isnull('DEM@PERMANENT'), 1, null())"

#r.mapcalc "drain_terminal = if(isnull('hydroptfill_DEM'), 1, null())"

# Get shoreline

r.buffer input=drain_terminal output=shoreline distances=330 units=meters --overwrite

# Extract accumulated drainage for shoreline

r.mapcalc "shoreline_SFD_flowacc = if((shoreline > 1), SFD_upstream, null())"

r.mapcalc "shoreline_MFD_flowacc = if((shoreline > 1), MFD_upstream, null())"

# Threshold minimum drainage area

# Create reclass parameterization file
### 2000 thru 99999999 = 1 ###
### * = NULL ###

r.reclass input=shoreline_SFD_flowacc output=basin_SFD_outlets rules='/Volumes/GRASS2020/GRASSsupport/reclass/reclass_flow_acc_2000.txt' --overwrite

r.reclass input=shoreline_MFD_flowacc output=basin_MFD_outlets rules='/Volumes/GRASS2020/GRASSsupport/reclass/reclass_flow_acc_2000.txt' --overwrite

# Combine the two basin outlet rasters

r.mapcalc "shoreline_flowacc = if ((shoreline_SFD_flowacc > shoreline_MFD_flowacc), shoreline_SFD_flowacc, shoreline_MFD_flowacc)" --overwrite

r.reclass input=shoreline_flowacc output=basin_shoreline_outlets rules='/Volumes/GRASS2020/GRASSsupport/reclass/reclass_flow_acc_2000.txt' --overwrite

# Vectorize basin shoreline outlet candidates

r.to.vect input=basin_shoreline_outlets output=basin_outlet_pt type=point --overwrite

r.to.vect input=basin_SFD_outlets output=basin_SFD_outlet_pt type=point  --overwrite

r.to.vect input=basin_MFD_outlets output=basin_MFD_outlet_pt type=point --overwrite

# Identify basin river mouths

### You can change the if conditions to include a wider range of values (e.g. 1 or 2).

r.mapcalc "lowlevel_DEM = if((DEM@PERMANENT <= 0), 0, null())"

#r.mapcalc "lowlevel_DEM = if((hydroptfill_DEM <= 0), 0, null())"

r.cost -n input=lowlevel_DEM output=lowlevel_outlet_costgrow start_points=basin_outlet_pt max_cost=0 --overwrite

r.clump -d input=lowlevel_outlet_costgrow  output=lowlevel_outlet_clumps --overwrite

r.out.gdal -f input=lowlevel_outlet_clumps format=GTiff output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/lowlevel-outlet-clumps_amazonia_0_cgiar-250.tif --overwrite

# Identify beachfront river mouths

r.mapcalc "shoreline_DEM = if((shoreline > 1 && DEM@PERMANENT <= 0), 0, null())" --overwrite

#r.mapcalc "shoreline_DEM = if((shoreline > 1 && hydroptfill_DEM <= 0), 0, null())" --overwrite

r.cost -n input=shoreline_DEM output=shoreline_outlet_costgrow start_points=basin_outlet_pt max_cost=0 --overwrite

r.clump -d input=shoreline_outlet_costgrow output=shoreline_outlet_clumps --overwrite

r.out.gdal -f input=shoreline_outlet_clumps format=GTiff output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/shoreline-outlet-clumps_amazonia_0_cgiar-250.tif --overwrite

### From this point the separate SFD and MFD data sources are not needed for a combined solutions. The coding is however included for convenience. ###

# Vectorize shoreline mouths

r.to.vect input=shoreline_outlet_clumps output=basin_mouth_outlet_pt type=point

# Add columns to vector databases

v.db.addcolumn map=basin_mouth_outlet_pt columns='upstream DOUBLE PRECISION'

v.db.addcolumn map=basin_mouth_outlet_pt columns='elevation INT'

v.db.addcolumn map=basin_mouth_outlet_pt columns='mouth_id INT'

v.db.addcolumn map=basin_mouth_outlet_pt columns='basin_id INT'

# or with multiple columns added in one command

v.db.addcolumn map=basin_SFD_outlet_pt columns='upstream DOUBLE PRECISION, elevation INT, mouth_id INT, basin_id INT'

v.db.addcolumn map=basin_MFD_outlet_pt columns='upstream DOUBLE PRECISION, elevation INT, mouth_id INT, basin_id INT'

# Add basin data to vector databases

v.what.rast map=basin_mouth_outlet_pt raster=SFD_upstream column=upstream

v.what.rast map=basin_mouth_outlet_pt raster=DEM@PERMANENT column=elevation

#v.what.rast map=basin_mouth_outlet_pt raster=hydroptfill_DEM column=elevation

v.what.rast map=basin_mouth_outlet_pt raster=shoreline_outlet_clumps column=mouth_id

v.what.rast map=basin_mouth_outlet_pt raster=lowlevel_outlet_clumps column=basin_id

v.what.rast map=basin_SFD_outlet_pt raster=SFD_upstream column=upstream

v.what.rast map=basin_SFD_outlet_pt raster=DEM@PERMANENT column=elevation

#v.what.rast map=basin_SFD_outlet_pt raster=hydroptfill_DEM column=elevation

v.what.rast map=basin_SFD_outlet_pt raster=shoreline_outlet_clumps column=mouth_id

v.what.rast map=basin_SFD_outlet_pt raster=lowlevel_outlet_clumps column=basin_id

v.what.rast map=basin_MFD_outlet_pt raster=MFD_upstream column=upstream

v.what.rast map=basin_MFD_outlet_pt raster=DEM@PERMANENT column=elevation

#v.what.rast map=basin_MFD_outlet_pt raster=hydroptfill_DEM column=elevation

v.what.rast map=basin_MFD_outlet_pt raster=shoreline_outlet_clumps column=mouth_id

v.what.rast map=basin_MFD_outlet_pt raster=lowlevel_outlet_clumps column=basin_id

# Upload the x and y coordinates to the vector db

v.to.db map=basin_mouth_outlet_pt option=coor columns=xcoord,ycoord

v.to.db map=basin_SFD_outlet_pt option=coor columns=xcoord,ycoord

v.to.db map=basin_MFD_outlet_pt option=coor columns=xcoord,ycoord

# Export basin outlet candidates

v.out.ogr type=point input=basin_mouth_outlet_pt format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-mouth-outlet-pt_drainage_amazonia_0_cgiar-250.shp --overwrite

v.out.ogr type=point input=basin_SFD_outlet_pt format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-SFD-outlet-pt_drainage_amazonia_0_cgiar-250.shp --overwrite

v.out.ogr type=point input=basin_MFD_outlet_pt format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/basin-MFD-outlet-pt_drainage_amazonia_0_cgiar-250.shp --overwrite

# Build a virtual wall across the basin mouths

r.buffer input=shoreline_outlet_clumps output=mouth_buffer distances=330 units=meters --overwrite

r.mapcalc "thickwall = if((drain_terminal == 1 && mouth_buffer > 1), 1, null())" --overwrite

r.out.gdal -f format=GTiff type=Byte input=thickwall output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/thickwall_amazonia_0_cgiar-250.tif --overwrite

# Shrink the thickwall to 1 cell width

r.mapcalc "drain_terminal_remain = if((drain_terminal == 1),  if ((isnull(thickwall)),1, null() ),null() ) " --overwrite  

r.out.gdal -f format=GTiff type=Byte input=drain_terminal_remain output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/drain-terminal-remain_amazonia_0_cgiar-250.tif --overwrite

r.buffer input=drain_terminal_remain output=mouthshoreline distances=330 units=meters --overwrite

r.out.gdal -f format=GTiff type=Byte input=mouthshoreline output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/mouthshoreline_amazonia_0_cgiar-250.tif --overwrite

r.mapcalc "shorewall = if((mouthshoreline > 1 && thickwall == 1), 1, null())" --overwrite

r.out.gdal -f format=GTiff type=Byte input=shorewall output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/shorewall_amazonia_0_cgiar-250.tif --overwrite

r.to.vect input=shorewall output=shorewall_pt type=point --overwrite

v.out.ogr type=point input=shorewall_pt format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/shorewall-pt_drainage_amazonia_0_cgiar-250.shp --overwrite

r.out.gdal -f format=GTiff type=Byte input=shorewall output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/shorewall_amazonia_0_cgiar-250.tif --overwrite

# Fill up the original DEM with the holes created from the difference between thickwall and shorewall

r.mapcalc "fillholeDEM = if ((thickwall==1 && isnull(mouthwall)),1, null() ) " --overwrite

r.out.gdal format=GTiff type=Byte input=fillholeDEM output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/fillholeDEM_amazonia_0_cgiar-250.tif --overwrite

Next step

The next step requires in depth analysis of database records and spatial relations. I do not know how to accomplish that using standard GIS commands. The next step thus requires Python scripting.

Basin delineation: 1 patch up DEM

2020-10-24T00:00:00+00:00

Introduction

The basin delineation system outlined in this blog only requires a Digital Elevation Model (DEM) as input. The quality of the DEM is, however, critical. This first part of the series of instructions deals with hydrological correction of DEMs using GRASS GIS.

Prerequisites

You must have setup GRASS 7 and imported a DEM as described under Installation & Setup in this blog. The DEM must have null (“no data”) for the water body into which the basins to delineate drain.

DEM errors affecting basin delineation

Basin delineation is grounded in the fact that water tends to flow downhill (from a higher to a lower potential, but strictly that does not necessarily mean downhill). This routing of water across the hillside and within water courses is the key for connecting any geographic point in the landscape to an outlet point.

DEM issues that can cause problems for flow routing include:

regions lacking elevation data,
artificial pits,
artificial barriers,
flat regions,
wide river mouths.

Regions lacking data are generally difficult to mend. There are, however, special cases where it is necessary. In this tutorial you will mend small no data regions (a few cells) by first assigning a low elevation (typically 0) and then, optionally, apply a pit filling. It is crucial to remove land locked no data cells as these regions will otherwise gorge all the (virtual) water flow entering.

Artificial (virtual) pits are the most common problem, and most flow routing algorithms, including GRASS r.watershed can handle pits. For hydrological modeling it is often, but not always, better to mend artificial depressions. Also that will be done in the this manual.

Artificial barriers are more difficult to handle. And is not approached in this manual. You could, however, invert the DEM and solve problems with barriers as if they were pits.

Flat regions and wide river mouths cause similar flow routing problems. Different algorithms can be applied (i.e. Single flow Direction, or SFD, versus Multiple Flow Direction, MFD) for handling flat area. But a more ideal solution is to increase the vertical resolution and properly steer the routing using elevation data. This post includes a test of different flow directions algorithms, and in part 3 you will create an artificial slope directing outflow from wide river mouths.

Coastal DEM errors

Narrow bays, estuaries, lagoons etc. can cause problems in near shore regions. Both because they can come out as pits, but a worse problem is if such features become defined as land locked no data cells. That will cause problems both for identifying the basin outlets and later for modeling water flow out of the basin. To get rid of small “no data” regions along the coast you need to identify them and then assign an elevation that allows water to pass. The main objective of this post is to present a GRASS based scripting sequence that removes land locked no data holes in Digital Elevation Models.

GRASS preparations

There are several GRASS commands that can be used for mending and adjusting DEMs. The easiest is to use ordinary gap filling (r.fill.stats or r.fillnulls) but these methods do not consider the flow routing. Instead GRASS offers the r.fill.dir algorithm. r.fill.dir identifies pits along flow paths and then fills them. You can also use r.fill.dir for mending small no data holes, by first filling all the holes with a low elevation (typically DEM = 0).

The command r.flowfill is an alternative, available as an addon. To install GRASS addons you must have prepared the GRASS c-compiler as described in the post Install GDAL, QGIS and GRASS.

If you want to try r.flowfill , the command for installing it is:

> g.extension extension=r.fill.gaps

The rest of this manual however, uses r.fill.dir.

GRASS processing

The text sections below explains how to use GRASS for identifying and filling land locked no data regions. If you only want to run the process, all the commands are summarized further down.

Once you have filled the land locked no data holes you can use r.fill.dir fill them up with more realistic elevation values. Fur running the watershed analysis in parts 2 and 3, it is, however, enough to assign a low elevation (i.e. 0) to the no data holes. The GRASS process [r.watershed] manages pits on its own.

If you want to fill up pits in your DEM in a hydrologically sound manner then you should run r.fill.dir. For large grids that will, however, take a very (very) long time. For a DEM of 10 M pixels it can take 24 hours or longer. Thus you need to tile the DEM, with some overlap, before running r.fill.dir separately on each tile. To write such a command structure would also take a day. But with the help of the Python package basin_extract the GRASS commands will be setup in a second. Below both the principles for the pit filling, and how to use basin_extract, are covered. But first you need to remove the land locked no data regions.

Make the target directory

If you want to follow the standard of Karttur’s GeoImagine Framework, your target folder for the exported layers should be (where amazonia is the region used in this example):

> mkdir -p /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/stage0/script

Create a map of the terminal drainage

Create a map of the terminal drainage using the GRASS command r.mapcalc. For this to work, your original DEM (as described in the post on GRASS 7 setup ) must have the terminal drainage defined as “null” in the original DEM.

>r.mapcalc "drain_terminal = if(isnull('DEM@PERMANENT'), 1, null())"

Clump (r.clump) all contiguous cells together with a unique id to allow identifying large and small bodies representing the terminal drainage (null in the original DEM).

> r.clump input=drain_terminal output=terminal_clumps –overwrite

Convert the clumps to polygons with the command r.to.vect.

> r.to.vect input=terminal_clumps output=terminal_clumps type=area –overwrite

Add the area of each polygon to the the vector database with the command v.to.db.

> v.to.db map=terminal_clumps type=centroid option=area columns=area_km2 units=kilometers

Optionally export the vector with the polygons representing “no data” in the original DEM with v.out.ogr.

> v.out.ogr input=terminal_clumps type=area format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazoniax/0/terminal-clumps_SRTM_hydro-amazonia_0_cgiar-250.shp –overwrite

Fill in DEM over land

With the command v.to.rast it is possible to apply an SQL while converting vectors to a raster. Use that function to assign polygons below an area threshold to be the “no data” to fill, while polygons above the threshold should then represent the true terminal drainage. Set the pixel value to 0 - the preliminary elevation you will assign these cells. In the example I have set the threshold at 2.0 square kilometers. You should inspect the result and change the threshold if required.

> v.to.rast input=terminal_clumps type=area where="area_km2< 2.0" output=drain_terminal_small use=val value=0 –overwrite

> v.to.rast input=terminal_clumps type=area where="area_km2 >= 2.0" output=drain_terminal_large use=val value=0 –overwrite

if you can not identify a threshold that works you might have to consider manually editing the polygons. For example by deleting individual polygons in QGIS.

Superimpose the small “no data” clumps over the original DEM to create a DEM that is complete over land.

> r.mapcalc "inland_comp_DEM = if(( isnull(DEM@PERMANENT)), drain_terminal_small,DEM@PERMANENT )" –overwrite

Optionally export the completed DEM for land areas:

> r.out.gdal format=GTiff input=inland_comp_DEM output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazoniax/0/inland-comp-DEM_amazonia_0_cgiar-250.tif –overwrite

The DEM that you just created, inland_comp_DEM is sufficient for use with r.watershed in part 2. The remaining part of this post deals with filling up pits. But that is strictly not needed for running r.watershed and might even have detrimental consequences.

GRASS shell script

The shell script below contains all the GRASS commands explained above. You can run the commands below by copying them to a file with the extension .sh. Remember that you have to make the script file executable before you can run it (chmod u+x /path/to/file.sh or chmod 755 /path/to/file.sh). The run it from the Terminal window where GRASS is running.

# Create a map of the terminal drainage

mkdir -p /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/stage0/script

r.mapcalc "drain_terminal = if(isnull('DEM@PERMANENT'), 1, null())"

r.clump input=drain_terminal output=terminal_clumps --overwrite

r.to.vect input=terminal_clumps output=terminal_clumps type=area --overwrite

v.to.db map=terminal_clumps type=centroid option=area columns=area_km2 units=kilometers

# v.out.ogr input=terminal_clumps type=area format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazoniax/0/terminal-clumps_SRTM_hydro-amazonia_0_cgiar-250.shp --overwrite

# Fill in DEM over land

v.to.rast input=terminal_clumps type=area where="area_km2< 2.0" output=drain_terminal_small use=val value=0 --overwrite

v.to.rast input=terminal_clumps type=area where="area_km2 >= 2.0" output=drain_terminal_large use=val value=0 --overwrite

r.mapcalc "inland_comp_DEM = if(( isnull(DEM@PERMANENT)), drain_terminal_small,DEM@PERMANENT )" --overwrite

# r.out.gdal format=GTiff  input=inland_comp_DEM output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazoniax/0/inland-comp-DEM_amazonia_0_cgiar-250.tif --overwrite

Restrict DEM filling to coastal strip

If you want to restrict the pit filling to the coastal strip you need to create a mask (r.mask). A mask limits the region for raster operations and will reduce the processing time.

To set a mask restricting the processing to the coastal strip you have to create a new layer for the terminal drainage - this time excluding the cells identified in drain_terminal_small.

> r.mapcalc "drain_terminal_v2 = if(isnull('inland_comp_DEM'), 1, null())" –overwrite

Then do an r.buffer starting from version 2 (v2) of the terminal drainage, set the maximum distance to the width of the coastal strip you want to analyse (e.g. 3 kilometers in the example).

> r.buffer input=drain_terminal_v2 output=coastal_strip distances=3000 units=meters –overwrite

Apply an r.mapcalc calculation to create a boolean layer of the coastal strip.

> r.mapcalc "coastal_mask = if((coastal_strip > 1), 1, null())"

To apply the mask by r.mask you just set it and it will remain in place until explicitly removed.

> r.mask raster=coastal_mask

Filling pits in the DEM

With all land areas having an assigned elevation, the next task is to fill up pits. If you want to fill up pits large than a single cell, you need to set a threshold for the maximum pit size to fill. This is done in one or two steps. First you have to decide whether to only fill up single cell pits (by setting the the parameter filldirsingle to 1 [= True]). Filling up single cell pits is more straight forward and is the recommended practice. If you set filldirsingle 0 [= False] you also need to set the maximum pit are to fill up (the parameter pitfillmaxarea), in the area units set to the vector database (square kilometers in the example below).

As noted above, you can not run r.fill.dir on large files. Here I only list the principal steps. To actually run the pit filling make use of the Python package basin_extract to create the required GRASS commands as explained further down.

The principal steps for filling up single cell pits (set the -f flag) in a DEM in GRASS:

r.fill.dir -f originaldem -> filldem [the f flag forces filling of single cells only]
r.mapcalc difference between filled and orignal dem
r.to.vect for cells (points) with difference
v.db.addcolumn for storing filled DEM value
v.what.rast extract fill DEM to vector points
v.patch to collect all vector points to fill in a single data source
v.to.rast rasterize the DEM values
r.mapcalc superimpose the filled DEM values over the original DEM

Overlaying the vector points on top of the original DEM can be done using different approaches. Apart from the GRASS comamnds used above (v.patch, v.to.rast and r.mapcalc) you can also make use of GDAL. This is discussed further down.

The principal steps for filling up also pits larger than a single cell in a DEM in GRASS:

r.fill.dir originaldem -> filldem2 [all pit cells filled regardless of area]
r.mapcalc difference between filled and orignal dem
r.to.vect for regions (areas) with difference
v.db.addcolumn for storing filled DEM value
v.what.rast extract fill DEM to polygon centroids
- v.patch to collect all vector areas to fill in a single data source
v.to.rast rasterize the DEM values
r.mapcalc superimpose the filled DEM values over the original DEM

The process steps above can not be run for very large grids - it takes too long time. But pits are usually small. Larger pits (hundreds of square kilometers or larger) usually represent endorheic basins and should not be filled. Thus you must, and can, partition large DEMs into smaller tiles and then run each tile separately. With an overlap that allows you to capture pits up to the size you deem relevant.

Create tiled process loop

The example DEM used in this tutorial of central South America is approximately 22700 × 22500 cells. This is far too large to process in one go. The Python package developed for assisting the basin delineation, basin_extract can generate a tiled process loop for GRASS.

Parameterisation

The Python script basin_extractor is parameterised from an XML file that follows the general structure of Karttur´s GeoImagine Framework. The structure below shows the setup for generating the GRASS shell script for a tiled processing of pit filling of the DEM over central South America (“Amazonia”).

<basindelineate>
	<userproj userid = 'karttur' projectid = 'karttur' tractid= 'amazonia' siteid = '*' plotid = '*' system = 'MODIS'></userproj>

	<!-- Define processing -->
	<process processid ='BasinDelineate'>
		<overwrite>Y</overwrite> # Y(es) or N(o)
		<delete>N</delete> # Y(es) or N(o)
		<parameters
		stage = '0' # 0, 1, 2 or 3
		adjacentdist = '330' # any number in map distance units
		outlet = 'SFD' # MOUTH, SFD or MFD
		distill = '' # MFD or None (nothing)
		clusteroutlet = 'central' # central or max
		basinthreshold='2000' # any number is cells
		watershed='MFD5' # SFD, MFD or MFD? (? in range 1..10)
		verbose = '1' # 0, 1 or 2
		proj4CRS = '+proj=sinu +lon_0=0 +x_0=0 +y_0=0 +a=6371007.181 +b=6371007.181 +units=m +no_defs'
		>

		</parameters>
		<srcpath volume = "GRASS2020"></srcpath>
		<dstpath volume = "GRASS2020"></dstpath>

		<srccomp>
			<!-- the name <tag> and prefix must be the same and can not be altered. The script looks for which source data is included and compares that with the parameters, and then sets the processing method if these corresponds. Otherwise the script ends with an error message.
			-->
			<basin-mouth-outlet-pt source = "SRTM" product = "drainage" folder = "basin" band = "basin-mouth-outlet-pt" prefix = "basin-mouth-outlet-pt" suffix = "cgiar-250">
			</basin-mouth-outlet-pt>

			<basin-MFD-outlet-pt source = "SRTM" product = "drainage" folder = "basin" band = "basin-MFD-outlet-pt" prefix = "basin-MFD-outlet-pt" suffix = "cgiar-250">
			</basin-MFD-outlet-pt>

			<basin-SFD-outlet-pt source = "SRTM" product = "drainage" folder = "basin" band = "basin-SFD-outlet-pt" prefix = "basin-SFD-outlet-pt" suffix = "cgiar-250">
			</basin-SFD-outlet-pt>

			<shorewall-pt source = "SRTM" product = "drainage" folder = "basin" band = "shorewall-pt" prefix = "shorewall-pt" suffix = "cgiar-250">
			</shorewall-pt>
		</srccomp>

		<dstcomp>
			<basin-outlet>
			</basin-outlet>
			<!--
			To force a non-default destination path and name, you can enter all components explicitly, e.g.
			<basin-outlet band = "basin-mfd+mfd-max" prefix = "basin-mfd+mfd-max">
			</basin-outlet>
			-->
		</dstcomp>
	</process>

</basindelineate>

The core parameters of relevance for this stage (0) include:

stage [0, 1, 2 or 3] (this part is for stage = ‘0’)
adjacentdist [not relevant for stage 0]
outlet [not relevant for stage 0]
distill [not relevant for stage 0]
clusteroutlet [not relevant for stage 0]
basinthreshold [not relevant for stage 0]
watershed [not relevant for stage 0]
pitfill
tilesize
tileoverlap
single [Boolean]
verbose [0, 1 or 2]
proj4CRS [‘proj4CRS definition for output data if input layers lack proper projection information’]

Setup xml file and run basin_extract

Use the xml template file above to setup the processing for your own xml. Set the parameter stage to 0 and run basin_extract pointing to the xml.

Running basin_extract with stage = 0 generates two shell script files, one for GRASS and one for OGR2OGR. You do not need to use the OGR2OGR file, it is just supplied in case you prefer that.

For each tile that is processed the GRASS shell script includes the following set of commands (excluding comments):

# This example shows the script for single cell filling (with the -f flag set):

# region is automatically set from the tiling process
g.region -a n=-3660170.456407 s=-3914992.450317 e=-8826107.250690 w=-9080929.244600

# the -f flag restricts the filling to single, isolated cells
r.fill.dir -f input=inland_comp_DEM output=hydro_cellfill_DEM_0_0 direction=hydro_cellfill_draindir_0_0 areas=hydro_cellfill_problems_0_0 --overwrite

# get the difference between the filled and the original DEM
r.mapcalc "DEM_cellfill_diff_0_0 = hydro_cellfill_DEM_0_0 - inland_comp_DEM" --overwrite

# create boolean mask of changed cells
r.mapcalc "inland_fill_cell_0_0 = if(DEM_cellfill_diff_0_0 != 0, 1, null() )" --overwrite

# convert the cells with altered elevation to a point vector
r.to.vect input=inland_fill_cell_0_0 output=inland_fill_pt_0_0 type=point --overwrite

# add column to vector file with altered elevations
v.db.addcolumn map=inland_fill_pt_0_0 columns="filldem DOUBLE PRECISION"

# read the altered DEM values to the point vector
v.what.rast map=inland_fill_pt_0_0 column=filldem raster=hydro_cellfill_DEM_0_0

# export the point vector to an ESRI shape file
v.out.ogr input=inland_fill_pt_0_0 type=point format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/stage0/inland-fill-pt-0-0.shp --overwrite

Superimpose filled DEM over original DEM

All areas identified as pits are captured in the sequence of tiles. You now have several alternatives for superimposing these values over the original DEM. All alternatives can be applied using a tile by tile approach, or applied for the whole region after patching the tiles.

Filling of pits affects flow routing and hydrological modeling. When the flow routing enters a flat area, an algorithm traversing the flat area towards the lowest drainage(s) out of the flat must be identified. Dependent on the parameterization of the flow dividsion (single or multiples and the spread if multiple) the flat area will be wetted differently. This will later also affect the estimation of soil moisture, evapotranspiration and flooding tendencies of the cells in the flat area (in general all tend to increase). The most widely spread recommendation is to allow filling of single cell pits, but be more careful with filling larger and larger pits.

On the other hand, DEMs generated by SAR data have a tendency to underestimate the elevation of water surface (due to radar signal double bouncing on water surface and shoreline structures). Thus no general recommendation can be given regarding how to handle larger depressions in DEMs.

You have different alternatives for superimposing The alternatives for filling pits that I have tested include:

superimpose tile by tile with GDAL
patch up vectors in GDAL, superimpose
patch up vectors in GRASS, rasterize, superimpose

GDAL is quicker and can be used for burning vector data on a raster. The burning can be done on a tile by tile basis, or after patching up the tiles to a single vector data source. With GRASS you have to first patch the vector tiles, then rasterize them, and then superimpose. This takes longer and demands more processing capacity.

Patching tiles (optional)

If you use GDAL (GDAL_rasterize) for burning the filled DEM on the original DEM you do not need to patch the tiles. Just continue to the section on Rasterize using GDAL below. The shell script for the burning is already produced by the Python package basin_extract.

You can use two different methods for patching together the tiles. The first alternative is to use the GRASS command v.patch. The commands for patching all the times are given at the end of the GRASS script file:

g.region raster=DEM@PERMANENT

MAPS=$(g.list type=vector separator=comma pat="inland_fill_pt_*")
v.patch -e input=$MAPS output=inland_fill_pt

MAPS=$(g.list type=vector separator=comma pat="inland_fill_area_*")
v.patch -e input=$MAPS output=inland_fill_area

The other alternative is to use the GDAL vector command ogr2ogr. The command line process for patching together all vectors are prepared in the script file “region”_ogr_part0.sh, produced and reported by the Python package basin_extractor. The first lines of the shell script looks like this:

ogr2ogr -skipfailures -nlt /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/flowdir-pt-dem_drainage_amazonia_0_cgiar-250.shp /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/stage0/inland-fill-pt-0-0.shp

ogr2ogr -skipfailures -nlt /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/flowdir-pt-dem_drainage_amazonia_0_cgiar-250.shp /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/stage0/inland-fill-area-0-0.shp

ogr2ogr  -append -skipfailures -nlt /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/flowdir-pt-dem_drainage_amazonia_0_cgiar-250.shp /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/stage0/inland-fill-pt-0-1.shp

ogr2ogr -append  -skipfailures -nlt /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/flowdir-pt-dem_drainage_amazonia_0_cgiar-250.shp /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/stage0/inland-fill-area-0-1.shp

The two first lines coopies the input vectors to a new file, all following lines appends the input vectors to the initial output file.

Patch up vectors in GRASS, rasterize, superimpose

It is more complicated to superimpose the filled elevation values using GRASS compare to GDAL. For GRASS you first have to patch up the vectors, then rasterize and finally superimpose. The required sequence of commands is included in the GRASS shell script file that was produced when running basin_extract for stage0. The very last lines of the that shell script file should be something like:

v.to.rast input=inland_fill_area where=”area_km2<2.0” output=inland_fill_accept use=attr attribute_column=filldem –overwrite</span>

r.mapcalc inland_fill_dem = if( isnull(inland_fill_accept), inland_comp_DEM, inland_fill_accept)

Rasterize using GDAL

With GDAL you can instead use GDAL_rasterize to burn the DEM values from the vectors with the filled DEM value directly over the original DEM. The burning can be done using either the vector tiles or a patched vector. By using vector tiles you bypass the need for patching tiles.

That requires fewer step and is already prepared for running in the two shell script files:

amazonia_GDAL_pt_part0.sh
amazonia_GDAL_area_part0.sh

Here are the first lines from the latter:

GDAL_rasterize -a filldem /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/stage0/inland-fill-area-0-0.shp /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/inland-comp-demm_drainage_amazonia_0_cgiar-250.shp
GDAL_rasterize -a filldem /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/stage0/inland-fill-area-0-1.shp /Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazonia/0/inland-comp-demm_drainage_amazonia_0_cgiar-250.shp

Visualizing the DEM errors and fixes

If you want to try the hydrological fixing of DEM using r.fill.dir, you need to start by setting a subregion to process with g.region. About 1 million cells is a suitable region.

> g.region -a n=”float” s=”float” e=”float” w=”float”

If you do not set a subregion, the process will take several hours, or even days. With a small subregion set , you can run r.fill.dir.

for single cell pits only:

> r.fill.dir -f input=inland_comp_DEM output=hydro_cellfill_DEM_ direction=hydro_cellfill_draindir areas=hydro_cellfill_problems –overwrite

or for all depressions:

> r.fill.dir input=inland_comp_DEM output=hydro_areafill_DEM_ direction=hydro_areafill_draindir areas=hydro_areafill_problems –overwrite

Calculate the difference between the pit filled and the original DEM using r.mapcalc.

> r.mapcalc “DEM_fill_diff = hydro_areafill_DEM - inland_comp_DEM” –overwrite

Set a color ramp to the difference layer.

> r.colors DEM_fill_diff color=differences

Export the difference layer to a goetiff.

> r.out.gdal format=GTiff input=DEM_fill_diff output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazoniax/0/DEM-fill-diff_amazonia_0_cgiar-250.tif –overwrite

Calculate a boolean map of the difference area.

> r.mapcalc “inland_fill_areas = if(DEM_fill_diff != 0, 1, null() )” –overwrite

Convert the boolean map of identified pits to a vector.

> r.to.vect input=inland_fill_areas output=inland_fill_areas type=area –overwrite

Export the vector with identified pits to an ESRI shape file.

> v.out.ogr input=inland_fill_areas type=area format=ESRI_Shapefile output=/Volumes/GRASS2020/GRASSproject/SRTM/region/basin/amazoniax/0/inland-fill-areas_SRTM_hydro-amazonia_0_cgiar-250.shp –overwrite

You can inspect the exported files in for instance QGIS

You can also open a monitor for GRASS directly from the command line and then add the layers from the command line.

> d.mon wx0

> d.shade shade=inland_comp_DEM

> color=inland_comp_DEM

> d.vect inland_fill_areas type=boundary color=red

git clone basin_delineate

2020-10-17T11:27:00+00:00

Introduction

The python package basin_extract is freely available as a repository on GitHub.

If you just want to download basin_extract from GitHub, just go ahead and you are done with this post. The rest of this post deals cloning either a stable version or a development version. The letter is intended for those who want to participate in the code development.

Prerequisits

If you want to use basin_extract with the IDE Eclipse you must have setup Eclipse as outlined in the previous post. It you want to participate in the development you should also have setup the git version control system.

Cloning alternatives

First you need to decide if you want to participate in the development, or even develop your own code. If you want to do either of those you should start by forking the original repo to your own GitHub account. If you d not need your won development version you can skip the forking and just clone the basin_extract from Karttur’s repo.

Fork project to your own repo

Login to your account on GitHub, or create a free account if you do not have one. While being logged in navigate to Karttur’s basin_extract repo. In the upper right corner, below the top menu row, there is a button for Fork. Click on it, and GitHub creates a fork (copy), then opens it in your own account.

GitHub forked repo.

The forked repo has two branches. Change to the branch dev by clicking the branch button, as illustrated to the right. The page for the dev branch (below) tells you that This branch is 1 commit ahead of main.

With your own fork of the project basin_extract you are ready to get a local clone and starting coding. You can then push your improved/customized code to your won fork, and then push

Local clone

Regardless if you want to clone the stable (main) or development (dev) version, you have some different options.

Clone using Eclipse at startup
Clone from inside Eclipse
Clone using git command line and then import separately into Eclipse

If you do not intend to use Eclipse you can use the third laternative, but you can also just download the package directly from GitHub.

Eclipse startup clone

This is probably the easiest way to get the whole project setup in Eclipse. Start Eclipse and when the IDE launcher page open, create a new folder in your workspace directory. When the welcome pages opens, select the alternative Checkout projects from Git.

From Eclipse Welcome page select _Checkout projects from Git_.

The next window that opens, Select Repository Source just highlight [Clone URI] and click Next.

Eclipse Select Repository Source - highlight [Clone URI] and click Next.

In the Source Git Repository window, paste the URI to the GitHub repo of basin_extract. Either Karttur’s original repo (if you are not pushing any changes back online) or your own fork (to allow staging and committing changes to the online repo). Then click Next.

Eclipse Source Git repo.

In the Branch selection window you should have two alternatives, dev and main. Choose the one that suit your needs (main if you are user, dev if you are a developer). Click Next.

Eclipse Git Branch Selection.

Set the path to the directory you just created as the target Directory. DO NOT accept the default target path suggested by Eclipse</span>, under your user and then git. This will lead to conflicts when updating git itself. You can also change the Initial branch to _dev_ (or another branch). But keep the standard _origin_ for the Remote name.

Eclipse Git Local Destination.

In the next window (Select a wizard to use for importing projects) click the radio button for Importing Existing Eclipse Projects. Then Next.

Eclipse Select a wizard to use for importing projects.

And you should have reached the last window, Import Projects and this time you can happily click Finish.

Eclipse Finish Import projects.

When the project is imported, Eclipse looks for a Python interpreter.

Eclipse python projects requires a Python interpreter.

Click the Manual config and you will get to to the Preferences window and the menu set to identifying Python interpreters.

Eclipse Preferences, identifying python interpreters.

The Python interpreter you need is described in the parallel post on Eclipse for Basin extraction.

Clone from inside Eclipse

You can clone a git repo from within an existing Eclipse project. Start an empty Eclipse project. Get the GIT perspective. Either from the menu system:

Window -> Perspective -> Open Perspective -> Other … .

Eclipse Menu path to different perspectives.

Eclipse menu of perspectives.

You can also use the search tool and start writing “git” and locate git perspective.

Eclipse search.

In the Git repositories view you should click the alternative Clone a Git repository (if no text appears slide the cursor over the icons to get the alternative Clone a Git repository and add the clone to this view).

Eclipse git perspective.

This will open the same Source Git Repository window as in the previous section and the steps that then follows are the same. But Eclipse does not recognise the imported repo as a PyDev project. You have to define the PyDev project and then team up the git repo packages. How to do that is covered in the post Setup Eclipse teamed with GitHub repository.

Make a git repo

2020-10-17T11:27:00+00:00

Introduction

The python package basin_extract is freely available as a repository on GitHub. This post is a manual for how it was constructed. The post is thus only of interest if you want to create a similar repo.

Prerequisits

You need to have a GitHub account and you must have Installed git for command line.

basin_extract at GitHub

This post outlines how to create a GitHub repo with a default main branch and a dev(elopment) branch using git command line tool. You have to register a free account with GitHub and then create a repository. The name of the repo with the basin_extract code is called basin_extract. For a more detailed instruction on creating a new repo, see the post Remote repositories with GitHub.

When the new repo is created, click on the green button Code. There are (in November 2020) 4 alternatives for cloning, plus the additional options [Open with GitHub Desktop] and [Download ZIP]. Copy the text for the clone alternative [SSH], as shown in the figure to the right.

Clone to local repo

Open a Terminal window on your local machine and cd to the parent directory where you want to create the clone of your remote (GitHub) repository. Then type (but do not execute):

$ git clone

If you followed the instructions in the previous section, you can now just paste the SSH link from your clipboard to the command line:

$ git clone git@github.com:karttur/basin_extract.git

Execute the command and the remote repo (“basin_extract”) should clone to your local machine. If this is the first time you use the SSH key, you will be prompted the following statement and question:

Cloning into 'basin_extract'...
The authenticity of host 'github.com (140.82.118.4)' can't be established.
RSA key fingerprint is [.....].
Are you sure you want to continue connecting (yes/no)?

Answer with a full yes

The cloning will only take a few seconds, and the result is reported at the terminal prompt:

Cloning into 'basin_extract'...
remote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 4 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (4/4), 12.54 KiB | 2.51 MiB/s, done.

Change direction (cd) to the newly cloned repo and list (ls) the content:

$ cd basin_extract

$ ls

if you instead type (ls -a) also hidden files will be listed, including .git.

$ ls -a

The post on Local git control explains how to Check and setup user name.

You can check the remote repo associated with your local clone:

git remote -v

origin	git@github.com:karttur/basin_extract.git (fetch)
origin	git@github.com:karttur/basin_extract.git (push)

Check out the branches and history:

$ git log --all --decorate --oneline --graph

* a5a7152 (HEAD -> main, origin/main, origin/HEAD) Initial commit

For the clone we are working with the HEAD pointer points towards two new items: origin/main and origin/HEAD. As origin can be seen as an alias for the primary remote repo, the pointing is towards the remote (GitHub) repo. As HEAD is pointing both towards the local main and the remote main, our local repo is in sync with the GitHub repo.

Create/edit .gitignore file

Open/create the file .gitignore using for example the terminal editor pico.

$ pico .gitignore

Add the following items to ignore:

.DS_Store
*.pyc
__pycache__/

The first item (.DS_Store) is an internal Mac OSX file, the second (*.pyc) is a wildcard for ignoring all python cache files and the last item (__pycache__/) is the directory holding the python cache files.

Hit [ctrl]+[X] to exit pico and save the edits by pressing Y when asked.

Stage and commit I

With edits done to the .gitignore you can stage (add) and commit (lock in and save) the changes to your local git repository:

git add .
git commit -m 'created .gitignore'

As this is the first time you stage something you have to use the separate git add . command.

If all the files that you want to commit have already been staged before, you can shorten the two commands to:

git commit -am 'created .gitignore'

Create or copy PyDev project

The repo (basin_extract) only contains the README, LICENSE and .gitignore files (plus .git). The Python package that you want to develop with the help of git must be either created inside the repo or, if you have already started the package, copied into it. As I have already built a first version of the Python package basin_extract, I copy the complete structure into the repo. The initial structure of basin_extract thus becomes (leaving out the content of .git and adding comments):

.
|____README.md # initial README markdown (md) text file
|____.gitignore
|____.git
|____basin_delineate # This is the Eclipse project (containing the package)
| |____.project # definition of the Eclipse project
| |____.pydevproject # definition of the Eclipse PyDev project
| |____basin_extract # The main python package
| | |______init__.py # Python default initiation script file
| | |____basin_extract.py # The main python module
| |____params # Python package for setting parameters
| | |____be_params.py # python module for setting parameters
| | |______init__.py # Python default initiation script file
| | |____be_xml.py # python package for reading xml parameters
| |____ds_manage # python package for spatial data source (ds) management
| | |______init__.py # Python default initiation script file
| | |____datasource.py # python module for patial data source (ds) management

Stage and commit II

Stage and commit the complete project in your local clone of the repo basin_extract.

git add .
git commit -m 'initial commit of PyDev project'

The check the status of your repo:

$ git status

On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

Or with the more decorated option:

$ git log --all --decorate --oneline --graph

* 1430b14 (HEAD -> main) initial commit of PyDev project
* a5a7152 (origin/main, origin/HEAD) Initial commit

Push to origin

Push the committed changes to your remote repo on GitHub:

git push  <REMOTENAME> <BRANCHNAME>

$ git push origin main

Enumerating objects: 1139, done.
Counting objects: 100% (1139/1139), done.
Delta compression using up to 4 threads
Compressing objects: 100% (1104/1104), done.
Writing objects: 100% (1138/1138), 8.10 MiB | 3.79 MiB/s, done.
Total 1138 (delta 229), reused 0 (delta 0)
remote: Resolving deltas: 100% (229/229), done.
To github.com:karttur/basin_extract.git
   a5a7152..1430b14  main -> main

$ git status

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

Create local dev branch

Create a local development (dev) branch.

$ git checkout -b "dev"

Switched to a new branch 'dev'

$ git branch [-r] [-a] [-r] to see only remote branches, [-a] to see all branches.

* dev
  main

A minute edit

Do some small editing to any of the files in the repo, just for illustration really. As all files are already staged, you can stage and commit in one command:

$ git commit -a -m "update be_params.py"

[dev 4cc0223] update be_params.py
 1 file changed, 96 insertions(+), 97 deletions(-)

$ git log --all --decorate --oneline --graph

* 4cc0223 (HEAD -> dev) update be_params.py
* 1430b14 (origin/main, origin/HEAD, main) initial commit of PyDev project
* a5a7152 Initial commit

HEAD is now pointing at the branch dev and the remote repo (with the alias origin) is out of sync still pointing at masin.

Upload branch

Upload the branch dev to the repo

$ git push origin dev

Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 4 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 975 bytes | 975.00 KiB/s, done.
Total 5 (delta 3), reused 0 (delta 0)
remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
remote:
remote: Create a pull request for 'dev' on GitHub by visiting:
remote:      https://github.com/karttur/basin_extract/pull/new/dev
remote:
To github.com:karttur/basin_extract.git
 * [new branch]      dev -> dev

$ git log --all --decorate --oneline --graph

* 4cc0223 (HEAD -> dev, origin/dev) update be_params.py
* 1430b14 (origin/main, origin/HEAD, main) initial commit of PyDev project
* a5a7152 Initial commit

HEAD is pointing towards the branch dev, also in the remote repo (origin/dev).

Return to the online (remote) GitHub repo basin_extract.

GitHub repo after pushing local branch "dev".

Change to the branch dev by clicking the branch button, as illustrated to the right. The page for the dev branch (below) tells you that This branch is 1 commit ahead of main.. Thus we know that all has worked out as we intended.

GitHub repo showing the "dev" branch.

Eclipse for Basin extraction

2020-10-15T11:27:00+00:00

Introduction

basin_extract is a Python package that belongs to the semi automated system for delineating river basins. This post is a manual on how to setup a Python environment for the basin_extract package in the Eclipse Integrated Development Environment (IDE).

Prerequisites

You must have installed Anaconda for handling virtual Python environments and Eclipse IDE for PyDev.

Setup virtual Python environment

The basin_extract package requires the standard (default) Python packages that come with Eclipse, plus some additional packages:

numpy
pandas
shapely
scipy

Trying to setup a working Python environment for basin_extract in October 2020 I found that the listed packages are incompatible in Python 3.8. The virtual environment herein is thus setup using the older Python 3.6 interpreter.

The basics of Conda virtual environments is covered in another post. More extensive information is available on the official conda document site. Here I will only step over the barebones of setting up a virtual environment for Ortho.

When you open a Terminal window on a machine with Conda installed, the first entry on the cursor line should be the active conda environment. (base) is the default (overall) environment. If the cursor line of your Terminal window does not say (base) you have activated another Conda environment. To return to base enter the command:

$ conda activate

Update conda and anaconda

Before setting up the virtual environment, update Conda and Anaconda at the terminal:

(base) …$ conda update conda

(base) …$ conda update anaconda

Create a Python 3.6 virtual environment

The basic command for creating a virtual Python environment with a pre-defined version of Python is (do not run it yet, read a bit further first):

(base) …$ conda create -n basin_extract_py36 python=3.6

If your Conda environment is defined to include a set of additional packages (if you have no idea about what I am writing, never mind and just continue), then these will be installed in your virtual environment on top of the default Python installation. To avoid that instead type:

(base) …$ conda create --no-default-packages -n basin_extract_py36 python=3.6

This will install a barebone Python 3.6 virtual environment even if you have defined additional packages to be installed by default. Now you can go ahead and create the barebone virtual environment with one of the command above.

Install additional packages

Your newly created environment does not include the additional packages needed (the ones listed above)for the Python package basin-extract. When adding these packages you have to make sure that they are installed within your new environment. That can be achieved by either destining the installation from (base) or first activate your new environment. Here I will only show how to change the active environment and then install. Thus activate your virtual environment:

(base) …$ conda activate basin_extract_py36

The cursor line will then change to reflect that you are now in another environment.

(basin_extract_py36) …$

With your new Python 3.6 environment active you can install the required packages:

(basin_extract_py36) …$ conda install -c conda-forge gdal

(basin_extract_py36) …$ conda install -c anaconda numpy

(basin_extract_py36) …$ conda install -c anaconda scipy

(basin_extract_py36) …$ conda install -c conda-forge shapely

Setting this up in October 2020, all installations went through without problems. However, setting up a virtual environment with more recent versions of Python can lead to conflicts between packages. For that reason it is better to install all required packages with the Python initial installation, as explained in the next section.

Install packages with the python version

Setting up a virtual environment with all the packages listed has the advantage that Conda checks the consistencies between all packages before installing. To try that out for the basin_extract environment, return to base:

(basin_extract_py36) …$ conda activate

And then extend the Conda create command with a list of all the packages to install:

(base) …$ conda create --no-default-packages -n basin_extract_py36 python=3.6 numpy scipy gdal shapely

Set your virtual environment as your Python interpreter in Eclipse

Start Eclipse. In the Eclipse IDE Launcher window, specify a new location and click Launch.

Eclipse select a new directory as workspace.

In the Welcome page that opens, just go to Workbench (in the upper right corner).

Eclipse welcome page, just click the Workbench in the upper right corner.

The default IDE that opens is for Java projects, but you want it to be a PyDev project page. To change to a PyDev perspective, go via the menu:

Window -> Perspective -> Open Perspective -> Other…

Eclipse menu route for opening a new perspective.

In the window that opens, select PyDev. If PyDev is not available as an alternative, you need to go back to post on Eclipse IDE for PyDev and use the Eclipse Marketplace to install PyDev for Eclipse.

Eclipse pop up widnow for selecting perspective.

To set up your virtual Python environment as the Python interpreter, go via the main menu:

Eclipse -> Preferences

And then in the Preference window that opens, go via the left side navigation:

PyDev -> Interpreters -> Python Interpreter,

and the right side of the window expands. Click the Browse for python/pypy exe and navigate to the directory envs under your Anaconda installation. There you will find the virtual environment that you just created, basin_extract_py36. The Python executable file is then under the path bin/python. The full path on my machine is shown in the figure below. Click OK to select the python interpreter.

Eclipse window for selecting interpreter.

In the next post you will setup the projects, packages and modules that constitute the basin_extract Python package.

GRASS 7 setup

2020-10-03T06:17:25+00:00

Introduction

This post covers how to start GRASS 7 for the first time. Including defining a GRASS database and a location with a projection. The manual is for GRASS 7 on Mac OSX and is part of a series on how to delineate river basins using GRASS GIS and other tools.

The manual only covers the command line GRASS tools for processing. But all the processing can also be done using the GRASS Graphical User Interface (GUI).

Prerequisites

You must have GRASS 7 installed as described in the post on Install GDAL, QGIS and GRASS. You also need a projected raster file (e.g. a GeoTIFF) for defining both the projection and the location.

Start GRASS

Before you actually start GRASS, you need to start up a Terminal session. Otherwise GRASS might not start properly. Once you have the Terminal up and running locate your installation of GRASS7 and start it. Alternatively you can also start GRASS7 directly from the command line, just type in the full path to the grass.sh executable script:

/Applications/GRASS-7.X.X.app/Contents/MacOS/Grass.sh

The startup might take a while, and GRASS should then show the window GRASS GIS 7.x.x Startup.

GRASS7 initial startup page

If the location you want to work with is already defined in your GRASS database, it is listed as a GRASS location (the location Amazonia in the example below). You can then just skip to the last section in this post Create a new mapset.

GRASS7 startup page with existing location

Define new GRASS Location

The first time you start GRASS7 you have to set the database directory, and a first Location. As noted on the startup page, in red even, GRASS needs a directory (GRASS database) in which to store its data …. The default database directory is the users home directory. The basin delineation will, however, require a rather large storage space and I recommend using an external disk or server for the data storage.

Use the Browse button to select the location for your GRASS database. Then use the New button between the smaller windows for 2 Select GRASS Location and 3. Select GRASS Mapset. GRASS then presents you with a new window, Define new GRASS Location.

Define new GRASS Location

In the example figure above, I created a local disk GRASS2020 and then the directory GRASSDATA for my GRASS database. I then also defined a Location called Amazonia. All GRASS locations will get a default MapSet called PERMANENT; let that be your initial mapset for the Location you define.

Do not tick the boxes for Set default region extent and resolution or Create user mapset, we will fix that in the next step. Click Next > to get to the next step.

Choose method for creating a new location

A new window, but still belonging to the Define new GRASS Location set, opens. The best option here is to have a projected raster file that you can point at for defining the location. Assuming that you have one, click the radiobutton for that option.

Define new GRASS Location

Click Next > and browse to the raster file to use for creating the new location. If you did not select the option to use an existing file for creating the new location, you need to manually add the projection and location.

When you have added all the information required, GRASS will summarise the definition of the new location.

Define new GRASS Location

Click Finish and you are done with the definition of database, location and projection of your first GRASS7 project.

Import raster defining the location

If you choose to define your location using a raster file, like illustrated above, GRASS7 will automatically ask if you want to import this data. In most cases the answer is most likely yes. Whereupon the file should be successfully imported into the MapSet PERMANENT. Click OK and GRASS7 should start its Graphical User interface.

Import data used for defining projection and region

GRASS Graphical User Interface (GUI)

GRASS7 opens an empty GUI with two windows, a Map Display and a Layer Manager.

GRASS 7 Graphical User Interface (GUI)

In the Layer Manager find the button for Add multiple raster or vector map layers and click it. Add the raster file you used for defining the location and projection.

GRASS 7 Map Display

GRASS commandline

You can either user GRASS via the GUI, or using the GRASS commandline. If you started GRASS with the Terminal up and running, you should now have a terminal windown where GRASS is running.

GRASS 7 terminal commandline

Commandline tools

Try the commandline tool by checking out the projection:

GRASS 7.2.2 (Amazonia):~ > g.proj -p

The projection information will be returned at the prompt:

-PROJ_INFO-------------------------------------------------
name       : Sinusoidal (Sanson-Flamsteed)
a          : 6371007.181
es         : 0
proj       : sinu
lon_0      : 0
x_0        : 0
y_0        : 0
no_defs    : defined
-PROJ_UNITS------------------------------------------------
unit       : meter
units      : meters
meters     : 1

Then also check the region:

GRASS 7.2.2 (Amazonia):~ > g.region -p

Note how the returned information specifies the boundaries of the region as well as the spatial resolution and the number of rows and columns (cols) that span the region.

projection: 99 (Sinusoidal (Sanson-Flamsteed))
zone:       0
datum:      ** unknown (default: WGS84) **
ellipsoid:  a=6371007.181 es=0
north:      1297275.606933
south:      -3914992.450317
west:       -9080929.2446
east:       -3822329.91573
nsres:      231.6563581
ewres:      231.6563581
rows:       22500
cols:       22700
cells:      510750000

Rename layer

In the following parts of this series on Basin delineation, the name of the DEM layer to use for delineating basins will be assumed to be DEM. If you imported the DEM as part of the definition of your location, it will be given the same name as the original map. If you forgot the name, use the GRASS general command g.list to list the layers in the current mapset:

> g.list type=raster

If your DEM is not listed, make sure you are in the correct mapset with the command g.mapset:

> g.mapset -p

> g.mapset mapset=name

Rename any layer in your current mapset with the GRASS general command g.rename:

> g.rename raster=DEM_SRTM_amazonia_0_cgiar-250,DEM

Import DEM

To manually import the DEM, and at the same time set a custom name you can use the GRASS command r.in.gdal. Add the -e flag to set the region to the extent of the imported DEM if not already set to fit this dataset.

> r.in.gdal -e input=/Volumes/GRASS2020/MODIS/SRTM/region/DEM/amazonia/DEM_SRTM_amazonia_0_cgiar-250.tif output=DEM –overwrite

Create a new mapset

The DEM raster file that you imported, either when you defined the projection and location, or as a separate raster layer, should have ended up in the mapset PERMANENT. For the delineation work, deriving a range of intermediate layers, and finally getting a map of all the basin outlets, it is better to change to a user defined mapset. Use the GRASS command g.mapset.

> g.mapset -c drainage

Exit GRASS

To end the session you need to to exit from the GRASS commandline:

GRASS 7.2.2 (Amazonia):~ > exit