Skip to content

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
Fill operation 3D fill operation

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 operation 3D cut operation

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
Cut-fill operation 3D cut-fill operation

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
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
Dam Dam Breach

REFERENCES

Harmon, B. (2025). r.earthworks (Version 2.0.0) [Computer software]. https://doi.org/10.5281/zenodo.15507392

AUTHORS

Brendan Harmon

SOURCE CODE

Available at: r.earthworks source code (history)
Latest change: Wednesday Aug 13 09:11:06 2025 in commit fe13de2