Introduce GMT modes: classic and modern

Added by Paul 7 months ago

Please see Remko's proposal for producing PDF and avoiding -O -K (listed at the bottom of the Developer page). This modification is in that spirit but extended to allow simplification for GMT usage from both command lines and external interfaces. It will achieve this by the introduction of a GMT mode setting.

As we start to have more experience with the MATLAB and Octave toolboxes (and about to start work on the Python package) we are noticing that the resulting scripts look too much like the GMT shell command line. In particular, there are the repetitive options -O -K -R -J and the repeated appending to the PostScript cake being built. A new way forward is to introduce a new GMT Default setting GMT_MODE which takes on values classic or modern. Classic is the GMT we all know. The modern mode sets a new simpler mode which disables some options that we can avoid using by following new rules:

  1. No redirection of PostScript output is possible, as all PostScript is written to a hidden gmt.ps file.
  2. The -O -K options are disabled.
  3. A PostScript -producing module will know if it starts a new cake or if it is appending due to the absence or presence of the hidden gmt.ps file.
  4. psconvert will auto-complete any PostScript cake since they all miss the trailer layer.
  5. If -R is not given but required we supply the previous -R. If none then we have an error.
  6. If -J is not given but required we supply the previous -J. If none then we have an error.
  7. psconvert will get a few more options to extract and reinsert the hidden gmt.ps file for advanced use.

For external interfaces the mode is set in the GMT_Create_Session call. The developers of these interfaces can decide what they want to offer but presumably this is the modern mode. To illustrate the new modes, here is a hypothetical bash script in classic mode that makes a PDF map:

gmt grdimage -Chot -Iintens.nc data.nc -JM6i -P -K > my_map.ps
gmt pscoast -Rdata.nc -J -O -Baf -Gred -K >> my_map.ps
gmt pstext -F+f12p labels.txt -R -J -O -K >> my_map.ps
gmt psxy -W2p lines.txt -R -J -O >> my_map.ps
gmt psconvert -Tf -P -A my_map.ps

Using the modern mode we will instead write

gmt grdimage -Chot -Iintens.nc data.nc -JM6i -P   # Initialize plot, set -R -J the first time
gmt pscoast -Baf -Gred                            # Overlay coastlines
gmt pstext -F+f12p labels.txt                     # Inherit -R -J automatically
gmt psxy -W2p lines.txt                           # Add some lines
gmt psconvert -Tf -P -A -Fmy_map.pdf              # Finalize and get a PDF, delete hidden PS

A comparable GMT/MATLAB toolbox example:

gmt ('grdimage', '-JM6i -P -Chot -I', G, Intense);   % Initialize plot, set -R -J the first time
gmt ('pscoast', '-Baf -Gred');                       % Overlay coastlines
gmt ('pstext', '-F+f12p', labels);                   % Inherit -R -J automatically
I = gmt ('psxy', '-W2p', lines);                     % Finalize, rip PS to image which is returned, delete hidden PS

Coding becomes much shorter, avoiding all the repetitive -O -K -R -J options, and is simpler to explain. As you know, the -O -K dance is the bane of many a GMT rookie and it would no longer need to be explained.


Replies (7)

RE: Introduce GMT modes: classic and modern - Added by Remko 7 months ago

Keeping psconvert might indeed be the smart thing to do, so you can keep all its options without another GMT default.
As you suggested it would include the following functionalities:
  • End the PS file gmt.ps by adding the trailer.
  • Convert to any format (also EPS and plain PS).

But how is this working with the Matlab toolbox? Does this still require an external call to psconvert?

Maybe, given this new functionality there ought to be an alias "gmt end" for "gmt psconvert"?

RE: Introduce GMT modes: classic and modern - Added by Paul 7 months ago

Thanks Remko, the above has been implemented in trunk and we are testing things. So far so good, Windows gives some trouble but we shall overcome.
If gmt end, then why not gmt begin as well?

RE: Introduce GMT modes: classic and modern - Added by Paul 7 months ago

To clarify, gmt begin would initialize the new PS file and set -R -J [and optionally -X -Y -U, others]. It could do more things as well such as specify which gmt.conf to use , easy access to paper size setting , pre-specify the plot name instead of at the end . Perhaps could set a single -V that lasts until gmt end (a -V for other modules only applies to that module), etc., etc. It would be implemented as a call to GMT_psxy with -R -J -K -T [-X -Y -U etc], and as Remko said, gmt end is just an alias for psconvert.

gmt begin -Rw/e/s/n -JM6i
    gmt .... other call
    gmt .... other call
    gmt .... other call
    gmt .... other call
gmt end -Fmyplot -Tfp

More ideas?

RE: Introduce GMT modes: classic and modern - Added by Remko 7 months ago

Although, later I realised that "gmt end" would not be a correct naming convention, as it only applies to PS matter. So "gmt psend" would be OK.
And then "gmt begin" does not make sense any more ...

On the other hand, I like your suggestion. But we should not forget that people may use GMT for non-PS jobs, for which "gmt begin"/"gmt end" is of less purpose.

RE: Introduce GMT modes: classic and modern - Added by Paul 7 months ago

Right, agreed. Over the years there have been suggestions by some of us and users as to having a plotend command to do the psxy -R -J -O -T part. So one could imagine

gmt psbegin
gmt ...some plot command
gmt psend

situation, but I think these should not be required as

gmt pscoast -R0/30/0/30 -JM6i -Gred -Baf -P
gmt psconvert -Tf -Fmap

should be OK too.

RE: Introduce GMT modes: classic and modern - Added by Remko 6 months ago

Agreed. The psbegin/psend just adds additional variations of "GMT as we know it". If this had been used from the start, it would be very logical. But after so many years it would just add commands without necessity.
Only the alias "psend" for "psconvert" may be useful.
You have already noted that "psconvert" will now automatically add the trailer to the Postscript file, so covers the "psxy -R -J -O -T" part.

RE: Introduce GMT modes: classic and modern - Added by Paul 6 months ago

Yes. I think if one is to explain to a new user how to make a plot and obtain a PDF map then "psconvert" is a good verb and says more than "psend" would do. So lets bag the begin-end for now. The only situation where "psconvert" is slightly wrong is when you actually want a plain PostScript file (so not really a conversion), which I would assume is almost never these days (you may want an EPS file as some journals want that, and that is a conversion). Dinosaurs who insist on a pure PostScript file will be using classic mode anyway.

(1-7/7)