d.background: Add module for setting display background color (#2282)

d.background is just a wrapper around a simple d.erase call, but it has a name which is more relevant in the context of setting the background color. In other words, when setting a background color, the first call in the series of commands does not have to be d.erase anymore, but it can be d.background, i.e., you start with d.background, not d.erase.

d.mon wx0 does not support d.erase bgcolor, so d.background does not work either. In the main GUI, d.background works (only) as a command layer (same as for d.erase). In grass.jupyter, d.background removes the need for background parameter or set_background methods which is the original motivation for this module.

The color option is not defined using a standard option because the default is defined for the standard option and d.background cannot have a default color.

Example with an image is included.

scripts/Makefile

@@ -1,6 +1,7 @@
 MODULE_TOPDIR = ..
 
 SUBDIRS = \
+	d.background \
 	d.correlate \
 	d.frame \
 	d.out.file \

scripts/d.background/Makefile

@@ -0,0 +1,7 @@
+MODULE_TOPDIR = ../..
+
+PGM = d.background
+
+include $(MODULE_TOPDIR)/include/Make/Script.make
+
+default: script

scripts/d.background/d.background.html

@@ -0,0 +1,43 @@
+<h2>DESCRIPTION</h2>
+
+<em>d.background</em> will fill the image (or generally display monitor)
+with a single color specified by the <b>color</b> option.
+
+<h2>NOTES</h2>
+
+<em>d.background</em> is a frontend to <em>d.erase</em> and shares its limitations.
+Namely, it does not work with the wx monitors such as <code>d.mon wx0</code>.
+
+<h2>EXAMPLES</h2>
+
+In this example, the <em>streets_wake</em> map from the North Carolina sample
+location is displayed with custom background color (specified using HTML hex color code)
+using <em>cairo</em> display monitor (creates file called <em>map.png</em>):
+
+<div class="code"><pre>
+g.region vector=streets_wake
+d.mon cairo
+d.background color=#ADEFD1
+d.vect map=streets_wake color=#00203F legend_label="Streets"
+d.legend.vect -b at=70,30 title="Wake County"
+</pre></div>
+
+<!--
+image generated using the example above
+optipng -o5 map.png
+-->
+<center>
+<img src="d_background.png" alt="Street network with legend and background color">
+<p>
+Figure: Wake County street network with custom background color (North Carolina sample dataset)
+</center>
+
+<h2>SEE ALSO</h2>
+
+<em>
+<a href="d.erase.html">d.erase</a>
+</em>
+
+<h2>AUTHOR</h2>
+
+Vaclav Petras, <a href="https://geospatial.ncsu.edu/geoforall/">NCSU GeoForAll Lab</a>

scripts/d.background/d.background.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+
+############################################################################
+#
+# MODULE:    d.background
+# AUTHOR(S): Vaclav Petras
+# PURPOSE:   Uses d.his to drape a color raster over a shaded relief map
+# COPYRIGHT: (C) 2022 by Vaclav Petras and the GRASS Development Team
+#
+#                This program is free software under the GNU General Public
+#                License (>=v2). Read the file COPYING that comes with GRASS
+#                for details.
+#
+#############################################################################
+
+# %module
+# % description: Fills the graphics display frame with user defined color.
+# % keyword: display
+# % keyword: graphics
+# % keyword: background
+# % keyword: fill
+# % keyword: erase
+# %end
+# %option
+# % key: color
+# % type: string
+# % required: yes
+# % key_desc: name
+# % label: Background color
+# % description: Either a standard color name or R:G:B triplet
+# % gisprompt: old,color,color
+# %end
+
+
+import grass.script as gs
+
+
+def main():
+    options, unused = gs.parser()
+    color = options["color"]
+    gs.run_command("d.erase", bgcolor=color, errors="fatal")
+
+
+if __name__ == "__main__":
+    main()