Skip to content

r.dem.change

DoD computation with cleanup, LoD masking, and volumetric summary

r.dem.change [-nk] [dem=name] [reference=name] [dod=name] lod=name [output_dod=name] output_sig=name [volume_csv=name] [trim_percentile=float] [stable_mask=name] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.dem.change dod=name lod=name output_sig=name

grass.tools.Tools.r_dem_change(dem=None, reference=None, dod=None, lod, output_dod=None, output_sig, volume_csv=None, trim_percentile=None, stable_mask=None, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_dem_change(dod="name", lod="name", output_sig="name")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

grass.script.run_command("r.dem.change", dem=None, reference=None, dod=None, lod, output_dod=None, output_sig, volume_csv=None, trim_percentile=None, stable_mask=None, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.dem.change", dod="name", lod="name", output_sig="name")

Parameters

dem=name
    Post-event DEM (co-registered); requires reference
reference=name
    Reference DEM; requires dem
dod=name
    Precomputed (e.g. debiased) DEM of Difference; alternative to dem+reference
lod=name [required]
    Level of Detection raster (from r.dem.lod or r.dem.errprop)
output_dod=name
    Raw DoD (dem - reference, no LoD masking); dem+reference path only
output_sig=name [required]
    Significant DoD (cells where |dh| > LoD)
volume_csv=name
    CSV output with erosion/deposition/net volumes
trim_percentile=float
    Trim |DoD| blunders above this percentile before thresholding
    Allowed values: 0-100
stable_mask=name
    Stable-terrain mask used to estimate the trim_percentile threshold (only used with trim_percentile)
-n
    Remove isolated significant cells (speckle) from the significant DoD
-k
    Report DoD distribution kurtosis (Fisher and Pearson)
--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

dem : str | np.ndarray, optional
    Post-event DEM (co-registered); requires reference
    Used as: input, raster, name
reference : str | np.ndarray, optional
    Reference DEM; requires dem
    Used as: input, raster, name
dod : str | np.ndarray, optional
    Precomputed (e.g. debiased) DEM of Difference; alternative to dem+reference
    Used as: input, raster, name
lod : str | np.ndarray, required
    Level of Detection raster (from r.dem.lod or r.dem.errprop)
    Used as: input, raster, name
output_dod : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Raw DoD (dem - reference, no LoD masking); dem+reference path only
    Used as: output, raster, name
output_sig : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
    Significant DoD (cells where |dh| > LoD)
    Used as: output, raster, name
volume_csv : str, optional
    CSV output with erosion/deposition/net volumes
    Used as: output, file, name
trim_percentile : float, optional
    Trim |DoD| blunders above this percentile before thresholding
    Allowed values: 0-100
stable_mask : str | np.ndarray, optional
    Stable-terrain mask used to estimate the trim_percentile threshold (only used with trim_percentile)
    Used as: input, raster, name
flags : str, optional
    Allowed values: n, k
    n
        Remove isolated significant cells (speckle) from the significant DoD
    k
        Report DoD distribution kurtosis (Fisher and Pearson)
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.

Raises:

grass.tools.ToolError: When the tool ended with an error.

dem : str, optional
    Post-event DEM (co-registered); requires reference
    Used as: input, raster, name
reference : str, optional
    Reference DEM; requires dem
    Used as: input, raster, name
dod : str, optional
    Precomputed (e.g. debiased) DEM of Difference; alternative to dem+reference
    Used as: input, raster, name
lod : str, required
    Level of Detection raster (from r.dem.lod or r.dem.errprop)
    Used as: input, raster, name
output_dod : str, optional
    Raw DoD (dem - reference, no LoD masking); dem+reference path only
    Used as: output, raster, name
output_sig : str, required
    Significant DoD (cells where |dh| > LoD)
    Used as: output, raster, name
volume_csv : str, optional
    CSV output with erosion/deposition/net volumes
    Used as: output, file, name
trim_percentile : float, optional
    Trim |DoD| blunders above this percentile before thresholding
    Allowed values: 0-100
stable_mask : str, optional
    Stable-terrain mask used to estimate the trim_percentile threshold (only used with trim_percentile)
    Used as: input, raster, name
flags : str, optional
    Allowed values: n, k
    n
        Remove isolated significant cells (speckle) from the significant DoD
    k
        Report DoD distribution kurtosis (Fisher and Pearson)
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

DESCRIPTION

r.dem.change computes a DEM of Difference (DoD) between a co-registered post-event DEM and a reference DEM, applies a Level of Detection (LoD) threshold to isolate significant change, and reports volumetric erosion, deposition, and net change. Optional cleanup stages remove gross blunders and isolated significant cells.

The pipeline is:

  1. Raw DoD: output_dod = dem - reference, the unmodified difference.
  2. Blunder trimming (optional, trim_percentile): cells whose absolute difference exceeds a percentile of |DoD| are dropped before thresholding. The threshold is estimated over stable_mask when supplied, and stable_mask requires trim_percentile (without it the mask has no effect and the parser rejects the combination), otherwise over the whole DoD.
  3. LoD thresholding: output_sig keeps cells where |DoD| exceeds the per-cell lod value (from r.dem.lod or r.dem.errprop).
  4. Speckle removal (optional, -n): isolated significant cells (no significant neighbour among the eight surrounding cells) are removed.
  5. Volumetric summary: erosion, deposition, and net volume in cubic metres (and cubic yards), optionally written to volume_csv.

With the -k flag the Fisher and Pearson kurtosis of the raw DoD distribution are reported as a diagnostic of noise and tail behavior.

A precomputed difference (typically the bias-corrected DoD from r.dem.bias) can be supplied via dod instead of dem and reference; volumes are then integrated over the corrected surface, and the input column of volume_csv records which raster was analyzed.

NOTES

The lod input is a per-cell raster, so a spatially varying Level of Detection from r.dem.lod (local mode) or r.dem.errprop can be used directly. A uniform LoD is simply a constant raster.

output_dod always holds the raw, unmodified difference. Blunder trimming and speckle removal affect only output_sig and the reported volumes, so the raw difference remains available for inspection.

On the dem plus reference path the difference has to be written somewhere, so output_dod is required there. It is rejected on the dod path, where the difference already exists and is analyzed as supplied.

Volumes are computed from significant cells only, using the current region cell size. Ensure the computational region matches the input DEM resolution.

The kurtosis diagnostic (-k) requires the Python scipy package.

EXAMPLES

The commands below use the example scene built in the r.dem toolset manual, which is derived from the North Carolina sample dataset. Build it there first.

Threshold the debiased difference against the detection limit and report volumes:

g.region raster=elev_lid792_1m

r.dem.change -n dod=dod_debiased lod=lod_filled \
    output_sig=dod_significant volume_csv=volumes.csv

The volumes can be checked against the volumes r.earthworks moved when the scene was built; they land within a few percent.

The -n flag matters here. Without it, noise that clears the detection limit by chance is counted as change, and on this scene that inflates both volumes by roughly ten percent. Speckle removal drops isolated cells, which real erosion and deposition are not.

Trim blunders on stable ground first, remove isolated significant cells, and report the distribution kurtosis as a noise diagnostic:

r.dem.change dod=dod_debiased lod=lod_local \
    output_sig=dod_significant_clean \
    trim_percentile=99 stable_mask=stable_terrain -n -k

On the dem plus reference path the raw difference has to be written, so output_dod is required:

r.dem.change dem=dsm_post reference=elev_lid792_1m lod=lod_global \
    output_dod=dod_uncorrected output_sig=dod_significant_raw

r.dem.change example
Figure: The known change added with r.earthworks, and the significant DoD recovered above the Level of Detection.

SEE ALSO

r.dem, r.dem.coregister, r.dem.errprop, r.dem.lod, r.neighbors, r.univar

AUTHORS

Corey T. White, Center for Geospatial Analytics, NC State University

SOURCE CODE

Available at: r.dem.change source code (history)
Latest change: Thursday Aug 20 19:32:37 2026 in commit d08d385