Deprecate the ugly perspective -JG syntax and introduce a modern form

doc/examples/anim09/anim09.sh

@@ -38,12 +38,12 @@ cat << 'EOF' > main.sh
 # Main frame script that makes a single frame given the location and twist from the data file
 # and the other view parameters from the include file.
 gmt begin
-	gmt grdimage -Rg -JG${MOVIE_COL0}/${MOVIE_COL1}/${ALTITUDE}/${MOVIE_COL2}/${TILT}/${MOVIE_COL3}/${WIDTH}/${HEIGHT}/${MOVIE_WIDTH} \
-	  -Y0 -X0 @earth_relief_30s -I/tmp/earth_relief_30s+2.5_int.nc -CMOR_topo.cpt
+	gmt grdimage -Rg -JG${MOVIE_COL0}/${MOVIE_COL1}/${MOVIE_WIDTH}+z${ALTITUDE}+a${MOVIE_COL2}+t${TILT}+w${MOVIE_COL3}+v${WIDTH}/${HEIGHT} \
+	  -Y0 -X0 @earth_relief_30s -Iearth_relief_30s+2.5_int.nc -CMOR_topo.cpt
 	gmt events MOR_names.txt -L100 -Et+r6+f6 -T${MOVIE_FRAME} -F+f12p,Helvetica-Bold,yellow
 gmt end
 EOF
 # 3. Run the movie
 gmt set PROJ_LENGTH_UNIT inch FONT_TAG 20p,Helvetica,white
-gmt movie main.sh -Iinclude.sh -CHD -Sbpre.sh -TMOR_PAC_twist_path.txt -Nanim09 -D24 -H4 -K -M2000,png -Gblack -Le+jTR -Lf -V -W -Zs
+gmt movie main.sh -Iinclude.sh -CHD -Sbpre.sh -TMOR_PAC_twist_path.txt -Nanim09 -D24 -H4 -K -M2000,png -Fmp4 -Gblack -Le+jTR -Lf -V -W -Zs
 rm -f gmt.conf

doc/examples/ex26/ex26.sh

@@ -9,13 +9,8 @@ gmt begin ex26
 	latitude=41.5
 	longitude=-74
 	altitude=160
-	tilt=0
-	azimuth=0
-	twist=0
-	Width=0
-	Height=0
 
-	PROJ=-JG${longitude}/${latitude}/${altitude}/${azimuth}/${tilt}/${twist}/${Width}/${Height}/10c
+	PROJ=-JG${longitude}/${latitude}/10c+z${altitude}
 	gmt coast -Rg $PROJ -B5g5 -Glightbrown -Slightblue -W -Dl -N1/1p,red -N2/0.5p -Y12c
 
 	# now point from an altitude of 160 km with a specific tilt and azimuth and with a wider restricted
@@ -26,6 +21,6 @@ gmt begin ex26
 	Width=30
 	Height=30
 
-	PROJ=-JG${longitude}/${latitude}/${altitude}/${azimuth}/${tilt}/${twist}/${Width}/${Height}/12c
+	PROJ=-JG${longitude}/${latitude}/12c+z${altitude}+a${azimuth}+t${tilt}+w${twist}+v${Width}/${Height}
 	gmt coast $PROJ -B5g5 -Glightbrown -Slightblue -W -Ia/blue -Di -Na -X1i -Y-10c
 gmt end show

doc/rst/source/basemap.rst

@@ -368,7 +368,7 @@ and height will product a 6-inch-wide basemap:
 
    ::
 
-    gmt basemap -Rg -JG-74/41.5/160/210/55/30/30/6i -Bafg -B+t"General Perspective" -pdf genper
+    gmt basemap -Rg -JG-74/41.5/6i+z160+a210+t55+v30 -Bafg -B+t"General Perspective" -pdf genper
 
 Stereographic [conformal]
 ~~~~~~~~~~~~~~~~~~~~~~~~~

doc/rst/source/cookbook/map-projections.rst

@@ -404,24 +404,27 @@ Perspective projection (**-Jg** **-JG**)
 
 **Syntax**
 
-    **-Jg**\|\ **G**\ *lon0/lat0/altitude/azimuth/tilt/twist/Width/Height/*\ *scale*\|\ *width*
+    **-Jg**\|\ **G**\ *lon0/lat0*\ [*/horizon*]\ */*\ *scale*\|\ *width*\ [**+a**\ *azimuth*][**+t**\ *tilt*][**+v**\ *vwidth/vheight*][**+w**\ *twist*][**+z**\ *altitude*]
 
-**Parameters**
+**Required Parameters**
 
 - The longitude (*lon0*) and latitude (*lat0*) of the projection center.
-- The *altitude* of the viewer above sea level in kilometers. If this value is less than 10, it is assumed to instead be
-  the distance of the viewer from the center of the earth in earth radii. If **r** is appended, it is assumed to instead
-  be the distance from the center of the earth in kilometers.
-- The *azimuth* in degrees. This is the direction in which you are looking, measured clockwise from north.
-- The *tilt* in degrees. This is the viewing angle relative to zenith. For example, a tilt of 0° is looking straight
-  down, and 60° is looking from 30° above the horizon.
-- The *twist* in degrees. This is the boresight rotation (clockwise) of the image.
-- The *Width* and *Height* of the viewpoint in degrees. This number depends on whether you are looking with the naked
-  eye (in which case the view is about 60° wide), or with binoculars, for example.
 - The *scale* as 1:xxxxx or as radius/latitude where radius is distance on map in :ref:`plot-units <plt-units>` from
   projection center to a particular oblique latitude (with **-Jg**), or map width in :ref:`plot-units <plt-units>`
   (with **-JG**).
 
+**Optional Parameters**
+
+- The *azimuth* in degrees. This is the direction in which you are looking, measured clockwise from north [0].
+- The *tilt* in degrees. This is the viewing angle relative to zenith. For example, a tilt of 0° is looking straight
+  down, and 60° is looking from 30° above the horizon [0].
+- The *vwidth* and *vheight* of the viewpoint in degrees. This number depends on whether you are looking with the naked
+  eye (in which case the view is about 60° wide), or with binoculars, for example [unrestricted].
+- The *twist* in degrees. This is the boresight rotation (clockwise) of the image [0].
+- The *altitude* of the viewer above sea level in kilometers. If this value is less than 10, it is assumed to instead be
+  the distance of the viewer from the center of the earth in earth radii. If **r** is appended, it is assumed to instead
+  be the distance from the center of the earth in kilometers [infinity].
+
 **Description**
 
 The perspective projection imitates in 2 dimensions the 3-dimensional view of the earth from space. The implementation
@@ -431,7 +434,7 @@ in GMT is very flexible, and thus requires many input variables.
 
 The imagined view of northwest Europe from a Space Shuttle at 230 km looking due east is thus accomplished by the
 following :doc:`/coast` command (*lon0*\ =4; *lat0*\ =52; *altitude*\ =230 km; *azimuth*\ = 90°; *tilt*\ = 60°;
-*twist*\ = 180°; *Width*\ = 60°; *Height*\ = 60°; and *width* = 12 cm):
+*twist*\ = 180°; *vwidth*\ = *vheight*\ = 60°; and *width* = 12 cm):
 
 .. literalinclude:: /_verbatim/GMT_perspective.txt
 

doc/rst/source/explain_-J.rst_

@@ -205,15 +205,19 @@ respectively):
         *lon0/lat0* specifies the projection center. *horizon* specifies the max distance from projection center (in
         degrees, <= 90, default 90). Give *scale* (with **-Jg**; as **1:**\ *xxxx* or *radius/lat*, where *radius* is
         distance in :ref:`plot-units <plt-units>` from origin to the oblique latitude *lat*.
-    **-Jg**\|\ **G**\ *lon0/lat0/altitude/azimuth/tilt/twist/Width/Height/*\ *scale*\|\ *width* (General Perspective).
-        *lon0/lat0* specifies the projection center. *altitude* is the height (in km) of the viewpoint above local sea
-        level. If *altitude* is less than 10, then it is the distance from the center of the earth to the viewpoint in
-        earth radii. If *altitude* has a suffix **r** then it is the radius from the center of the earth in kilometers.
-        *azimuth* is measured to the east of north of view. *tilt* is the upward tilt of the plane of projection. If
-        *tilt* is negative, then the viewpoint is centered on the horizon. Further, specify the clockwise *twist*,
-        *Width*, and *Height* of the viewpoint in degrees. Give *scale* (with **-Jg**; as **1:**\ *xxxx* or
-        *radius/lat*, where *radius* is distance in :ref:`plot-units <plt-units>` from origin to the oblique latitude
-        *lat*) or width (with **-JG**; in :ref:`plot-units <plt-units>`).
+    **-Jg**\|\ **G**\ *lon0/lat0*\ /\ *scale*\|\ *width*\ [**+a**\ *azimuth*][**+t**\ *tilt*][**+v**\ *vwidth/vheight*][**+w**\ *twist*][**+z**\ *altitude*] (General Perspective).
+        *lon0/lat0* specifies the projection center. Give *scale* (with **-Jg**; as **1:**\ *xxxx* or *radius/lat*,
+        where *radius* is distance in :ref:`plot-units <plt-units>` from origin to the oblique latitude *lat*) or width
+        (with **-JG**; in :ref:`plot-units <plt-units>`). Several optional modifiers control the perspective:
+
+     - **+a** sets *azimuth* measured to the east of north of view [0].
+     - **+t** sets the upward *tilt* of the plane of projection. If
+       *tilt* is negative, then the viewpoint is centered on the horizon [0].
+     - **+v** sets a restricted view: *vwidth* and *vheight* ( in degrees) limits the view from the viewpoint [unrestricted].
+     - **+w** sets the clockwise *twist* of the viewpoint (in degrees) [0].
+     - **+z** sets the *altitude* (in km) of the viewpoint above local sea level [infinity]. If *altitude* is less than 10, then
+       it is the distance from the center of the earth to the viewpoint in earth radii. If *altitude* has a suffix **r**
+       then it is the radius from the center of the earth in kilometers.
 
 .. _-Js_full:
 

doc/rst/source/psbasemap.rst

@@ -300,7 +300,7 @@ and height will product a 6-inch-wide basemap:
 
    ::
 
-    gmt psbasemap -Rg -JG-74/41.5/160/210/55/30/30/6i -Bafg -B+t"General Perspective" -P > genper.ps
+    gmt psbasemap -Rg -JG-74/41.5/6i+z160+a210+t55+v30 -Bafg -B+t"General Perspective" -P > genper.ps
 
 Stereographic [conformal]
 ~~~~~~~~~~~~~~~~~~~~~~~~~

doc/scripts/GMT_perspective.sh

@@ -1,2 +1,2 @@
 #!/usr/bin/env bash
-gmt coast -Rg -JG4/52/230/90/60/180/60/60/12c -Bx2g2 -By1g1 -Ia -Di -Glightbrown -Wthinnest -Slightblue --GMT_THEME=cookbook --MAP_ANNOT_MIN_SPACING=0.6c -ps GMT_perspective
+gmt coast -Rg -JG4/52/12c+z230+a90+t60+w180+v60 -Bx2g2 -By1g1 -Ia -Di -Glightbrown -Wthinnest -Slightblue --GMT_THEME=cookbook --MAP_ANNOT_MIN_SPACING=0.6c -ps GMT_perspective