Use modern gs transparency command

[PaulWessel]

Yet, we check if our gs is old and if so we stitch in the older transparency command. At some point we should remove that crutch. Closes #4453.

[seisman]

Running this command:

gmt basemap -R0/10/0/10 -JX10c -Baf -t90 -png test

master

This branch

[PaulWessel]

And manually editing the PS and putting back the old command gives the correct answer. Since all our plotting commands are between the two PSL_transp calls I wonder if they have a bug...

[PaulWessel]

The problem is that the old .setopacityalpha has been replaced with two settings: .setfillconstantalpha and .setstrokeconstantalpha. So, there are actually two options facing us:

1. We can set both and then GMT should behave exactly as before
2. We allow -t and @transp arguments to take optional +s (stroke) or +f (fill) to allow for enhanced flexibility.

I am not sure when this is useful but I note that the gs developers felt this is useful. Perhaps fading a color in a polygon but leaving lines solid is not a bad idea, so I think option 2 is better - but requires gs 9.53 of course to have an effect.

[PaulWessel]

Following up on last post, there are actually several issues to decide here going forward:

A. Backwards compatibility

1. I think -ttransp should set both stroke and fill transparency, as it currently does.
2. Note that plot, text and plot3d can take -t with no arguments and then read transparency from data column. We then read one value but assign it to both types of transparency, to be consistent with (1).

B. New features

As discussed, extend the syntax for -t to now be -t[ftransp[/stransp]][+s][+f] where

1. ftransp and stransp are fill and stroke transparencies, respectively. If only ftransp is given it means stransp = ftransp unless there are modifiers.
2. Modifiers +f and +s limits the single given transparency to either fill or stroke
3. If no transparencies are given then we read one from file (ftransp = stransp) unless one or both modifiers are given.

Comments or concerns, @joa-quim and @seisman ?

[PaulWessel]

Note that our transparency macro supports both ghostscript and Adobe Destiller:

/PSL_transp {						% Set transparencies
  /.setfillconstantalpha where {pop .setblendmode .setfillconstantalpha}{		% Using ghostscript
  /pdfmark where {pop [ /BM exch /CA exch dup /ca exch /SetTransparency pdfmark}	% Or Adobe
  {pop pop} ifelse} ifelse				% Or skip if neither are supported
}!

and looking (again) and the pdfmark documentation I can now remember that CA and ca sets the two different types of transparencies and we are just duplicating them (dup) since we only pass on number to PSL_transp. Going forward, we will need to pass two numbers in order to set different values, e.g.,

0.2 0.5 /Normal PSL_transp

I think a first step is simply to change the macro to take two numbers and then change the code that writes these commands to write two numbers (duplicates). Then the above enhancements can take place next.

Information on pdfmark can be found here. The example they give on top of page 41 is actually what we get (using the path twice) in GMT, so perhaps we need to be more careful when transparency applies to both path and fill.

[PaulWessel]

I have implemented the dual transparencies and fixed the PSL_transp macro for gs 9.53. I also let psconvert handle version mismatches on the fly: New PS with old gs as well as Old PS (our PS origs) and new gs. I have tested the transparency for both ghostscript 9.53 and 9.50 and Adobe Distiller as well as none available, so the new macro works. I have updated the docs and codes and all tests pass. I will need help with the new explain_-tv.rst_ and explain_-tv_full.rst_ since the link from the synopsis do not work and I get

common_SYN_OPTs.rst_:63: WARNING: undefined label: -tv_full (if the link has no caption the label must precede a section header)

Please give the update GMT PS a spin.

[seisman]

These two commands give me the same figures:

gmt basemap -R0/10/0/10 -JX10c -Baf -t90+s -png test
gmt basemap -R0/10/0/10 -JX10c -Baf -t90+f -png test

[PaulWessel]

Thanks, I can see why and will fix shortly.

[PaulWessel]

Try these and contrast:

gmt basemap -R0/10/0/10 -JX10c -Baf -t60+f -pdf test --FONT_ANNOT_PRIMARY=16p,Helvetica,red=0.25p,blue
gmt basemap -R0/10/0/10 -JX10c -Baf -t60+s -pdf test --FONT_ANNOT_PRIMARY=16p,Helvetica,red=0.25p,blue

[PaulWessel]

Or your original examples.

[seisman]

Looks good to me, but also see the tiny fixes in my previous review.

[PaulWessel]

For @joa-quim : This PR prevents those warnings when gs 9.53 is run on previously built PS made before this PR, such as our PS originals in GitHub.

[seisman]

I will need help with the new explain_-tv.rst_ and explain_-tv_full.rst_ since the link from the synopsis do not work and I get

common_SYN_OPTs.rst_:63: WARNING: undefined label: -tv_full (if the link has no caption the label must precede a section header)

Please give the update GMT PS a spin.

The warning is because, explain_-tv_full.rst_ is not included anywhere. Perhaps we should include the file in gmt.rst?

[PaulWessel]

OK, yes, the other _full are included by gmt.rst but here -t is slightly different in the -tv. Is there a way to include it but not show it? Or perhaps just include full in the three module rst files instead of the short one?

[PaulWessel]

Perhaps that is the best solution so it is clear without clicking that see more link that there are a few changes here.

[seisman]

Perhaps that is the best solution so it is clear without clicking that see more link that there are a few changes here.

Sounds OK to me.