Docs: how could `-Jo|O[a|A]` all map to just `-Jomerc`?

Q&A
1

On https://docs.generic-mapping-tools.org/dev/cookbook/options.html#proj-codes we see

There are two conventions you may use: (a) GMT-style syntax and (b) PROJ-style syntax.
…
Oblique Mercator, 1: origin and azim -Jo|O[a|A] -Jomerc/ lon0/lat0/azim/scale|width [+v]

Seems suspicious, how could all four combinations (-Joa, -JoA, -JOa, -JOA) all
map to a single “-Jomerc”? I mean if it were that simple, then there
wouldn’t need to be four cases in the first place.

OK, my next step in my investigation was to find a working example to
test my suspicions with.

I found one on https://docs.generic-mapping-tools.org/dev/cookbook/map-projections.html#jo ,
the ‘Oblique view of Baja California’ example.

OK, I swapped out the

  • -JOa120W/25N/-30/6c+v

with

  • -Jomerc/120W/25N/-30/6c+v

and my suspicions were confirmed: I got a very different looking map.

That’s all I know*.

Therefore I conclude -Jo|O[a|A] do not all just simply map to
-Jomerc, thus options.html needs to be corrected. Probably there is
the same problem with the b and c lines there too.

(Fun fact, while looking for examples, I found there were zero -Job ones!)

$ for i in a b c
   do rgrep -i -- -jo$i Downloads/gmt-6.4.0/doc_release/html/|
   wc -l; done
9
0
25

(*In fact I know more. Adding -V to the original example also gave:)

coast [INFORMATION]: GMT_Parse_Options: Interval-setting -B options were reordered to appear before axis and frame -B options to ensure proper parsing.
coast [INFORMATION]: Detected a classic module name (psxy) in modern mode - please use the modern mode name plot instead.

(so maybe the example could be tightened up a little, even though
without -V one would not notice the “problem”.)

2

Probably best to let @Joaquim answer this since he did all the PROJ stuff. I dont use PROJ but pretty sure it has no concept of map width, only scale. Since GMT mostly tends to plot maps it is convenient to specify map width rather than computing a scale from desired map size and, say, projected x-range. So there cannot be any -Jomerc equivalent to the upper case letters (unless @Joaquim did sneaky things under the hood).

Not sure if there is an equivalent setting like our +v to transpose the coordinate system. There is talk about some rotation but, again, not tried that.

The message about psxy is interesting since it is not used in that script? You are talking about GMT_obl_baja.sh, right?

3

Forgot that coast may call psxy when DCW polygons must be filled. I’ve made a PR where we check if we are in modern or classic mode and call the corresponding module name.

4

We probably should remove that from the documentation. It was introduced way before the proj stuff and I never saw it used. It can be considered the first attempt of introducing long options.

5 
$ echo 12 55 | gmt mapproject -V -J"+proj=omerc +lon_1=-1 +lat_1=1 +lon_2=0 +lat_2=0"
mapproject [INFORMATION]: Converted to -J syntax = -Joc-1/1/0/0/1:1 ...
349567.574844   6839490.49645

Interesting. Let’s give it a try with that -Joc,

$ echo 12 55 | gmt mapproject -V -Joc-1/1/0/0/1:1
mapproject [ERROR]: Must specify -R option

Well OK, but no -R I tried couldn’t get the same answer as above, all thousands away.

Wait, proj.org documents say:

the azimuth is given indirectly by specifying two points on the
central line, using the options +lat_1, +lon_1, +lat_2, and +lon_2.

And https://docs.generic-mapping-tools.org/dev/cookbook/options.html#projections-specifications says

Oblique Mercator, 1: origin and azim -Jo|O[a|A] -Jomerc/ lon0/lat0/azim/scale|width [+v]
Oblique Mercator, 2: two points -Jo|O[b|B] -Jomerc/ lon0/lat0/lon1/lat1/scale|width[+v]
Oblique Mercator, 3: origin and pole -Jo|O[c|C] -Jomercp/ lon0/lat0/lonp/latp/scale|width[+v]

So -V above saying that it is converting to -Joc, perhaps should say
-Job, which is the two point method.

However using -Job, (and -Joa too, while we’re at it) still don’t give
the answer above.

By the way, if one can draw a line from some X,Y to 0,0, then why can’t
one do the opposite? Why does GMT have the same inability as