Let data processors default to gridline reg for unspecified remote grids

.github/workflows/docs.yml

@@ -4,7 +4,7 @@
 name: Docs
 
 on:
-  # pull_request:
+  pull_request:
   push:
     branches:
       - master

.github/workflows/tests.yml

@@ -4,7 +4,7 @@
 name: Tests
 
 on:
-  # pull_request:
+  pull_request:
   push:
     branches:
       - master

doc/examples/ex52/ex52.sh

@@ -12,8 +12,8 @@ gmt begin ex52
   # Make a global grid with a smooth 2-degree transition across day/night boundary.
   gmt grdmath -Rd -I${res} -r $(gmt solar -C -o0:1 -I+d2000-06-22T24:00+z-10) 2 DAYNIGHT = w.grd
 
-  # We will create an intensity grid based on a DEM so that we can see structures in the oceans
-  gmt grdgradient @earth_relief_${res} -Nt0.5 -A45 -Gintens.grd
+  # We will create an intensity grid based on a pixel-registered DEM so that we can see structures in the oceans
+  gmt grdgradient @earth_relief_${res}_p -Nt0.5 -A45 -Gintens.grd
 
   # Blend the earth_day and earth_night geotiffs using the weights, so that when w is 1
   # we get the earth_day, and then adjust colors based on the intensity.

doc/examples/images.dvc

@@ -1,5 +1,5 @@
 outs:
-- md5: df85591c00343ed16310813c991db900.dir
-  size: 35020779
+- md5: 050dd52b0b4a7252c80ab0e3fadc40a8.dir
+  size: 35097918
   nfiles: 53
   path: images

doc/rst/source/datasets/remote-data.rst

@@ -38,12 +38,8 @@ and standardized their file names.  In GMT, you may access such data
    @remote_name_\ *rr*\ *u*\ [_\ *reg*\ ]
 
 where the leading @ symbol identifies the file as a remote data set, the *remote_name_* is specific
-to the dataset and the *rr* code is a 2-digit integer specifying the grid/image
-resolution in the unit *u*, where *u* is either **d**, **m** or **s** for arc degree, arc minute or
-arc second, respectively. Optionally, you can append _\ **g** or _\ **p** to specifically get the
-gridline-registered or pixel-registered version (if they both exist).  If *reg* is not specified we
-will return the pixel-registered version unless only the gridline-registered file is available.  If you
-do specify a specific registration and that version is not available you will get an error message.
+to the dataset and the *rr* code is a 2-digit integer specifying the grid/image resolution in the
+unit *u*, where *u* is either **d**, **m** or **s** for arc degree, arc minute or arc second, respectively.
 The codes for *rr*\ *u* and the optional *reg* that are supported will be listed in the sections
 below describing each of the available data sets.
 
@@ -61,6 +57,20 @@ Details about the remote datasets currently provided by GMT can be found at
 Many of the remote datasets have a preferred, default color table that will be used unless you
 override that default by giving your desired CPT information.
 
+Data Registration
+-----------------
+
+Optionally, you can append _\ **g** or _\ **p** to specifically get the gridline-registered or
+pixel-registered version (if they both exist).  If *reg* is not specified then the behavior
+depends on whether you are making a plot or processing/extracting a subset of the data:
+
+    - For plots we will return the pixel-registered version unless only the gridline-registered file is available.
+    - For grid processing modules we will return the gridline-registered version unless only the pixel-registered
+      file is available.  We will also issue a warning since for calculations you should ideally know and
+      specify exactly what you want.
+
+If you do specify a specific registration and that version is not available you will get an error message.
+
 Controlling the Process
 -----------------------
 

doc/rst/source/tutorial/session-4.rst

@@ -228,7 +228,11 @@ we prefer to use the **-Ne** option; the value of
 
      gmt grdgradient @tut_relief.nc -Ne0.8 -A100 -fg -Gus_i.nc
 
-Given the CPT and the two gridded data sets we can
+However, for most maps relying on the remote data sets we do not actually
+need to extract subsets and run :doc:`/grdgradient` manually.  Instead, we let :doc:`/grdimage`
+create the gradients directly from the subset of the global grid, passing the
+arguments to :doc:`/grdgradient` via the **-I** option of :doc:`/grdimage`.  
+Given the previous CPT and our chosen :doc:`/grdgradient` arguments we can
 create the shaded relief image:
 
 .. literalinclude:: /_verbatim/GMT_tut_16.txt
@@ -241,14 +245,14 @@ Your plot should look like :ref:`our example 16 below <gmt_tut_16>`
    :width: 400 px
    :align: center
 
-   Result of GMT Tutorial example 16
+   Result of GMT Tutorial example 16.
 
 
 Exercises:
 
 #. Force a gray-shade image.
 
-#. Rerun :doc:`/grdgradient` with **-N**\ 1.
+#. Rerun the example with **-I+a**\ 30\ **+n**\ 1.
 
 Multi-dimensional maps
 ----------------------
@@ -332,7 +336,7 @@ Option                    Purpose
 ========================= =============================================================================================================
 **-C**\ *cpt*             The *cpt* is required for color-coded surfaces and for contoured mesh plots
 **-G**\ *drape\_file*     Assign colors using *drape\_file* instead of *relief\_file*
-**-I**\ *intens\_file*    File with illumination intensities
+**-I**\ *intens\_file*    File with illumination intensities or arguments to :doc:`/grdgradient`
 **-Qm**                   Selects mesh plot
 **-Qs**\ [**+m**]         Surface plot using polygons; append **+m** to show mesh.  This option allows for **-W**
 **-Qi**\ *dpi*\ [**g**]   Image by scan-line conversion.  Specify *dpi*; append **g** to force gray-shade image.  **-B** is disabled.
@@ -366,7 +370,7 @@ Color-coded view
 ~~~~~~~~~~~~~~~~
 
 We will make a perspective, color-coded view of the US Rockies
-from the southeast.  This is done using
+from the southeast.  Similar to the :doc:`/grdimage` examples, this is done using
 
 .. literalinclude:: /_verbatim/GMT_tut_19.txt
 
@@ -378,7 +382,7 @@ Your plot should look like :ref:`our example 19 below <gmt_tut_19>`
    :width: 400 px
    :align: center
 
-   Result of GMT Tutorial example 19
+   Result of GMT Tutorial example 19.
 
 This plot is pretty crude since we selected 50 dpi but it is fast
 to render and allows us to try alternate values for vantage point
@@ -389,6 +393,6 @@ Exercises:
 
 #. Choose another vantage point and scaling.
 
-#. Redo :doc:`/grdgradient` with another illumination direction and plot again.
+#. Examine the :doc:`/grdgradient` options and select another illumination direction in **-I** and plot again.
 
 #. Select a higher *dpi*, e.g., 200.

doc/scripts/GMT_atan.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 gmt begin GMT_atan
 	gmt set GMT_THEME cookbook
-	gmt grdgradient -A45 @earth_relief_30s -R-108/-103/35/40 -N -fg -Gtt.t.nc
+	gmt grdgradient -A45 @earth_relief_30s_p -R-108/-103/35/40 -N -fg -Gtt.t.nc
 	gmt grd2xyz -Z tt.t.nc > tt.d
 	gmt histogram tt.d -R-0.75/0.75/0/20 -JX1.5i/1i -Bx0.5 -By5f5 -BWSne -W0.01 -Gblack -Z1
 

doc/scripts/GMT_tut_16.sh

@@ -2,8 +2,6 @@
 gmt begin GMT_tut_16
 	gmt set GMT_THEME cookbook
 	gmt makecpt -Crainbow -T1000/5000
-	gmt grdcut @earth_relief_30s -R-108/-103/35/40 -Gtut_relief.nc
-	gmt grdgradient tut_relief.nc -Ne0.8 -A100 -fg -Gus_i.nc
-	gmt grdimage @earth_relief_30s -R-108/-103/35/40 -Ius_i.nc -JM6i -B -BWSnE
+	gmt grdimage @earth_relief_30s -R-108/-103/35/40 -I+a100+ne0.8 -JM6i -B -BWSnE
 	gmt colorbar -DJTC -I0.4 -Bxa -By+lm
 gmt end show

doc/scripts/GMT_tut_19.sh

@@ -2,7 +2,5 @@
 gmt begin GMT_tut_19
 	gmt set GMT_THEME cookbook
 	gmt makecpt -Cdem2 -T1000/5000
-	gmt grdcut @earth_relief_30s -R-108/-103/35/40 -Gtut_relief.nc
-	gmt grdgradient tut_relief.nc -Ne0.8 -A100 -fg -Gus_i.nc
-	gmt grdview tut_relief.nc -JM4i -p135/35 -Qi50 -Ius_i.nc -B -JZ0.5i
+	gmt grdview @earth_relief_30s -R-108/-103/35/40 -JM4i -p135/35 -Qi50 -I+a100+ne0.8 -B -JZ0.5i
 gmt end show

src/gmt_init.c

@@ -14170,7 +14170,7 @@ GMT_LOCAL bool gmtinit_is_PS_module (struct GMTAPI_CTRL *API, const char *name,
 	else if (!strncmp (name, "pscontour", 9U)) {	/* Check for -D option */
 		if ((opt = GMT_Find_Option (API, 'D', options))) return false;	/* -D writes dataset */
 	}
-	else if (!strncmp (name, "psevents", 8U)) {	/* Check for -D option */
+	else if (!strncmp (name, "psevents", 8U)) {	/* Check for -A option */
 		if ((opt = GMT_Find_Option (API, 'A', options)) == NULL) return true;	/* All but -A is guaranteed to write PS */
 		if (opt->arg[0] == 'r' && opt->arg[1] && isdigit (opt->arg[1])) return false;	/* This is just preparing an densely sampled file */
 		return true;	/* Any other case gets here and makes PS */
@@ -15045,7 +15045,7 @@ struct GMT_CTRL *gmt_init_module (struct GMTAPI_CTRL *API, const char *lib_name,
 	 * Note: 1. If no -J can be found in the history we provide either -JQ15c (geographic data) or -JX15c (Cartesian).
 	 *
 	 * Modules like pslegend has "rj" since -R -J are not required if -Dx is used but required for other settings.
-	 * Modules like blockmean, surface has "R" since it is never cool to autodetermine grid domains as this also
+	 * Modules like blockmean, surface has "R" since it is never cool to auto-determine grid domains as this also
 	 *  depends on grid spacing, for instance.
 	 * Modules like grdview has "g" since they always have a grid domain to fall back on in the absence of -R.
 	 * Modules like psxy has "d" so we can make a quick map without specifying -R.
@@ -15065,10 +15065,14 @@ struct GMT_CTRL *gmt_init_module (struct GMTAPI_CTRL *API, const char *lib_name,
 	gmt_M_unused(this_module_kw);
 	#endif
 
-	/* First handle any half-hearted naming of remote datasets where _g or _p should be appended */
+	is_PS = gmtinit_is_PS_module (API, mod_name, keys, options);	/* true if module will produce PS */
+
+	/* First handle any halfhearted naming of remote datasets where _g or _p should be appended */
 
 	if (options) {
-		if (!strcmp (mod_name, "grdtrack")) API->use_gridline_registration = true;	/* Override API default since grdtrack is a data processor */
+		if (!is_PS) {	/* Override API default since module is a data processor */
+			API->use_gridline_registration = true;
+		}
 		for (opt = *options; opt; opt = opt->next) {	/* Loop over all options */
 			if (!gmtinit_might_be_remotefile (opt->arg)) continue;
 			if (remote_first) {
@@ -15184,7 +15188,6 @@ struct GMT_CTRL *gmt_init_module (struct GMTAPI_CTRL *API, const char *lib_name,
 		}
 	}
 
-	is_PS = gmtinit_is_PS_module (API, mod_name, keys, options);	/* true if module will produce PS */
 	if (is_PS) {
 		if (gmtinit_set_modern_mode_if_oneliner (API, options))	/* Look out for modern -png mymap and similar specs */
 			return NULL;

src/gmt_remote.c

@@ -488,6 +488,7 @@ void gmt_set_unspecified_remote_registration (struct GMTAPI_CTRL *API, char **fi
 	q += strlen (p);	/* Move to the end of family name after which any registration codes would be found */
 	if (strstr (q, "_p") || strstr (q, "_g")) goto clean_up;	/* Already have the registration codes */
 	if (API->use_gridline_registration) {	/* Switch order so checking for g first, then p */
+		GMT_Report (API, GMT_MSG_WARNING, "Remote dataset given to a data processing module but no registration was specified - default to gridline registration (if available)\n");
 		kstart = 1; kstop = -1; kinc = -1;
 	}
 	for (k = kstart; k != kstop; k += kinc) {

test/baseline/gmtmex.dvc

@@ -1,5 +1,5 @@
 outs:
-- md5: 62aa10dd47eedb69073cc06450a315ec.dir
-  size: 2480646
+- md5: 8031eb862d2823b66666a38cfab08b32.dir
+  size: 2485046
   nfiles: 3
   path: gmtmex

test/baseline/grdfill.dvc

@@ -1,5 +1,5 @@
 outs:
-- md5: 82975536c80c6bb2561c097ea194e345.dir
-  size: 207030
+- md5: 1fc1d45ab00d7238f6b9ec5fa5e9601c.dir
+  size: 207393
   nfiles: 5
   path: grdfill

test/genper/east_map_8.sh

@@ -19,6 +19,6 @@ Height=30.0
 PROJ=-JG${DEBUG}${EARTH_MODEL}${longitude}/${latitude}/${altitude}/${azimuth}/${tilt}/${twist}/${Width}/${Height}/7i+
 
 gmt makecpt -Cglobe > t.cpt
-gmt grdcut -R275/290/30/45 @earth_relief_02m -Getopo2-chesapeake.nc=ns
+gmt grdcut -R275/290/30/45 @earth_relief_02m_p -Getopo2-chesapeake.nc=ns
 gmt grdimage ${GMT_VERBOSE} etopo2-chesapeake.nc -P -Xc -Yc $REGION $PROJ -Ct.cpt -K > $ps
 gmt pscoast ${GMT_VERBOSE} $REGION $PROJ -B5g5 -B+t${TITLE} -Ia -Na -O --MAP_ANNOT_MIN_SPACING=0.5i >> $ps

test/genper/pacific_map_2.sh

@@ -22,6 +22,6 @@ Height=2.0
 PROJ=-JG${DEBUG}${EARTH_MODEL}${longitude}/${latitude}/${altitude}/${vp_longitude}/${vp_latitude}/${twist}/${Width}/${Height}/7i+
 
 gmt makecpt -Cglobe > t.cpt
-gmt grdcut @earth_relief_02m -R189/210/10/33 -Getopo2-hawaii.nc=ns
+gmt grdcut @earth_relief_02m_p -R189/210/10/33 -Getopo2-hawaii.nc=ns
 gmt grdimage etopo2-hawaii.nc ${GMT_VERBOSE} -P -Xc -Yc $REGION $PROJ -Ct.cpt -K > $ps
 gmt pscoast ${GMT_VERBOSE} $REGION $PROJ -B5g5 -B+t${TITLE} -Wfaint -O --MAP_ANNOT_MIN_SPACING=0.5i >> $ps

test/grd2cpt/equalarea.sh

@@ -5,7 +5,7 @@
 
 gmt begin equalarea ps
 	gmt set MAP_FRAME_TYPE plain
-	gmt grdcut -R0/90/0/45 @earth_relief_05m -Gtmp.grd
+	gmt grdcut -R0/90/0/45 @earth_relief_05m_p -Gtmp.grd
 	gmt subplot begin 2x1 -Fs16c/11c -BWSrt -M6p -T"CPT Equalization" -Y0.5i
 	gmt subplot set 0
 	gmt grd2cpt tmp.grd -E11

test/grdcontour/contours.sh

@@ -16,7 +16,7 @@ color_contour () {
 	done
 }
 
-gmt grdcut @earth_relief_02m -R204/206/19/21 -GBigIsland.nc
+gmt grdcut @earth_relief_02m_p -R204/206/19/21 -GBigIsland.nc
 gmt makecpt -Cseis -T0/1 > contour.cpt
 
 # The bottom map will have contours oriented so that as you move along

test/grdcut/polycut.sh

@@ -5,11 +5,11 @@ gmt begin polycut
 	# Get France polygon
 	gmt coast -EFR -M > FR.txt
 	# Crop output grid to bounding box of FR
-	gmt grdcut @earth_relief_30m -FFR.txt+c -GFR_only.grd
+	gmt grdcut @earth_relief_30m_p -FFR.txt+c -GFR_only.grd
 	# Same but set inside, not outside, to NaN
-	gmt grdcut @earth_relief_30m -FFR.txt+c+i -GFR_not.grd
+	gmt grdcut @earth_relief_30m_p -FFR.txt+c+i -GFR_not.grd
 	# Like first, but retain input region
-	gmt grdcut @earth_relief_30m -FFR.txt -GFR_world.grd
+	gmt grdcut @earth_relief_30m_p -FFR.txt -GFR_world.grd
 	gmt grdimage FR_world.grd -B -Rd -JQ0/18c -Cturbo
 	gmt subplot begin 1x2 -Fs8.5c -Scb -Srl -RFR -JM8.5c -M0.35c -Yh+1c
 		gmt grdimage FR_only.grd -Cturbo -c

test/grdfft/gfilter.sh

@@ -4,7 +4,7 @@
 ps=gfilter.ps
 gmt set GMT_FFT kiss
 topo=topo_38.nc
-gmt grdcut @earth_relief_02m -R-60/-45/-20/-10 -G${topo}=ns
+gmt grdcut @earth_relief_02m_p -R-60/-45/-20/-10 -G${topo}=ns
 
 # Do a 100 km Gaussian filter on some topography
 gmt grdfft ${topo} -fg -F-/100000 -Glow.nc -N+l

test/grdfill/constfill.sh

@@ -2,7 +2,7 @@
 # Testing grdfill with constant infill of NaN areas
 ps=constfill.ps
 # Get topo for Hawaiian Islands and set data on land to NaN
-gmt grdclip @earth_relief_05m -R199:30/206/18/23 -Sa0/NaN -Gislands.nc
+gmt grdclip @earth_relief_05m_p -R199:30/206/18/23 -Sa0/NaN -Gislands.nc
 gmt makecpt -Csealand -T-5000/5000 > t.cpt
 # Now replace NaN holes with 4000 m
 gmt grdfill islands.nc -Ac4000 -Gnew.nc

test/grdfill/gridfill.sh

@@ -2,11 +2,12 @@
 # Test the -Ag algorithm in grdfill
 # The commented step are the commands making the file now in the cache
 # Pull out a small piece of 20m DEM
-# gmt grdcut -R0/10/0/10 @earth_relief_20m -Gdata.grd
+# gmt grdcut -R0/10/0/10 @earth_relief_20m_g -Gdata.grd
 # Make a mask for two holes
 # gmt grdmath -Rdata.grd 4 6 SDIST 250 GE 0 NAN 7 1.5 SDIST 100 GE 0 NAN ADD 2 DIV = mask.grd
 # Combine to get data with the holes
 # gmt grdmath data.grd mask.grd MUL = earth_relief_20m_holes.grd
+# The file earth_relief_20m_holes.grd is stored in the cache
 # Try filling in the holes via sampling from a coarser 1d grid
 gmt begin gridfill
 	gmt makecpt -Cgeo

test/grdfill/nnfill.sh

@@ -2,7 +2,7 @@
 # Testing grdfill with NN infill of NaN areas
 ps=nnfill.ps
 # Get topo for Hawaiian Islands and set data inside a 200 km radius of 203/20:30 to NaN
-gmt grdmath @earth_relief_05m -R199:30/206/18/23 203 20:30 SDIST 200 GT MUL 0 NAN = islands.nc
+gmt grdmath @earth_relief_05m_p -R199:30/206/18/23 203 20:30 SDIST 200 GT MUL 0 NAN = islands.nc
 gmt makecpt -Csealand -T-5000/1000 > t.cpt
 # Fill in the NaN hole using nearest neighbor
 gmt grdfill islands.nc -An -Gnew.nc

test/grdfill/showregions.sh

@@ -2,7 +2,7 @@
 # Testing grdfill with -L to indicate regions of NaNs
 ps=showregions.ps
 # Get topo for Hawaiian Islands and set data on land to NaN
-gmt grdclip @earth_relief_10m -R199:30/206/18/23 -Sa0/NaN -Gislands.nc
+gmt grdclip @earth_relief_10m_p -R199:30/206/18/23 -Sa0/NaN -Gislands.nc
 gmt makecpt -Csealand -T-5000/5000 > t.cpt
 # Determine all holes and get rectangular polygons for each one and plot
 gmt grdfill islands.nc -Lp > t.txt

test/grdfill/splinefill.sh

@@ -2,7 +2,7 @@
 # Testing grdfill with spline infill of NaN areas
 gmt begin splinefill ps
 	# Get topo for Hawaiian Islands and set data on land to NaN
-	gmt grdclip @earth_relief_05m -R199:30/206/18/23 -Sa0/NaN -Gislands.nc
+	gmt grdclip @earth_relief_05m_p -R199:30/206/18/23 -Sa0/NaN -Gislands.nc
 	gmt makecpt -Csealand -T-5000/5000 -H > t.cpt
 	# Now replace NaN holes with cubic spline solutions
 	gmt grdfill islands.nc -As -Gnew.nc

test/grdfilter/filtertest.sh

@@ -16,7 +16,7 @@ fi
 
 FILT=g			# Gaussian filter
 INC=1			# 1x1 degree output
-DATA=@earth_relief_10m # Test on ETOP10 data
+DATA=@earth_relief_10m_p # Test on ETOP10 data
 lon=150
 lat=-80
 D=5000

test/grdfilter/highpass.sh

@@ -2,7 +2,7 @@
 # Test highpass-filter with or without coarse grid low-pass option
 # Doing a 10x10 degree patch near Nigeria
 ps=highpass.ps
-gmt grdcut @earth_relief_02m -R0/10/0/10 -GAFR.nc
+gmt grdcut @earth_relief_02m_p -R0/10/0/10 -GAFR.nc
 gmt grdfilter AFR.nc -Fg100+h -D2 -GHc.nc -I15m
 gmt grdfilter AFR.nc -Fg100 -D2 -GLc.nc -I15m
 gmt grdfilter AFR.nc -Fg100+h -D2 -GHf.nc

test/grdfilter/threads.sh

@@ -9,7 +9,7 @@ fi
 FILT=g			# Gaussian filter
 INC=1			# 1x1 degree output
 D=1000			# 1000 km filter width
-DATA=@earth_relief_10m	# Test on ETOP10 data
+DATA=@earth_relief_10m_p	# Test on ETOP10 data
 
 # Run gmt grdfilter as specified
 gmt grdfilter -D4 -F${FILT}$D -I$INC $DATA -Gt.nc -fg ${_thread_opt}

test/grdimage/grdcyclic.sh

@@ -4,7 +4,7 @@ ps=grdcyclic.ps
 
 gmt makecpt -Cjet -T0/1000 -Ww > cyclic.cpt
 gmt makecpt -Cjet -T-5000/3000 > t.cpt
-gmt grdcut -R0/10/0/10 @earth_relief_05m -Gafr_topo.grd
+gmt grdcut -R0/10/0/10 @earth_relief_05m_p -Gafr_topo.grd
 gmt grdimage afr_topo.grd -Ccyclic.cpt -JM4.5i -P -K -Baf -BWSNe -X1.5i -Y0.75i > $ps
 gmt psscale -DJRM+mc -Ccyclic.cpt -Baf+l"CYCLIC" -R -J -O -K >> $ps
 gmt grdimage afr_topo.grd -Ct.cpt -JM4.5i -O -K -Baf -BWsNe -Y4.9i >> $ps

test/grdimage/imgshade.sh

@@ -5,10 +5,10 @@
 gmt begin imgshade ps
 	gmt subplot begin 2x1 -Fs16c/9.2c
 		gmt subplot set
-			gmt grdgradient @earth_relief_15m -Nt1 -A45 -GIntens.nc -R-85/-54/9/26
+			gmt grdgradient @earth_relief_15m_p -Nt1 -A45 -GIntens.nc -R-85/-54/9/26
 			gmt grdimage @earth_day_15m -IIntens.nc -JM?
 		gmt subplot set
-			gmt grdgradient @earth_relief_15m -Nt1 -A45 -GIntens.nc -R140/190/-50/-28
+			gmt grdgradient @earth_relief_15m_p -Nt1 -A45 -GIntens.nc -R140/190/-50/-28
 			gmt grdimage @earth_day_15m -IIntens.nc -JM?
 	gmt subplot end
 gmt end show