r.earthworks
Terrain modeling with cut and fill operations
r.earthworks [-pd] elevation=name earthworks=name mode=string operation=string function=string [raster=name] [coordinates=east,north] [points=name] [lines=name] [z=float [,float,...]] [flat=float] [volume=name] [linear=float] [exponential=float] [logistic=float] [gaussian=float] [lorentz=float] [quadratic=float] [cubic=float] [threshold=float] [border=float] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.earthworks elevation=name earthworks=earthworks mode=absolute operation=cutfill function=linear raster=name
grass.script.run_command("r.earthworks", elevation, earthworks="earthworks", mode="absolute", operation="cutfill", function="linear", raster=None, coordinates=None, points=None, lines=None, z=0.0, flat=0.0, volume=None, linear=0.1, exponential=0.04, logistic=0.025, gaussian=25, lorentz=25, quadratic=0.001, cubic=0.00001, threshold=500, border=250, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("r.earthworks", elevation="name", earthworks="earthworks", mode="absolute", operation="cutfill", function="linear", raster="name")
grass.tools.Tools.r_earthworks(elevation, earthworks="earthworks", mode="absolute", operation="cutfill", function="linear", raster=None, coordinates=None, points=None, lines=None, z=0.0, flat=0.0, volume=None, linear=0.1, exponential=0.04, logistic=0.025, gaussian=25, lorentz=25, quadratic=0.001, cubic=0.00001, threshold=500, border=250, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.r_earthworks(elevation="name", earthworks="earthworks", mode="absolute", operation="cutfill", function="linear", raster="name")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
Parameters
elevation=name [required]
Input elevation raster
Input elevation raster
earthworks=name [required]
Output earthworks
Output elevation raster
Default: earthworks
mode=string [required]
Earthworking mode
Allowed values: relative, absolute
Default: absolute
relative: Relative to existing topography
absolute: At given elevation
operation=string [required]
Earthworking operation
Allowed values: cut, fill, cutfill
Default: cutfill
cut: Cut into topography
fill: Fill over topography
cutfill: Cut and fill
function=string [required]
Slope function
Allowed values: linear, exponential, logistic, gaussian, lorentz, quadratic, cubic
Default: linear
linear: linear decay function
exponential: Exponential decay function
logistic: Logistic function
gaussian: Gaussian function
lorentz: Cauchy-Lorentz distribution
quadratic: Quadratic function
cubic: Cubic function
raster=name
Input raster spot elevations
Input raster spot elevations
coordinates=east,north
Seed point coordinates
Seed point coordinates
points=name
Input points
Input points
lines=name
Input lines
Input lines
z=float [,float,...]
Elevation value
Elevation value
Default: 0.0
flat=float
Radius of flats
Radius of flats
Default: 0.0
volume=name
Output volume
Output volumetric change raster
linear=float
Linear slope
Linear slope
Default: 0.1
exponential=float
Exponential decay factor
Exponential decay factor
Default: 0.04
logistic=float
Logistic shape parameter
Logistic shape parameter
Default: 0.025
gaussian=float
Gaussian standard deviation
Gaussian standard deviation
Default: 25
lorentz=float
Cauchy-Lorentz scale parameter
Cauchy-Lorentz scale parameter
Default: 25
quadratic=float
Quadratic coefficient
Quadratic coefficient
Default: 0.001
cubic=float
Cubic coefficient
Cubic coefficient
Default: 0.00001
threshold=float
Threshold per quadrant
Threshold per quadrant
Default: 500
border=float
Border around quadrants
Border around quadrants
Default: 250
-p
Print volume
-d
Disable quadtree segmentation
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
elevation : str, required
Input elevation raster
Input elevation raster
Used as: input, raster, name
earthworks : str, required
Output earthworks
Output elevation raster
Used as: output, raster, name
Default: earthworks
mode : str, required
Earthworking mode
Allowed values: relative, absolute
relative: Relative to existing topography
absolute: At given elevation
Default: absolute
operation : str, required
Earthworking operation
Allowed values: cut, fill, cutfill
cut: Cut into topography
fill: Fill over topography
cutfill: Cut and fill
Default: cutfill
function : str, required
Slope function
Allowed values: linear, exponential, logistic, gaussian, lorentz, quadratic, cubic
linear: linear decay function
exponential: Exponential decay function
logistic: Logistic function
gaussian: Gaussian function
lorentz: Cauchy-Lorentz distribution
quadratic: Quadratic function
cubic: Cubic function
Default: linear
raster : str, optional
Input raster spot elevations
Input raster spot elevations
Used as: input, raster, name
coordinates : tuple[float, float] | list[float] | str, optional
Seed point coordinates
Seed point coordinates
Used as: input, coords, east,north
points : str, optional
Input points
Input points
Used as: input, vector, name
lines : str, optional
Input lines
Input lines
Used as: input, vector, name
z : float | list[float] | str, optional
Elevation value
Elevation value
Default: 0.0
flat : float, optional
Radius of flats
Radius of flats
Default: 0.0
volume : str, optional
Output volume
Output volumetric change raster
Used as: output, raster, name
linear : float, optional
Linear slope
Linear slope
Default: 0.1
exponential : float, optional
Exponential decay factor
Exponential decay factor
Default: 0.04
logistic : float, optional
Logistic shape parameter
Logistic shape parameter
Default: 0.025
gaussian : float, optional
Gaussian standard deviation
Gaussian standard deviation
Default: 25
lorentz : float, optional
Cauchy-Lorentz scale parameter
Cauchy-Lorentz scale parameter
Default: 25
quadratic : float, optional
Quadratic coefficient
Quadratic coefficient
Default: 0.001
cubic : float, optional
Cubic coefficient
Cubic coefficient
Default: 0.00001
threshold : float, optional
Threshold per quadrant
Threshold per quadrant
Default: 500
border : float, optional
Border around quadrants
Border around quadrants
Default: 250
flags : str, optional
Allowed values: p, d
p
Print volume
d
Disable quadtree segmentation
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
elevation : str | np.ndarray, required
Input elevation raster
Input elevation raster
Used as: input, raster, name
earthworks : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
Output earthworks
Output elevation raster
Used as: output, raster, name
Default: earthworks
mode : str, required
Earthworking mode
Allowed values: relative, absolute
relative: Relative to existing topography
absolute: At given elevation
Default: absolute
operation : str, required
Earthworking operation
Allowed values: cut, fill, cutfill
cut: Cut into topography
fill: Fill over topography
cutfill: Cut and fill
Default: cutfill
function : str, required
Slope function
Allowed values: linear, exponential, logistic, gaussian, lorentz, quadratic, cubic
linear: linear decay function
exponential: Exponential decay function
logistic: Logistic function
gaussian: Gaussian function
lorentz: Cauchy-Lorentz distribution
quadratic: Quadratic function
cubic: Cubic function
Default: linear
raster : str | np.ndarray, optional
Input raster spot elevations
Input raster spot elevations
Used as: input, raster, name
coordinates : tuple[float, float] | list[float] | str, optional
Seed point coordinates
Seed point coordinates
Used as: input, coords, east,north
points : str, optional
Input points
Input points
Used as: input, vector, name
lines : str, optional
Input lines
Input lines
Used as: input, vector, name
z : float | list[float] | str, optional
Elevation value
Elevation value
Default: 0.0
flat : float, optional
Radius of flats
Radius of flats
Default: 0.0
volume : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
Output volume
Output volumetric change raster
Used as: output, raster, name
linear : float, optional
Linear slope
Linear slope
Default: 0.1
exponential : float, optional
Exponential decay factor
Exponential decay factor
Default: 0.04
logistic : float, optional
Logistic shape parameter
Logistic shape parameter
Default: 0.025
gaussian : float, optional
Gaussian standard deviation
Gaussian standard deviation
Default: 25
lorentz : float, optional
Cauchy-Lorentz scale parameter
Cauchy-Lorentz scale parameter
Default: 25
quadratic : float, optional
Quadratic coefficient
Quadratic coefficient
Default: 0.001
cubic : float, optional
Cubic coefficient
Cubic coefficient
Default: 0.00001
threshold : float, optional
Threshold per quadrant
Threshold per quadrant
Default: 500
border : float, optional
Border around quadrants
Border around quadrants
Default: 250
flags : str, optional
Allowed values: p, d
p
Print volume
d
Disable quadtree segmentation
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
Returns:
result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None
will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.
DESCRIPTION
r.earthworks models new landforms using cut and fill operations to add and remove earth from an elevation raster. It can be used to model topographic forms such as hills, pits, ridges, valleys, roads, dams, and levees. In cut operations earth is excavated from the elevation raster, while in fill operations earth is deposited on the elevation raster. In absolute mode earth is added or removed until the specified elevation is reached, while in relative mode earth is added or removed by a height relative to the existing terrain. Slope is determined by a growth and decay function which can be set to linear, exponential, logistic, Gaussian, Cauchy-Lorentz, quadratic, or cubic and then parameterized.
Inputs
The key inputs for r.earthworks
are an existing elevation raster
and a set of x-, y-, and z-values
for the local minima and maxima
of the new landforms.
These values can be input as
coordinates
, points
, lines
, or a raster
.
For x- and y-coordinates, 2D points, and 2D lines,
an input elevation parameter z
must also be specified.
This z
parameter can be
a single constant value
or a list of values.
Other input parameters
for r.earthworks include
operation, mode, function, slope, and flats.
The operation
parameter can be set to
cut, fill, or cut-fill mode
to excavate, build, or excavate and build terrain.
The mode
parameter can be set to
absolute or relative mode
to use either zero or
the existing elevation as a datum.
In absolute mode, for example,
a road would cut through
or be built up on embankments over
the existing terrain,
while in relative mode
a road would adapt to the terrain.
The function
parameter can be set to
linear, exponential, logistic,
Gaussian, Cauchy-Lorentz,
quadratic, or cubic
to define the slope
from the local minima or maxima
to the existing terrain.
A slope parameter - either
linear
,
exponential
,
logistic
,
gaussian
,
lorentz
,
quadratic
, or
cubic
-
specifies the
rate of growth and decay
for a given slope function.
For example a linear slope function
with a rate of 0.1
will generate a constant 10 percent slope.
The flats
parameter specifies the radius
of constant elevation around local minima or maxima.
It can be used to model the flat surfaces
of topographic features such as
plateaus, lakes, roads, and levees.
Outputs
In addition to generating an earthworks
raster
with transformed elevation values,
r.earthworks can also calculate
the volume of cut and fill.
Set the output volume
raster
to generate a volumetric change raster.
Use the -p
flag
to print the net volume of cut and fill.
Quadtree Segmentation
To speed computation,
r.earthworks uses quadtree segmentation.
The computational region is recursively divided into quadrants
until each quadrant contains no more a given number of coordinates
defined by a threshold
parameter.
Quadtree segmentation limits earthworking operations
to quadrants containing input geometry.
Each segmented subregion is grown by a border
parameter
which has a default value of 250 map units.
If this border is not large enough,
then the earthworking operations may be incomplete
with artifacts along their edges.
If artifacts occur, then increase the size of the border.
A larger border, however, will increase computation time.
When the initial region contains a hundred thousand cells or more
and there are more input coordinates than the threshold,
quadtree segmentation is used by default,
but can be disabled with flag -d
.
When segmentation is not used,
it can take a long time to model extensive earthworks
for large regions with a million cells or more.
EXAMPLES
For more detailed instructions and examples, see the earthworks tutorial collection.
Cut & Fill Operations
Perform basic cut and fill operations to model peaks and pits from x- and y-coordinates.
Setup Set the computational region with g.region and then use map algebra to generate a flat terrain with r.mapcalc.
g.region n=500 s=0 e=500 w=0 res=1
r.mapcalc expression="elevation = 0"
Fill Operation Model a peak from a set of x- and y-coordinates with r.earthworks. 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.
r.earthworks elevation=elevation earthworks=peak operation=fill coordinates=250,250 z=50 function=linear linear=0.5 flat=50
Fill | Fill 3D |
---|---|
![]() |
![]() |
Cut Operation Model a pit from a set of x- and y-coordinates with r.earthworks. Set a z-coordinate for the bottom of the pit.
r.earthworks elevation=elevation earthworks=pit operation=cut coordinates=250,250 z=-50 function=linear linear=0.5 flat=50
Cut | Cut 3D |
---|---|
![]() |
![]() |
Cut & Fill Operation Model a pit and a peak from two sets of x- and y-coordinates with r.earthworks. Set a z-coordinate for the bottom of the pit and another z-coordinate for the top of the peak.
r.earthworks elevation=elevation earthworks=peak_and_pit operation=cutfill coordinates=180,180,320,320 z=-50,50 function=linear linear=0.5 flat=50
Cut & Fill | Cut & Fill 3D |
---|---|
![]() |
![]() |
Road Grading
Use a vector map of a road network
to grade a road crossing over a valley.
Start GRASS in the
North Carolina basic dataset.
First set the computation region with
g.region.
Then run r.earthworks
with input elevation set to elevation
,
input lines set to roadsmajor
,
z set to 95
,
operation set to fill
,
function set to linear
,
linear set to 0.25
,
and flat set to 25
.
This will grade an embankment through the valley
with a 50 meter wide roadway
at a constant elevation of 95 meters
with side slopes of 25 percent.
Optionally, compute contours with
r.contour.
g.region n=217700 s=216200 w=639200 e=640700 res=10
r.earthworks elevation=elevation earthworks=earthworks lines=roadsmajor z=95 function=linear linear=0.25 operation=fill flat=25
r.contour input=earthworks output=contours step=2
Elevation | Earthworks |
---|---|
![]() |
![]() |
When working with a large elevation raster, set the region to your area of interest to reduce computation time. This earthwork can be patched back into the original elevation raster. To do so, first set the region to the extent of the original elevation raster. Then run r.patch with the first input raster set to the earthwork raster and the second input raster set to the original elevation raster.
g.region raster=elevation
r.patch --overwrite input=earthworks,elevation output=elevation
Dam Breach Modeling
Model a flood due to a dam breach. Use r.earthworks to breach the dam and then use r.lake to model the maximum possible extent and depth of flooding.
g.region n=223740 s=222740 w=634450 e=635450 res=10
r.lake elevation=elevation water_level=104 lake=lake coordinates=635150.7489931877,223203.9595016748
r.earthworks elevation=elevation operation=cut coordinates=635235.4648198467,223210.9879314204 z=103 function=linear linear=0.5 flat=20
r.lake --overwrite elevation=earthworks water_level=104 lake=lake coordinates=635150.7489931877,223203.9595016748
Dam | Dam Breach |
---|---|
![]() |
![]() |
REFERENCES
Harmon, B. (2025). r.earthworks (Version 2.0.0) [Computer software]. https://doi.org/10.5281/zenodo.15507392
AUTHORS
SOURCE CODE
Available at: r.earthworks source code
(history)
Latest change: Wednesday Aug 13 09:11:06 2025 in commit fe13de2