Add examples for the oblique mercator projection (#1251)

Co-authored-by: Will Schlitzer <[email protected]>
Co-authored-by: Michael Grund <[email protected]>
Co-authored-by: Dongdong Tian <[email protected]>

Author: 4 people

examples/projections/cyl/cyl_oblique_mercator_1.py

@@ -0,0 +1,32 @@
+"""
+Oblique Mercator
+================
+
+Oblique configurations of the cylinder give rise to the oblique Mercator
+projection. It is particularly useful when mapping regions of large lateral
+extent in an oblique direction. Both parallels and meridians are complex
+curves. The projection was developed in the early 1900s by several workers.
+
+**oa**\|\ **oA**\ *lon0/lat0/azimuth/scale*\[**+v**] or
+**Oa**\|\ **OA**\ *lon0/lat0/azimuth/width*\[**+v**]
+
+The projection is set with **o** or **O**. The pole is set in the 
+northern hemisphere with **a** or the southern hemisphere 
+with **A**. The central meridian is set by *lon0/lat0*. The oblique equator 
+is set by *azimuth*. Align the y-axis
+with the optional **+v**. The figure size is set with *scale* or *width*.
+"""
+import pygmt
+
+fig = pygmt.Figure()
+# Using the origin and azimuth
+fig.coast(
+    projection="Oa-120/25/-30/6c+v",
+    # Set bottom left and top right coordinates of the figure with "+r"
+    region="-122/35/-107/22+r",
+    frame="afg",
+    land="gray",
+    shorelines="1/thin",
+    water="lightblue",
+)
+fig.show()

examples/projections/cyl/cyl_oblique_mercator_2.py

@@ -0,0 +1,32 @@
+"""
+Oblique Mercator
+================
+
+Oblique configurations of the cylinder give rise to the oblique Mercator
+projection. It is particularly useful when mapping regions of large lateral
+extent in an oblique direction. Both parallels and meridians are complex
+curves. The projection was developed in the early 1900s by several workers.
+
+**ob**\|\ **oB**\ *lon0/lat0/lon1/lat1/scale*\ [**+v**] or
+**Ob**\|\ **OB**\ *lon0/lat0/lon1/lat1/width*\ [**+v**]
+
+The projection is set with **o** or **O**. The pole is set in the 
+northern hemisphere with **b** or the southern hemisphere 
+with **B**. The central meridian is set by *lon0/lat0*. The oblique 
+equator is set by *lon1/lat1*. Align the y-axis
+with the optional **+v**. The figure size is set with *scale* or *width*.
+"""
+import pygmt
+
+fig = pygmt.Figure()
+# Using the origin and two points
+fig.coast(
+    projection="Ob130/35/25/35/6c",
+    # Set bottom left and top right coordinates of the figure with "+r"
+    region="130/35/145/40+r",
+    frame="afg",
+    land="gray",
+    shorelines="1/thin",
+    water="lightblue",
+)
+fig.show()

examples/projections/cyl/cyl_oblique_mercator_3.py

@@ -0,0 +1,31 @@
+"""
+Oblique Mercator
+================
+
+Oblique configurations of the cylinder give rise to the oblique Mercator
+projection. It is particularly useful when mapping regions of large lateral
+extent in an oblique direction. Both parallels and meridians are complex
+curves. The projection was developed in the early 1900s by several workers.
+
+**oc**\|\ **oC**\ *lon0/lat0/lonp/latp/scale*\ [**+v**] or
+**Oc**\|\ **OC**\ *lon0/lat0/lonp/latp/width*\ [**+v**]
+
+The projection is set with **o** or **O**. The central meridian is set
+by *lon0/lat0*. The projection pole is set by *lonp/latp* in option three.
+Align the y-axis with the optional **+v**. The figure size is set
+with *scale* or *width*.
+"""
+import pygmt
+
+fig = pygmt.Figure()
+# Using the origin projection pole
+fig.coast(
+    projection="Oc280/25.5/22/69/12c",
+    # Set bottom left and top right coordinates of the figure with "+r"
+    region="270/20/305/25+r",
+    frame="afg",
+    land="gray",
+    shorelines="1/thin",
+    water="lightblue",
+)
+fig.show()

examples/projections/table/README.txt

@@ -53,11 +53,11 @@ The below table shows the projection codes for the 31 GMT projections.
    * - **N**\ [|lon0|/]\ *width*
      - :doc:`Robinson </projections/misc/misc_robinson>`
    * - **Oa**\ |lon0|/|lat0|/\ *azim*/*width*\ [**+v**]
-     - Oblique Mercator, 1: origin and azim
+     - :doc:`Oblique Mercator, 1: origin and azim </projections/cyl/cyl_oblique_mercator_1>`
    * - **Ob**\ |lon0|/|lat0|/|lon1|/|lat1|/\ *width*\ [**+v**]
-     - Oblique Mercator, 2: two points
+     - :doc:`Oblique Mercator, 2: two points </projections/cyl/cyl_oblique_mercator_2>`
    * - **Oc**\ |lon0|/|lat0|/|lonp|/|latp|/\ *width*\ [**+v**]
-     - Oblique Mercator, 3: origin and pole
+     - :doc:`Oblique Mercator, 3: origin and pole </projections/cyl/cyl_oblique_mercator_3>`
    * - **P**\ *width*\ [**+a**]\ [**+f**\ [**e**\|\ **p**\|\ *radius*]]\
        [**+r**\ *offset*][**+t**\ *origin*][**+z**\ [**p**\|\ *radius*]]
      - :doc:`Polar </projections/nongeo/polar>` [azimuthal]