Support underlays in modern more

[maxrjones]

Description of the desired feature

Add the functionality to recycle bits of PostScript in modern mode, e.g., make a common underlay base.ps and use it in different plots. I'm most interested in the basemap use case, but there also may be people who are interested in being able to add common overlays to many plots.

A pseudo-code example:

export GMT_SESSION_NAME=underlay
gmt begin
gmt basemap -JM6i -R-30/30/-30/30 -Bafg

unset GMT_SESSION_NAME

gmt begin -Dunderlay,overlay # duplicate underlay session to overlay
gmt plot ex1.txt -S -Cchrome
gmt end show

gmt begin -Dunderlay,overlay # duplicate underlay session to overlay
gmt plot ex2.txt -S -Cchrome
gmt end show

gmt begin -Dunderlay,overlay # duplicate underlay session to overlay
gmt plot ex3.txt -S -Cchrome
gmt end show

Are you willing to help implement and maintain this feature? Yes/No

[PaulWessel]

Some of you may recall an early modern mode command called revert (revert.c now lives in exile in the sandbox just in case). It could strip off layers from the current plot. It seems a bit clutzy to me thought.

Here are quick thoughts on overlays/underlays

1. Plot what you consider a layer normally
2. Run gmt layer get name to make a named snapshot of current plot
3. When you want to add this layer to another plot, run gmt layer put name
4. To use it as an underlay (first layer) for a new figure, you just do gmt figure first then gmt layer put name
5. Layers are not tied to a figure, but tied to session, and may be used any number of times
6. Named layers die when the session ends

The verbs get and put can be discussed. We can discuss if calling get with the same name as before simply overwrites or if we refuse to do so without some -F force option or an intermediate gmt layer delete name command.

[maxrjones]

Some of you may recall an early modern mode command called revert (revert.c now lives in exile in the sandbox just in case). It could strip off layers from the current plot. It seems a bit clutzy to me thought.

Here are quick thoughts on overlays/underlays

1. Plot what you consider a layer normally

2. Run **gmt layer get** _name_ to make a named snapshot of current plot

3. When you want to add this layer to another plot, run **gmt layer put** _name_

4. To use it as an underlay (first layer) for a new figure, you just do **gmt figure** first then **gmt layer put** _name_

5. Layers are not tied to a figure, but tied to session, and may be used any number of times

6. Named layers die when the session ends

The verbs get and put can be discussed. We can discuss if calling get with the same name as before simply overwrites or if we refuse to do so without some -F force option or an intermediate gmt layer delete name command.

Given that the layers die when the session ends, it is not clear to me how you would finalize the figures without closing the session if, for example, you want to use the same layers when updating a plot every day, week, year, etc.

[PaulWessel]

Perhaps we should convert this to a discussion item?

[maxrjones]

Good points @KristofKoch. I will accept that I will need to keep using -K's and -O's for the most powerful map control features in GMT 😄

[seisman]

I think we should have a section explaining how classic mode works in the documentation. For new GMT users, they only know modern mode, and know nothing about -K, -O and PS layers unless they read the old documentation.

[PaulWessel]

Yes, there may need to be a high-level overview of the two systems, the pros and cons, what can and cannot be done in modern and what is awkward in classic, etc.

[anbj]

People should be told that the (potential) convenience and simplicity of modern mode has a price.
I've tried modern mode a couple of times, but I keep falling back on classic mode; it's what I've been using since I first touched GMT, and the fingerspitzengefühl it gives you, is of high value to me. Also I'm getting grumpier by the year. I'm glad I learned GMT when only classical mode existed. I've learned things that I probably never would, if only modern mode was around.

[maxrjones]

One option would be to revise this section in the cookbook (https://docs.generic-mapping-tools.org/dev/cookbook/introduction.html#modern-and-classic-mode) to include the high-level overview, pros and cons, etc. for each without assuming any prior knowledge about GMT.

[joa-quim]

Modern forbids the use of -O, -K, >, >> so one cannot play with pieces of a PS file. But other that, what else is not possible in Modern but yes in Classic?