d.background: Add module for setting display background color

[wenzeslaus]

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).

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.

[wenzeslaus]

Feedback and further suggestions about the name, example, the idea are welcome.

This will play nicely with the rendering in Jupyter notebooks.

Binder link

[neteler]

The need of having a new module doing essentially the same as d.erase isn't entirely clear to me - I mainly think of the proliferation of new modules with marginal difference in functionality.

[wenzeslaus]

I agree that there is only a small difference in functionality, if any. The point of the module is really the different interface, rather than functionality, so the new feature is really the new interface. Hence, for me the question is same as always, is the new feature worth adding another module to core?

I think that the new name helps code authors find the intended function faster and that for the code readers the new name makes it obvious what is the most likely intention of the code author. With d.erase, fair questions to ask are: What is being erased here? Was there something before in the image? On the other hand, with d.background, one can clearly see that the code author is specifying background color.

The motivation is clarity and helping other places to treat the background in the same way as other code. The new classes for Jupyter kind of call for a clear way of setting background (although only TimeSeries renderer currently has that), but that would lead to a parameter (background) or a function (set_background). Internally, that would call d.erase, but than why to repeat that wrapping in every relevant case when the background can be treated the same as other display operations, i.e., with a module call? The issue with d.erase is the name, so calling would not lead to a nice interface.

Adding another module solves the issue for the rendering APIs in Jupyter: Background color is changed with a module call (no additional function or syntax) and the name is, in the context of display commands, as clear as "set background color" or its variations. A bonus feature here is that the new module is available in all other cases when display commands are used, so user scripts or any other wrappers can make use of the new module too.

Here are some example in different contexts:

In Documentation

Example how the two cases may look like in the documentation or a tutorial:

We only have d.erase

User can set the background color using d.erase with bgcolor option.

We have also d.background

User can set the background color using d.background with color option.

Or, given that color is the only and required parameter of d.background with an obvious name:

User can set the background color using d.background.

In Q&A

We only have d.erase

Q: How do I set background color?
A: Use d.erase with with bgcolor.

We have also d.background

Q: How do I set background color?
A: Use d.background.

Of course, my hope is that with the new module, the question is actually never asked, because the answer is obvious.

In Code

The following uses the first example from the basic_example_grass_jupyter.ipynb and adding setting of background color there. As a reader of the code (e.g., new contributor, learner), you may ask questions such as: What each line of the code is doing? What line is the one setting the background color?

Old Way: d.erase bgcolor="#333333"

gs.parse_command("g.region", raster="lakes", flags="pg")
gs.run_command("r.buffer", input="lakes", output="lakes_buff", distances=[60, 120, 240, 500])

# Start a GrassRenderer
img = gj.GrassRenderer()

# Add a raster and vector to the map
img.d_erase(bgcolor="#333333")
img.d_rast(map="lakes_buff")
img.d_legend(raster="lakes_buff", range=(2, 5), at=(80, 100, 2, 10))

# Display map
img.show()

New Way: d.background color="#333333"

gs.parse_command("g.region", raster="lakes", flags="pg")
gs.run_command("r.buffer", input="lakes", output="lakes_buff", distances=[60, 120, 240, 500])

# Start a GrassRenderer
img = gj.GrassRenderer()

# Add a raster and vector to the map
img.d_background(color="#333333")
img.d_rast(map="lakes_buff")
img.d_legend(raster="lakes_buff", range=(2, 5), at=(80, 100, 2, 10))

# Display map
img.show()

[wenzeslaus]

Any further opinions here?

For comparison, in Matplotlib has plt.figure(facecolor='#94F008'), ax.set_facecolor("#1CC4AF"), but also text.set_backgroundcolor(color='#94F008') and plt.style.use('dark_background').

Binder link

Screenshot: