Splitting of the projections gallery into projection types and complete the examples for azimuthal projections

.gitignore

@@ -10,6 +10,7 @@
 MANIFEST
 .pytest_cache/
 .ipynb_checkpoints/
+.vscode/
 build/
 dist/
 doc/_build
@@ -18,4 +19,4 @@ doc/gallery
 doc/tutorials
 doc/projections
 doc/api/gmt*.rst
-doc/api/generated
+doc/api/generated

doc/conf.py

@@ -56,7 +56,15 @@
     # path where to save gallery generated examples
     "gallery_dirs": ["gallery", "tutorials", "projections"],
     "subsection_order": ExplicitOrder(
-        ["../examples/gallery/coast", "../examples/gallery/plot"]
+        [
+            "../examples/gallery/coast",
+            "../examples/gallery/plot",
+            "../examples/projections/azim",
+            "../examples/projections/conic",
+            "../examples/projections/cyl",
+            "../examples/projections/misc",
+            "../examples/projections/nongeo",
+        ]
     ),
     # Patter to search for example files
     "filename_pattern": r"\.py",

examples/projections/azim/README.txt

@@ -0,0 +1,2 @@
+Azimuthal Projections
+---------------------

examples/projections/azim/azim_equidistant.py

@@ -0,0 +1,21 @@
+"""
+Azimuthal Equidistant
+=====================
+
+The main advantage of this projection is that distances from the projection
+center are displayed in correct proportions. Also directions measured from the
+projection center are correct. It is very useful for a global view on locations
+that lie within a certain distance or for comparing distances of different
+locations relative to the projection center.
+
+``elon0/lat0[/horizon]/scale`` or ``Elon0/lat0[/horizon]/width``
+
+``lon0/lat0`` specifies the projection center. The optional parameter
+``horizon`` specifies the max distance to the projection center (i.e. the
+visibile portion of the rest of the world map) in degrees <= 180° (default 180°).
+"""
+import pygmt
+
+fig = pygmt.Figure()
+fig.coast(projection="E-100/40/4.5i", region="g", frame="g", land="gray")
+fig.show()

examples/projections/azim/azim_general_perspective.py

@@ -0,0 +1,33 @@
+"""
+General Perspective
+===================
+
+The general perspective projection imitates the view of the Earth from a finite
+point in space. In a full view of the earth one third of its surface area can
+be seen.
+
+``lon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale`` or ``width``
+
+``lon0/lat0`` specifies the projection center, ``altitude`` 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). With ``azimuth`` the direction (in degrees) in which you are looking is
+specified, measured clockwise from north. ``tilt`` is given in degrees and is the
+viewing angle relative to zenith. A tilt of 0° is looking straight down, 60° is
+looking 30° above horizon. ``twist`` is the clockwise rotation of the image (in
+degrees). ``Width`` and ``Height`` describe the viewport angle in degrees.
+
+The example shows the coast of northern europe viewed from 250 km above sea
+level looking 30° from north at a tilt of 45°. The height and width of the
+viewing angle is both 60°, which imitates viewing with naked eye.
+"""
+import pygmt
+
+fig = pygmt.Figure()
+fig.coast(
+    projection="G4/52/250/30/45/0/60/60/5i",
+    region="g",
+    frame=["x10g10", "y5g5"],
+    land="gray",
+)
+fig.show()

examples/projections/azim/azim_general_stereographic.py

@@ -0,0 +1,28 @@
+"""
+General Stereographic
+=====================
+
+This map projection is a conformal, azimuthal projection. It is mainly used with
+a projection center in one of the poles. Then meridians appear as straight lines
+and cross latitudes at a right angle. Unlike the azimuthal equidistant projection,
+the distances in this projection are not displayed in correct proportions.
+It is often used as a hemisphere map like the Lambert Azimuthal Equal Area
+projection.
+
+``slon0/lat0[/horizon]/scale`` or ``Slon0/lat0[/horizon]/width``
+
+``lon0/lat0`` specifies the projection center, the optional ``horizon`` parameter
+specifies the max distance from projection center (in degrees, < 180, default 90).
+
+This projection can be displayed:
+
+* With map boundaries coinciding with longitude and latitude:
+  ``region`` specified via ``xmin/xmax/ymin/ymax``
+* As a map with rectangular boundaries: ``region`` specified as lower left and
+  upper right corner ``xlleft/ylleft/xuright/yurightr``. Note the appended ``r``.
+"""
+import pygmt
+
+fig = pygmt.Figure()
+fig.coast(region="4/14/52/57", projection="S0/90/4.5i", frame="ag", land="gray")
+fig.show()

examples/projections/azim/azim_gnomonic.py

@@ -0,0 +1,22 @@
+"""
+Gnomonic
+========
+
+The point of perspective of the gnomonic projection lies at the center of the
+earth. As a consequence great circles (orthodromes) on the surface of the earth
+are displayed as straight lines, which makes it suitable for distance estimation
+for navigational purposes. It is neither conformal nor equal-area and the
+distortion increases greatly with distance to the projection center. It follows
+that the scope of application is restricted to a small area around the
+projection center (at a maximum of 60°).
+
+``flon0/lat0[/horizon]/scale`` or ``Flon0/lat0[/horizon]/width``
+
+``lon0/lat0`` specify the projection center, the optional parameter ``horizon``
+specifies the max distance from projection center (in degrees, < 90, default 60).
+"""
+import pygmt
+
+fig = pygmt.Figure()
+fig.coast(projection="F-90/15/4.5i", region="g", frame="20g20", land="gray")
+fig.show()

examples/projections/azim/azim_orthographic.py

@@ -0,0 +1,20 @@
+"""
+Orthographic
+============
+
+This is a perspective projection like the general perspective,
+but with the difference that the point of perspective lies in infinite distance.
+It is therefore often used to give the appearance of a globe viewed from outer
+space, were one hemisphere can be seen as a whole. It is neither conformal nor
+equal-area and the distortion increases near the edges.
+
+``glon0/lat0[/horizon]/scale`` or ``Glon0/lat0[/horizon]/width``
+
+``lon0/lat0`` specifies the projection center, the optional parameter ``horizon``
+specifies the max distance from projection center (in degrees, <= 90, default 90)
+"""
+import pygmt
+
+fig = pygmt.Figure()
+fig.coast(projection="G10/52/4.5i", region="g", frame="g", land="gray")
+fig.show()

examples/projections/conic/README.txt

@@ -0,0 +1,2 @@
+Conic Projections
+-----------------

examples/projections/cyl/README.txt

@@ -0,0 +1,2 @@
+Cylindric Projections
+---------------------

examples/projections/misc/README.txt

@@ -0,0 +1,2 @@
+Miscellaneous Projections
+-------------------------

examples/projections/nongeo/README.txt

@@ -0,0 +1,2 @@
+Non-geographic Projections
+--------------------------