Expand 3-D basemap properties with back-walls and gridlines (#3993)

* Enable painting the xz and yz back-walls in 3-D

let +g set xy plan color, while +x and +y optionally set the other two side.

* Allow the 3-D box not to be plotted on top of figure

Until now, the +b did twh things: Turned on 3-D backwalls if gridlines were requested and draw the 3-D box, sometimes overprinting the main illustration.  This PR adds +B as an alternative.  Same as +b but does not draw the 3-D box outline.

* Switch +B to +w instead for "wall"

* Better parsing and checking for +x +y

* Add back-wall pen option via +w[pen]

* Add option to paint back walls

* Clean up code

* Ensure 3-D title on top

* Finalize xz and yz gridlines

* Fix docs

* typos

* Let wall outline cover up any gridlines in the same place

* Implicitly set +w if z-gridlines selected

* Draw portal, not box for backwall outlines

* let +g set all, while adding +x|y|z for individual control

* update docs

* Ensure +b sets the wall

* Adjust gridline spacing

Let the annotation interval always be the auto gridline spacing, and make first-orer allowances for perspective view when selecting the "width" of the axes.

* Revert gridline choice for now

* Address meaning of +x +y and set above/below annotation for z-axis

* remove printstatement

* Separate 3-D box lines from wall drawing

* Update gmtparse_B_arg_inspector for new +i,w,x,y,z modifiers

* Update module lists

* Revert "Update module lists"

This reverts commit 8246898.

Co-authored-by: Paul Wessel <pwessel@hawaii.edu>

doc/rst/source/cookbook/options.rst

@@ -287,23 +287,27 @@ tick, and gridline intervals, axes labels, and annotation units.
 
 The Frame settings are specified by
 
--  **-B**\ [*axes*][**+b**][**+g**\ *fill*][**+i**\ [*val*]][**+n**][**+o**\ *lon/lat*][**+t**\ *title*]
+-  **-B**\ [*axes*][**+b**][**+g**\ *fill*][**+i**\ [*val*]][**+n**][**+o**\ *lon/lat*][**+t**\ *title*][**+w**\ [*pen*]][**+x**\ *fill*][**+y**\ *fill*][**+z**\ *fill*]
 
 Here, the optional *axes* dictates which of the axes should be drawn
-and possibly annotated.  By default, all 4 map boundaries (or plot axes)
+and possibly annotated.  By default, all four map boundaries (or plot axes)
 are plotted (denoted **W**, **E**, **S**, **N**). To change this selection,
 append the codes for those you want (e.g., **WSn**). In this example,
 the lower case **n** denotes to draw the axis and (major and minor) tick
 marks on the "northern" (top) edge of the plot. The upper case **WS** will
 annotate the "western" and "southern" axes with numerals and plot the
 any axis labels in addition to draw axis/tick-marks.  For 3-D plots you can
-also specify **Z** or **z**.  By default a single vertical axes will then be
+also specify **Z** or **z**.  To *just* draw an axis without annotation and
+ticks you can use the **l**\ (eft), **r**\ (ight), **b**\ (ottom), **t**\ (op)
+and (for 3-D) **u**\ (p) codes. By default, a single vertical axes will then be
 plotted at the most suitable map corner.  You can override this by appending
 any combination of corner ids **1234**, where **1** represents the lower left
-corner and the order goes counter-clockwise.  Append **+b** to draw the outline
-of the 3-D box defined by **-R**; this modifier is also needed to display
-gridlines in the x–z, y–z planes.  You may paint the
-map canvas by appending the **+g**\ *fill* modifier [Default is no fill].
+corner and the order goes counter-clockwise.  Use **+w** to draw the outlines of
+the x-z and y-z planes [no outlines] and optionally append the *pen* to use
+[:term:`MAP_GRID_PEN_PRIMARY`]. Alternatively, append **+b** to also draw the front lines
+of the 3-D cube defined by **-R**.  You can paint the interior of the canvas with
+**+g**\ *fill* (this also sets fill for the two back-walls in 3-D).
+Use **+x**, **+y**, and **+z** to control the painting of planes *yz*, *xz* and *xy*, respectively [Default is no fill].
 Use **+i** to annotate an internal meridian or parallel when the axis that normally
 would be drawn and annotated does not exist (e.g., azimuthal map with 360-degree range
 has no latitude axis, and a global Hammer map has no longitude axis);

doc/rst/source/explain_-B_full.rst_

@@ -3,22 +3,24 @@
 **-B**\ [**p**\|\ **s**]\ *parameters*
     Set map Frame and Axes parameters. The Frame parameters are specified by
 
-    **-B**\ [*axes*][**+b**][**+g**\ *fill*][**+i**\ [*val*]][**+n**][**+o**\ *lon/lat*][**+t**\ *title*]
+    **-B**\ [*axes*][**+b**][**+g**\ *fill*][**+i**\ [*val*]][**+n**][**+o**\ *lon/lat*][**+t**\ *title*][**+w**\ [*pen*]][**+x**\ *fill*][**+y**\ *fill*][**+z**\ *fill*]
 
-    where *axes* selects which axes to plot. By default, all 4 map boundaries
+    where *axes* selects which axes to plot. By default, all four map boundaries
     (or plot axes) are plotted (named **W**, **E**, **S**, **N**). To customize,
     append the codes for those you want (e.g., **WSn**). Upper case means plot
     and annotate while lower case just plots and ticks the specified axes.
     To *just* draw an axis without annotation and ticks you can use the **l**\ (eft),
-    **r**\ (ight), **b**\ (ottom), **t**\ (opt) and (for 3-D) **u**\ (p) codes. If a 3-D basemap
-    is selected with **-p** and **-Jz**, append **Z**, **z**, or **u** to control the
-    appearance of the vertical axis. By default a single vertical axes will be
-    plotted at the most suitable map corner. Override the default by appending
+    **r**\ (ight), **b**\ (ottom), **t**\ (op) and (for 3-D) **u**\ (p) codes.
+    If a 3-D basemap is selected with **-p** and **-Jz**, append **Z**, **z**, or
+    **u** to control the appearance of the vertical axis. By default a single vertical
+    axes will be plotted at the most suitable map corner. Override the default by appending
     any combination of corner ids **1234**, where **1** represents the lower left
-    corner and the order goes counter-clockwise. Append **+b** to draw the outline of the 3-D
-    cube defined by **-R**; this modifier is also needed to display gridlines in
-    the x-z, y-z planes. Note that for 3-D views the title, if given, will be
-    suppressed. You can paint the interior of the canvas with **+g**\ *fill*.
+    corner and the order goes counter-clockwise.  Use **+w** to draw the outlines of
+    the x-z and y-z planes [no outline] and optionally append the *pen* to use
+    [:term:`MAP_GRID_PEN_PRIMARY`]. Alternatively, append **+b** to also draw the front lines
+    of the 3-D cube defined by **-R**. You can paint the interior of the canvas with
+    **+g**\ *fill* (this also sets fill for the two back-walls in 3-D).
+    Use **+x**, **+y**, and **+z** to control the painting of planes *yz*, *xz* and *xy*, respectively [Default is no fill]. 
     Use **+i** to annotate an internal meridian or parallel when the axis that normally
     would be drawn and annotated does not exist (e.g., azimuthal map with 360-degree range
     has no latitude axis, and a global Hammer map has no longitude axis); optionally append the parallel or meridian [0].