# Deciphering the Documentation and writing a tutorial (edited) **URL:** \ **Category:** Lounge\ **Created:** [January 15, 2024, 3:11am UTC](https://forum.generic-mapping-tools.org/t/deciphering-the-documentation-and-writing-a-tutorial-edited/4602 "2024-01-15T03:11:02Z")\ **Posts on this page:** 7\ **Page:** 1
**Author:** ![MollyJ](https://yyz1.discourse-cdn.com/flex047/user_avatar/forum.generic-mapping-tools.org/mollyj/32/3867_2.png) [@MollyJ](https://forum.generic-mapping-tools.org/u/MollyJ)\ **Post date:** [January 15, 2024, 3:11am UTC](https://forum.generic-mapping-tools.org/t/deciphering-the-documentation-and-writing-a-tutorial-edited/4602/1 "2024-01-15T03:11:02Z")
Hallo GMT group. I am gradually getting the hang of the GMT syntax. I am grateful for your patience with me. The forum text editor keeps breaking my formatting, sorry. M.J. (I have edited this post several times before clicking the commit button as I continue to cross reference the documentation. Please bear with some of my ignorance.) Here, I read a 3600px by 1800px Plate-Carree png and reproject it to Orthographic over Cardiff. gmt grdimage -JG+03/51/5 -Rd basic.png -png cardiff-JG-5 The image looks as I expect. Display SmileyFace !! Yay ! Scale set to 1 gives a 118 px square image ? What scale does that ? Scale set to 5 gives a 591 px square image ? I cannot work out the units GMT is working with here. Is it pixels per centimeter? Is scale looking for centimetres ? (I'm just coming right out and saying this is weird) (unless GMT is focused on print media, in which case it's very logical) The JG perspective options are a bit troublesome. I get nonsence results or errors. As I add one by one the options described in the documentation, I try to work out the expected range of inputs without success. This projection example is from the university of Hawaii GMT page: -Jg|G\/\/\|\[+a\][+t\][+v\/\][+w\][+z\[r|R]|g] I break it down here: -Jg|G (upper/lower case indicates the type of scale to print?) \=degrees (0 to 360 | -180 to 0 to +180) /\=degrees (-90 to +90) /\|\ unknown format | unknown units [+a\] Degrees (0 to 360 or other ?) [+t\] (0 to 90 or 0 to 180 yaw? roll? pitch?) [+v\ (unknown units unknown function) / \] (is this oblique "/" a typo? is it meant to be "|" ) (or is it meant to be a ratio? W/H ? what's the point of that ?) (what is vertical width? ) [+w\] (degrees ? roll) [+z\ (unknown units earth-radii ? Km ? ) [r|R]|g] (still working on this one) I have been poring over the docs but there is a dearth of examples with accompanying illustrations. Documentation source: http://gmt.soest.hawaii.edu/doc/latest/gmt.html ---
**Author:** ![MollyJ](https://yyz1.discourse-cdn.com/flex047/user_avatar/forum.generic-mapping-tools.org/mollyj/32/3867_2.png) [@MollyJ](https://forum.generic-mapping-tools.org/u/MollyJ)\ **Post date:** [January 15, 2024, 3:35am UTC](https://forum.generic-mapping-tools.org/t/deciphering-the-documentation-and-writing-a-tutorial-edited/4602/2 "2024-01-15T03:35:48Z")
I may have neglected to explain the project... sorry. I am an historian working as an archivist but I also write code that amateur astronomy people use. I am upgrading scripts that convert JPL images to Plate-Carre format so they can be used in 3D image rendering apps. (PovRay, Blender, xPlanet, etc.) These scripts currently rely on MMPS, ImageMagick, Bash, and some other Linux commands. I want to use components that are more precise, cross platform, and are compatable with a variety of graphical user interfaces (probably wrapped in Python). Gdal is an option but seems to have a flaw in rendering a complete Equidistant Cylidrical projection from perspective or orthographic image sources. I am now exploring GMT's capabilities. I am not a G.I.S. professional so I am going to make many mistakes interpreting industry jargon and translating to traditional, imaging, or celestial terms. I believe in the Feynman hypothisis that only the ability to teach a topic indicates true understanding, so I will be composing a tutorial of my own for the use by my intended audience. For this reason I may ask astonishingly naiive questions such as "Do ESRI numbers refer to ellipsoids and geoids and projections?" etc. Although I may occasionally sound stu[pid, I am not. I am one of the forum moderators at xplanet and I wrote the TravellerWorldViewer web application. I know, not much. anyway, that's why I'm here, why I'm involved, and why I will be asking questions as I zoom through the documentation. Morfydd James (Molly) ---
**Author:** ![Joaquim](https://yyz1.discourse-cdn.com/flex047/user_avatar/forum.generic-mapping-tools.org/joaquim/32/16_2.png) [@Joaquim](https://forum.generic-mapping-tools.org/u/Joaquim)\ **Post date:** [January 15, 2024, 11:53am UTC](https://forum.generic-mapping-tools.org/t/deciphering-the-documentation-and-writing-a-tutorial-edited/4602/3 "2024-01-15T11:53:49Z")
Like I mentioned in the other answer, please post a reproducible example. And two other things - You should be using latest release, namely GMT6.5 - The GMT documentation is at [https://docs.generic-mapping-tools.org/6.5/](https://docs.generic-mapping-tools.org/6.5/) ---
**Author:** ![MollyJ](https://yyz1.discourse-cdn.com/flex047/user_avatar/forum.generic-mapping-tools.org/mollyj/32/3867_2.png) [@MollyJ](https://forum.generic-mapping-tools.org/u/MollyJ)\ **Post date:** [January 15, 2024, 9:00pm UTC](https://forum.generic-mapping-tools.org/t/deciphering-the-documentation-and-writing-a-tutorial-edited/4602/4 "2024-01-15T21:00:24Z")
Thank you Joaquim, I have been studying documentation from several sources including the official ones at this domain. I cited the U.Hawaii page as that one had the example. I am restricted to version 6.3.0 as that is the one available to my inteded audience. They will be using the gmt package provided by the ubuntu/debian repositories. My tests: Molly’s GMT test: Input basic.png is 3600x1800 plate-carre Earth gmt grdimage -JG+5/+50/20 -Rd basic.png -png map\_JG-5 (Successful 20cm orthographic image centered on Cardiff ! Yay !) gmt grdimage -JG+5/+50/20 +a30 +t5 +v1 +w0 +z5 -Rd basic.png -png map\_JG-5 gmt [ERROR]: Cannot run a one-liner modern command within an existing modern mode session Do I need to “Clear” something ? From the man page: -Jg|G lon0 / lat0 / scl | width [+a azimuth] [+t tilt] [+v vwidth / vheight] [+w twist] [+z altitude [r|R]|g] (General Perspective) Question one -- Is it manditory that the perspective parameters be within a gmt script ? Is it impossible to output a specific view with one line of code? Question two -- Does gmt have an inverse projection function? Can I reproject from ortho back to plate-carree ? Thank you again for your patience. As I build up a set of working examples, I will be able to use them as templates for further trial and error study. This will be essential for the tutorial for my imaging scripts. --Molly ---
**Author:** ![Joaquim](https://yyz1.discourse-cdn.com/flex047/user_avatar/forum.generic-mapping-tools.org/joaquim/32/16_2.png) [@Joaquim](https://forum.generic-mapping-tools.org/u/Joaquim)\ **Post date:** [January 15, 2024, 11:01pm UTC](https://forum.generic-mapping-tools.org/t/deciphering-the-documentation-and-writing-a-tutorial-edited/4602/5 "2024-01-15T23:01:08Z")
> [@MollyJ](#): > > gmt grdimage -JG+5/+50/20 -Rd basic.png -png map\_JG-5 > (Successful 20cm orthographic image centered on Cardiff ! Yay !) > > gmt grdimage -JG+5/+50/20 +a30 +t5 +v1 +w0 +z5 -Rd basic.png -png map\_JG-5 > > gmt [ERROR]: Cannot run a one-liner modern command within an existing modern mode session And no errors between first and second `grdimage` commands? > [@MollyJ](#): > > Do I need to “Clear” something ? Yes. Need to do `gmt clear sessions`. But this is only necessary when a previous error left behind and non-finished session. > [@MollyJ](#): > > From the man page: > -Jg|G lon0 / lat0 / scl | width [+a azimuth] [+t tilt] [+v vwidth / vheight] [+w twist] [+z altitude [r|R]|g] (General Perspective) The old docs show that? New show **Syntax** > **-Jg** | **G** _lon0/lat0_ _/scale|width[+a__azimuth_][**+t** _tilt_][**+v** _vwidth/vheight_][**+w** _twist_][**+z** _altitude_[ **r** | **R**]| **g** ] _i.e._, the GMT golden rule **no spaces inside option strings** > [@MollyJ](#): > > Question one – Is it manditory that the perspective parameters be within a gmt script ? Is it impossible to output a specific view with one line of code? Yes, they are called _one-liners_ and you used them (docs explain it) > [@MollyJ](#): > > Question two – Does gmt have an inverse projection function? Can I reproject from ortho back to plate-carree ? The official answer is no. One need to make the tour _proj1 → geog → proj2_ but it’s actually not impossible that we can. Since PROJ created the pipelines we can go directly from `proj1 -> proj2` and since we accept proj strings in GMT it is not impossible that it can be done, but I never tried. Note that here I’m talking only in image reprojections, not map-making that has different issues. > [@MollyJ](#): > > I am restricted to version 6.3.0 as that is the one available to my inteded audience. They will be using the gmt package provided by the ubuntu/debian repositories. Now this is bad, really bad. See, we spend 3 years fixing and improving things and next users, not rarely, come asking for help for things that … have been fixed meanwhile. Manipulating images in GMT is one of those cases. ---
**Author:** ![MollyJ](https://yyz1.discourse-cdn.com/flex047/user_avatar/forum.generic-mapping-tools.org/mollyj/32/3867_2.png) [@MollyJ](https://forum.generic-mapping-tools.org/u/MollyJ)\ **Post date:** [January 15, 2024, 11:22pm UTC](https://forum.generic-mapping-tools.org/t/deciphering-the-documentation-and-writing-a-tutorial-edited/4602/6 "2024-01-15T23:22:37Z")
Thank you Joaquim. > [@MollyJ](#): > > gmt grdimage -JG+5/+50/20 +a30 +t5 +v1 +w0 +z5 -Rd basic.png -png map\_JG-5 What does the correct command look like ? ---
**Author:** ![Joaquim](https://yyz1.discourse-cdn.com/flex047/user_avatar/forum.generic-mapping-tools.org/joaquim/32/16_2.png) [@Joaquim](https://forum.generic-mapping-tools.org/u/Joaquim)\ **Post date:** [January 15, 2024, 11:40pm UTC](https://forum.generic-mapping-tools.org/t/deciphering-the-documentation-and-writing-a-tutorial-edited/4602/7 "2024-01-15T23:40:19Z")
> [@MollyJ](#): > > gmt grdimage -JG+5/+50/20 +a30 +t5 +v1 +w0 +z5 -Rd basic.png -png map\_JG-5 No spaces inside the **-J** option gmt grdimage -JG5/50/20+a30+t5+v1+w0+z5 -Rd basic.png -png map\_JG-5