GMT-like shaded relief illumination via view.py --dem-blend (#1089)

Rather than plotting DEM in the background and overlaying the data with transparency, I attempt to view data with color adjusted by the shaded relief DEM when provided. Just like `gmt grdimage -I` option. Hereafter, I call this DEM-blended data.

This can be done via `matplotlib.colors.LightSource.shade_rgb()` module (as opposed to what has been used in MintPy, i.e., the `shade()` module, that only produces the shaded relief of the DEM itself). This PR adds this support for the single-subplot scenario via changes in `view.plot_slice()`, the multi-subplot scenarios are not supported.

Detailed changes in MintPy code are as follows:

+ `utils.arg_utils.add_dem_argument()`: add the following new options to allow users to activate and tune the DEM-blended data plotting: `--dem-blend`, `--blend-mode`, `--shade-frac` and `--base-color`

+ `utils.plot.py`:
   - add `prep_blend_image()` to prepare the illuminated RGB array from a given data and DEM
   - add `plot_blend_image()` to call `prep_blend_image()` and `imshow` for plotting
   - add `blend_colorbar()` to create a DEM-blended colorbar, to be called within `plot_colorbar()`
   - `plot_colorbar()`: add generic customization support for the DEM-blended colorbar from `blend_colorbar()`
   - rename: `prepare_dem_background()` --> `prep_dem_background()`

+ `cli.view.cmd_line_parse()`: add checkings for `--dem-blend` option
    - turn off the disp_dem_shade option
    - check the existence of `--dem` option

+ `view.plot_slice()`: call `plot.plot_blend_image()` for the DEM-blended style.

TODO: we could add the resampling capability in plot_blend_image(), to handle the different resolution between data and DEM.

---------

Co-authored-by: Zhang Yunjun <[email protected]>

src/mintpy/cli/view.py

@@ -143,6 +143,12 @@ def cmd_line_parse(iargs=None):
     if inps.flip_lr or inps.flip_ud:
         inps.auto_flip = False
 
+    if inps.disp_dem_blend:
+        inps.disp_dem_shade = False
+        # --dem-blend option requires --dem option
+        if inps.dem_file is None:
+            parser.error("--dem-blend requires -d/-dem.")
+
     # check: conflicted options (geo-only options if inpput file is in radar-coordinates)
     geo_opt_names = ['--coord', '--show-gps', '--coastline', '--lalo-label', '--lalo-step', '--scalebar', '--faultline']
     geo_opt_names = list(set(geo_opt_names) & set(inps.argv))

src/mintpy/utils/arg_utils.py

@@ -104,29 +104,43 @@ def add_dem_argument(parser):
                      help='do not show DEM shaded relief')
     dem.add_argument('--dem-nocontour', dest='disp_dem_contour', action='store_false',
                      help='do not show DEM contour lines')
+    dem.add_argument('--dem-blend', dest='disp_dem_blend', action='store_true',
+                     help='blend the DEM shade with input image to have a GMT-like impression.')
 
-    dem.add_argument('--contour-smooth', dest='dem_contour_smooth', type=float, default=3.0,
-                     help='Background topography contour smooth factor - sigma of Gaussian filter. \n'
+    # DEM contours
+    dem.add_argument('--contour-smooth', dest='dem_contour_smooth', type=float, default=3.0, metavar='NUM',
+                     help='[Contour] Topography contour smooth factor - sigma of Gaussian filter. \n'
                           'Set to 0.0 for no smoothing; (default: %(default)s).')
     dem.add_argument('--contour-step', dest='dem_contour_step', metavar='NUM', type=float, default=200.0,
-                     help='Background topography contour step in meters (default: %(default)s).')
+                     help='[Contour] Topography contour step in meters (default: %(default)s).')
     dem.add_argument('--contour-lw','--contour-linewidth', dest='dem_contour_linewidth',
                      metavar='NUM', type=float, default=0.5,
-                     help='Background topography contour linewidth (default: %(default)s).')
+                     help='[Contour] Topography contour linewidth (default: %(default)s).')
 
+    # DEM shade
     dem.add_argument('--shade-az', dest='shade_azdeg', type=float, default=315., metavar='DEG',
-                     help='The azimuth (0-360, degrees clockwise from North) of the light source '
+                     help='[Shade] Azimuth angle (0-360, degrees clockwise from North) of the light source '
                           '(default: %(default)s).')
     dem.add_argument('--shade-alt', dest='shade_altdeg', type=float, default=45., metavar='DEG',
-                     help='The altitude (0-90, degrees up from horizontal) of the light source '
+                     help='[Shade] Altitude (0-90, degrees up from horizontal) of the light source '
                           '(default: %(default)s).')
-
     dem.add_argument('--shade-min', dest='shade_min', type=float, default=-4000., metavar='MIN',
-                     help='The min height in m of colormap of shaded relief topography (default: %(default)s).')
+                     help='[Shade] Minimum height of shaded relief topography (default: %(default)s m).')
     dem.add_argument('--shade-max', dest='shade_max', type=float, default=999., metavar='MAX',
-                     help='The max height of colormap of shaded relief topography (default: max(DEM)+2000).')
-    dem.add_argument('--shade-exag', dest='shade_exag', type=float, default=0.5,
-                     help='Vertical exaggeration ratio (default: %(default)s).')
+                     help='[Shade] Maximum height of shaded relief topography (default: max(DEM)+2000 m).')
+    dem.add_argument('--shade-exag', dest='shade_exag', type=float, default=0.5,  metavar='NUM',
+                     help='[Shade] Vertical exaggeration ratio (default: %(default)s).')
+
+    # DEM-blended image
+    dem.add_argument('--shade-frac', dest='shade_frac', type=float, default=0.5, metavar='NUM',
+                     help='[Blend] Increases/decreases the contrast of the hillshade (default: %(default)s).')
+    dem.add_argument('--base-color', dest='base_color', type=float, default=0.9, metavar='NUM',
+                     help='[Blend] Topograhpy basemap greyish color ranges in [0,1] (default: %(default)s).')
+    dem.add_argument('--blend-mode', dest='blend_mode', type=str, default='overlay',
+                     choices={'hsv','overlay','soft'}, metavar='STR',
+                     help='[Blend] Type of blending used to combine the colormapped data with illumated '
+                          'topography.\n(choices: %(choices)s; default: %(default)s).\n'
+                          'https://matplotlib.org/stable/gallery/specialty_plots/topographic_hillshading.html')
     return parser
 
 
@@ -277,8 +291,8 @@ def add_map_argument(parser):
     mapg.add_argument('--coastline', dest='coastline', type=str, choices={'10m', '50m', '110m'},
                       help="Draw coastline with specified resolution (default: %(default)s).\n"
                            "This will enable --lalo-label option.\n"
-                           "Link: https://scitools.org.uk/cartopy/docs/latest/matplotlib/geoaxes.html"
-                           "#cartopy.mpl.geoaxes.GeoAxes.coastlines")
+                           "https://scitools.org.uk/cartopy/docs/latest/reference/generated/"
+                           "cartopy.mpl.geoaxes.GeoAxes.html")
     mapg.add_argument('--coastline-lw', '--coastline-linewidth', dest='coastline_linewidth',
                       metavar='NUM', type=float, default=1,
                       help='Coastline linewidth (default: %(default)s).')