Skip to content

Earthwork tutorials: update for compatibility with new version of r.earthworks #90

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 18, 2025
Merged

Earthwork tutorials: update for compatibility with new version of r.earthworks #90

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
066466e
earthworks tutorials
baharmon Jul 14, 2025
164f356
earthworks tutorials
baharmon Jul 14, 2025
f1c3e34
revised tutorials
baharmon Jul 15, 2025
82e5fc5
merge
baharmon Aug 5, 2025
8b9b8b9
earthworking tutorials: update for compatibility with new version or …
baharmon Aug 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions content/tutorials/earthworks/basics.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,8 @@
"and y-coordinates. Use the `z` parameter to set a z-coordinate for the\n",
"top of the peak. Optionally use the `flat` parameter to create a plateau\n",
"at the top of the peak. Using the default linear growth and decay\n",
"function $z = z_0 - r \\sqrt{\\Delta x^2 + \\Delta y^2}$, set the `rate` to\n",
"function $z = z_0 - r \\sqrt{\\Delta x^2 + \\Delta y^2}$, \n",
"set the `linear` slope parameter to\n",
"0.5 to model a 50 percent slope."
]
},
Expand All @@ -196,7 +197,7 @@
" coordinates=[400, 100],\n",
" z=25,\n",
" flat=25,\n",
" rate=0.5\n",
" linear=0.5\n",
" )\n",
"\n",
"# Visualize\n",
Expand Down Expand Up @@ -248,7 +249,7 @@
" coordinates=[400, 100],\n",
" z=-25,\n",
" flat=25,\n",
" rate=0.5\n",
" linear=0.5\n",
" )\n",
"\n",
"# Visualize\n",
Expand Down Expand Up @@ -298,7 +299,7 @@
" coordinates=[350, 100, 450, 100],\n",
" z=[-25, 25],\n",
" flat=25,\n",
" rate=0.5\n",
" linear=0.5\n",
" )\n",
"\n",
"# Visualize\n",
Expand Down Expand Up @@ -365,7 +366,7 @@
" earthworks=\"earthworks\",\n",
" operation=\"fill\",\n",
" raster=\"random\",\n",
" rate=0.25,\n",
" linear=0.25,\n",
" flat=25\n",
" )\n",
"\n",
Expand Down
31 changes: 18 additions & 13 deletions content/tutorials/earthworks/basics.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,14 +187,15 @@ Use the `z` parameter to set a z-coordinate for the top of the peak.
Optionally use the `flat` parameter to create a plateau at the top of the peak.
Using the default linear growth and decay function
$z = z_0 - r \sqrt{\Delta x^2 + \Delta y^2}$,
set the `rate` to 0.5 to model a 50 percent slope.
set the `linear` slope parameter to 0.5
to model a 50 percent slope.

::: {.panel-tabset group="language"}

## Command line

```{bash}
r.earthworks elevation=elevation earthworks=peak operation=fill coordinates=400,100 z=25 flat=25 rate=0.5
r.earthworks elevation=elevation earthworks=peak operation=fill function=linear linear=0.5 coordinates=400,100 z=25 flat=25
```

## Python
Expand All @@ -206,10 +207,11 @@ gs.run_command(
elevation="elevation",
earthworks="peak",
operation="fill",
function="linear",
linear=0.5,
coordinates=[400, 100],
z=25,
flat=25,
rate=0.5
flat=25
)

# Visualize
Expand Down Expand Up @@ -239,7 +241,7 @@ then the slopes will climb at a given rate of growth.
## Command line

```{bash}
r.earthworks elevation=elevation earthworks=pit operation=cut coordinates=400,100 z=-25 flat=25 rate=0.5
r.earthworks elevation=elevation earthworks=pit operation=cut function=linear linear=0.5 coordinates=400,100 z=-25 flat=25
```

## Python
Expand All @@ -251,10 +253,11 @@ gs.run_command(
elevation="elevation",
earthworks="pit",
operation="cut",
function="linear",
linear=0.5,
coordinates=[400, 100],
z=-25,
flat=25,
rate=0.5
flat=25
)

# Visualize
Expand All @@ -281,7 +284,7 @@ and another z-coordinate for the top of the peak.
## Command line

```{bash}
r.earthworks elevation=elevation earthworks=pit_and_peak operation=cutfill coordinates=350,100,450,100 z=-25,25 flat=25 rate=0.5
r.earthworks elevation=elevation earthworks=pit_and_peak operation=cutfill function=linear linear=0.5 coordinates=350,100,450,100 z=-25,25 flat=25
```

## Python
Expand All @@ -293,10 +296,11 @@ gs.run_command(
elevation="elevation",
earthworks="pit_and_peak",
operation="cutfill",
function="linear",
linear=0.5,
coordinates=[350, 100, 450, 100],
z=[-25, 25],
flat=25,
rate=0.5
flat=25
)

# Visualize
Expand Down Expand Up @@ -335,7 +339,7 @@ Set input raster to the random cells.
```{bash}
r.surf.random out=surface min=0 max=25 seed=2
r.random input=surface npoints=50 raster=random seed=7
r.earthworks elevation=elevation earthworks=earthworks operation=fill raster=random rate=0.25 flat=25
r.earthworks elevation=elevation earthworks=earthworks operation=fill raster=random function=linear linear=0.25 flat=25
```

## Python
Expand All @@ -360,7 +364,8 @@ gs.run_command(
earthworks="earthworks",
operation="fill",
raster="random",
rate=0.25,
function="linear",
linear=0.25,
flat=25
)

Expand Down Expand Up @@ -401,4 +406,4 @@ m.show()

:::

![Contours](images/basics_06.webp)
![Contours](images/basics_06.webp)
4 changes: 1 addition & 3 deletions content/tutorials/earthworks/earthworks.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,7 @@ execute:

![Random fill operation with r.earthworks](images/earthworks_01.webp)

Learn how model terrain with {{< meta links.r_earthworks >}}. With this tool you can generate new terrain or modify existing terrain using cut and fill operations inspired by earthworking. The first tutorial on the basics of terrain modeling introduces key concepts such as cut and fill operations. The subsequent tutorials introduce more advanced concepts such as relative operations and growth and decay functions. These tutorials demonstrate how to generate terrain, model natural landforms, and model anthropogenic landforms - i.e. earthworks - such as roads, dams, and levees. Read our [paper](https://raw.githubusercontent.com/baharmon/r.earthworks/main/paper/paper.pdf) to learn more.

<!-- Update link when paper published -->
Learn how model terrain with {{< meta links.r_earthworks >}}. With this tool you can generate new terrain or modify existing terrain using cut and fill operations inspired by earthworking. The first tutorial on the basics of terrain modeling introduces key concepts such as cut and fill operations. The subsequent tutorials introduce more advanced concepts such as relative operations and growth and decay functions. These tutorials demonstrate how to generate terrain, model natural landforms, and model anthropogenic landforms - i.e. earthworks - such as roads, dams, and levees. Read our [paper](https://raw.githubusercontent.com/baharmon/r.earthworks/main/paper/paper.pdf) to learn more.

## Installation

Expand Down
4 changes: 2 additions & 2 deletions content/tutorials/earthworks/gullies.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -285,7 +285,7 @@
"and decay function $z = z_0 e^{-\\lambda \\sqrt{\\Delta x^2 + \\Delta y^2}}$\n",
"to model the steep slopes of the gullies. Set `mode` to relative,\n",
"`operation` to cut, `function` to exponential, `raster` to the raster\n",
"map of gullies, `z` to a negative value, and `rate` $\\lambda$ to a value\n",
"map of gullies, `z` to a negative value, and `exponential` $\\lambda$ to a value\n",
"such as 0.1. Save an output `volume` raster to visualize volumetric\n",
"change. This may take a minute to run. For faster results, try setting a\n",
"lower resolution with\n",
Expand All @@ -309,7 +309,7 @@
" operation=\"cut\",\n",
" function=\"exponential\",\n",
" raster=\"gullies\",\n",
" rate=0.1\n",
" exponential=0.1\n",
" )\n",
"gs.run_command(\"r.colors\", map=\"volume\", color=\"inferno\")\n",
"\n",
Expand Down
8 changes: 4 additions & 4 deletions content/tutorials/earthworks/gullies.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -305,7 +305,7 @@ Set `mode` to relative,
`operation` to cut,
`function` to exponential,
`raster` to the raster map of gullies,
and `rate` $\lambda$ to a value such as 0.1.
and `exponential` $\lambda$ to a value such as 0.1.
Save an output `volume` raster
to visualize volumetric change.
This may take a minute to run.
Expand All @@ -317,7 +317,7 @@ with {{< meta links.g_region >}}.
## Command line

```{bash}
r.earthworks elevation=fractal earthworks=gullies volume=volume mode=relative operation=cut function=exponential raster=gullies rate=0.1 --overwrite
r.earthworks elevation=fractal earthworks=gullies volume=volume mode=relative operation=cut function=exponential raster=gullies exponential=0.1 --overwrite
r.colors map=volume color=inferno
```

Expand All @@ -334,7 +334,7 @@ gs.run_command(
operation="cut",
function="exponential",
raster="gullies",
rate=0.1
exponential=0.1
)
gs.run_command("r.colors", map="volume", color="inferno")

Expand All @@ -355,4 +355,4 @@ m.show()

![Gullies](images/gullies_03.webp)

![Volumetric change](images/gullies_04.webp)
![Volumetric change](images/gullies_04.webp)
18 changes: 9 additions & 9 deletions content/tutorials/earthworks/levees.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -376,7 +376,7 @@
"north. Then use a cut operation with\n",
"[r.earthworks](https://grass.osgeo.org/grass-stable/manuals/addons/r.earthworks.html)\n",
"to model the borrow area. Set `elevation` to the elevation raster,\n",
"`lines` to the borrow vector, `z` to -1.5, `rate` to 0.2, and `flat` to\n",
"`lines` to the borrow vector, `z` to -1.5, `linear` to 0.2, and `flat` to\n",
"7.6."
]
},
Expand All @@ -398,7 +398,7 @@
" operation=\"cut\",\n",
" lines=\"borrow\",\n",
" z=[-1.5],\n",
" rate=0.2,\n",
" linear=0.2,\n",
" flat=7.6\n",
" )\n",
"\n",
Expand Down Expand Up @@ -430,7 +430,7 @@
"Use a fill operation with\n",
"[r.earthworks](https://grass.osgeo.org/grass-stable/manuals/addons/r.earthworks.html)\n",
"to model the restored ridge. Set `elevation` to the earthworks raster,\n",
"`lines` to the ridge vector, `z` to 1.5, `rate` to 0.2, and `flat` to\n",
"`lines` to the ridge vector, `z` to 1.5, `linear` to 0.2, and `flat` to\n",
"7.6."
]
},
Expand All @@ -449,7 +449,7 @@
" operation=\"fill\",\n",
" lines=\"ridges\",\n",
" z=1.5,\n",
" rate=0.2,\n",
" linear=0.2,\n",
" flat=7.6\n",
" )\n",
"\n",
Expand Down Expand Up @@ -485,7 +485,7 @@
"with a ratio of 10H:1V. For\n",
"[r.earthworks](https://grass.osgeo.org/grass-stable/manuals/addons/r.earthworks.html)\n",
"set `elevation` to the earthworks raster, `lines` to the levee vector,\n",
"`z` to 5.5, `rate` to 0.1, and `flat` to 1.5."
"`z` to 5.5, `linear` to 0.1, and `flat` to 1.5."
]
},
{
Expand All @@ -503,7 +503,7 @@
" operation=\"fill\",\n",
" lines=\"levees\",\n",
" z=5.5,\n",
" rate=0.1,\n",
" linear=0.1,\n",
" flat=1.5\n",
" )\n",
"\n",
Expand Down Expand Up @@ -539,7 +539,7 @@
"built from rows of interlocking vertical segments \n",
"of piles that are driven into the ground. \n",
"Set `elevation` to the\n",
"earthworks raster, `lines` to the gaps vector, `z` to -0.6, `rate` to 1,\n",
"earthworks raster, `lines` to the gaps vector, `z` to -0.6, `linear` to 1,\n",
"and `flat` to 10. The radius of flats should be set to the region\n",
"resolution to ensure that the gaps are fully closed because we test our\n",
"design with a flood simulation. To better visualize the results, use\n",
Expand All @@ -563,7 +563,7 @@
" operation=\"cutfill\",\n",
" lines=\"gaps\",\n",
" z=-0.6,\n",
" rate=1,\n",
" linear=1,\n",
" flat=10\n",
" )\n",
"\n",
Expand All @@ -575,7 +575,7 @@
" operation=\"cutfill\",\n",
" lines=\"closures\",\n",
" z=1.37,\n",
" rate=1,\n",
" linear=1,\n",
" flat=5\n",
" )\n",
"\n",
Expand Down
Loading
Loading