d.explanation.plot
Draw a plot of multiple rasters to explain a raster operation for example a + b = c
d.explanation.plot a=name [b=name] [c=name] [d=name] [raster_font=string] [operator_ab=string] [operator_bc=string] [operator_cd=string] [operator_font=string] [label_a=string] [label_b=string] [label_c=string] [label_d=string] [label_font=string] [label_size=float] [bottom=float] [--verbose] [--quiet] [--qq] [--ui]
Example:
d.explanation.plot a=name
grass.script.run_command("d.explanation.plot", a, b=None, c=None, d=None, raster_font=None, operator_ab=None, operator_bc=None, operator_cd=None, operator_font=None, label_a=None, label_b=None, label_c=None, label_d=None, label_font=None, label_size=None, bottom=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("d.explanation.plot", a="name")
grass.tools.Tools.d_explanation_plot(a, b=None, c=None, d=None, raster_font=None, operator_ab=None, operator_bc=None, operator_cd=None, operator_font=None, label_a=None, label_b=None, label_c=None, label_d=None, label_font=None, label_size=None, bottom=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.d_explanation_plot(a="name")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
Parameters
a=name [required]
Name of input raster map
b=name
Name of input raster map
c=name
Name of input raster map
d=name
Name of input raster map
raster_font=string
Font for raster numbers
operator_ab=string
Operator between a and b
operator_bc=string
Operator between b and c
operator_cd=string
Operator between c and d
operator_font=string
Font for operators
label_a=string
Label above the raster
label_b=string
Label above the raster
label_c=string
Label above the raster
label_d=string
Label above the raster
label_font=string
Font for labels
label_size=float
Text size for labels
bottom=float
Offset from the bottom (percentage)
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
a : str, required
Name of input raster map
Used as: input, raster, name
b : str, optional
Name of input raster map
Used as: input, raster, name
c : str, optional
Name of input raster map
Used as: input, raster, name
d : str, optional
Name of input raster map
Used as: input, raster, name
raster_font : str, optional
Font for raster numbers
operator_ab : str, optional
Operator between a and b
operator_bc : str, optional
Operator between b and c
operator_cd : str, optional
Operator between c and d
operator_font : str, optional
Font for operators
label_a : str, optional
Label above the raster
label_b : str, optional
Label above the raster
label_c : str, optional
Label above the raster
label_d : str, optional
Label above the raster
label_font : str, optional
Font for labels
label_size : float, optional
Text size for labels
bottom : float, optional
Offset from the bottom (percentage)
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
a : str | np.ndarray, required
Name of input raster map
Used as: input, raster, name
b : str | np.ndarray, optional
Name of input raster map
Used as: input, raster, name
c : str | np.ndarray, optional
Name of input raster map
Used as: input, raster, name
d : str | np.ndarray, optional
Name of input raster map
Used as: input, raster, name
raster_font : str, optional
Font for raster numbers
operator_ab : str, optional
Operator between a and b
operator_bc : str, optional
Operator between b and c
operator_cd : str, optional
Operator between c and d
operator_font : str, optional
Font for operators
label_a : str, optional
Label above the raster
label_b : str, optional
Label above the raster
label_c : str, optional
Label above the raster
label_d : str, optional
Label above the raster
label_font : str, optional
Font for labels
label_size : float, optional
Text size for labels
bottom : float, optional
Offset from the bottom (percentage)
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 | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned.
Raises:
grass.tools.ToolError: When the tool ended with an error.
DESCRIPTION
d.explantion.plot creates a plot of rasters and their relations which can serve as an explanation of a raster operation performed by a module or function.
Up to four rasters are supported. The default operators assume rasters to have the following relation:
a + b -> c
EXAMPLES
Example using generated data
In Bash:
g.region n=99 s=0 e=99 w=0 rows=3 cols=3
r.mapcalc expression="a = rand(0., 5)" seed=1
r.mapcalc expression="b = rand(0., 5)" seed=2
r.mapcalc expression="c = rand(0., 5)" seed=3
r.series input=a,b,c output=d method=average
In Python:
import grass.jupyter as gj
plot = gj.Map(use_region=True, width=700, height=700)
plot.d_background(color="white")
plot.run("d.explanation.plot", a="a", b="b", c="c", d="d", operator_font="FreeMono:Regular")
plot.show()
Figure: Resulting image for r.series
Example using artificial data
r.in.ascii input=- output=input_1 <<EOF
north: 103
south: 100
east: 103
west: 100
rows: 3
cols: 3
5 * 9
* 5 *
* 5 5
EOF
r.in.ascii input=- output=input_2 <<EOF
north: 103
south: 100
east: 103
west: 100
rows: 3
cols: 3
3 4 4
2 2 2
2 1 1
EOF
r.colors map=input_1,input_2 color=viridis
g.region raster=input_1
r.patch input=input_1,input_2 output=result
d.mon wx0 width=400 height=400 output=r_patch.png
d.explanation.plot a=input_1 b=input_2 c=result
Figure: Resulting image for r.patch
KNOWN ISSUES
- Issue #3381 prevents
d.rast.num to be used with
d.mon cairo, sod.mon wx0needs to be used with this module. Using environmental variables for rendering directly or using tools such as Map from grass.jupyter avoids the issues. - Issue #3382 prevents
usage of centered text with
d.mon wx0, so the hardcoded values for text does not work perfectly. - Issue #3383 prevents
d.rast.num to be saved to the image with
d.mon wx0, taking screenshot is necessary (with a powerful screenshot tool, this also addresses the copping issue below). - The size of the display must be square to have rasters and their
cells as squares, e.g.,
d.mon wx0 width=400 height=400must be used. The image needs to be cropped afterwards, e.g. using ImageMagic'smogrify -trim image.png.
SEE ALSO
g.region, d.frame, d.rast.num, d.grid, d.mon, v.mkgrid
AUTHOR
Vaclav Petras, NCSU GeoForAll Lab
SOURCE CODE
Available at: d.explanation.plot source code
(history)
Latest change: Thursday Mar 20 21:36:57 2025 in commit 7286ecf