Allow the use of a separate file for shading (grdimage -I)

The gmt command grdimage has an option -I that adds shading to another image by modulating the intensity. Historically, (up until gmt v5), this command has only taken as an option another grd filename. One common use of this feature was to plot something like a gravity, the geoid, or magnetic field in color, and then apply shading using a topography file to provide geologic context.

Since gmt 5, there has been the option of using the input grd file along with grdgradient to automatically generate an intensity file that would be used with the -I command. I believe that pygmt only accepts the option shading=True which automatically generates such an intensity file using gmt defined default illumination angle parameters.

I am asking that pygmt fully implement the grdimage -I option. This is the only feature that I am currently missing in pygmt, and which is forcing me to use both gmt and pygmt separately to generate publication quality images for journal articles.

For reference, here is the relevant part of the gmt grdimage man page:

	-I Apply directional illumination. Append name of intensity grid file.
	   For a constant intensity (i.e., change the ambient light), append a value.
	   To derive intensities from <grd_z> instead, append +a<azim> [-45], +n<method> [t1], and +m<ambient> [0]
	   or use -I+d to accept the default values (see grdgradient for details).

[seisman]

It seems that the upstream GMT PR https://github.com/GenericMappingTools/gmt/pull/4328 also fixes this issue.

Running @weiji14’s script above gives me a plot which looks correct (with the GMT master branch version: 6.2.0_8a4275f_2020.10.14):

But we need some more tests.

[weiji14]

However, the grdimage shading with a xarray.DataArray has known upstream bugs (see #750 (comment), #750 (comment), and GenericMappingTools/gmt#5294).

I’m reopening this issue to better track the upstream bug.

The last bits of the upstream CPT stretching issue (https://github.com/GenericMappingTools/gmt/issues/5294) should be fixed with https://github.com/GenericMappingTools/gmt/pull/5947 and https://github.com/GenericMappingTools/gmt/pull/5948 (thanks Meghan and Paul!) and will be available in GMT 6.3.

I’ve opened a GMT conda-forge dev build at https://github.com/conda-forge/gmt-feedstock/pull/173 which will contain these patches, and allow us to test things easily using conda install -c conda-forge/label/dev gmt. So we should be able to close this issue once PyGMT bumps the minimum GMT version to 6.3, and the xfail is removed from the test below:

https://github.com/GenericMappingTools/pygmt/blob/5dc135b3d789c842c959c9abbdb505b07011a68e/pygmt/tests/test_grdimage.py#L120-L125

The test is currently XPASS at https://github.com/GenericMappingTools/pygmt/runs/4111894254?check_suite_focus=true#step:15:295 😁