Improve documentation plotting of interrupted projections. (#3144)

Improves the documentation plotting code by adding checks for interrupted lines and graticules. This does not replace the continental outlines with filled continents because that is a harder job. A number of plots has been improved and included in the docs.

Also fixes a typo on the ob_tran plot so that it now renders as intended according to the description paragraph as an oblique Mollweide rather than oblique Miller Cylindrical, which is neither a common nor attractive projection.

docs/plot/plot.py

@@ -239,6 +239,27 @@ def resample_polygon(polygon):
     return Polygon(ext, rings)
 
 
+def plot_with_interruptions(axes, x, y, delta_cut=1e100, **kwargs):
+    """
+    Plot x/y with proper splitting for interrupted projections.
+    """
+    _x = np.atleast_1d(x)
+    _y = np.atleast_1d(y)
+
+    dx = np.nan_to_num(_x[1: ]) - np.nan_to_num(_x[0: -1])
+    dy = np.nan_to_num(_y[1: ]) - np.nan_to_num(_y[0: -1])
+    split, = ((np.abs(dx) > delta_cut) | (np.abs(dy) > delta_cut)).nonzero()
+    split = np.append(split, _x.size - 1)
+    split += 1
+
+    last_part = 0
+    for part in split:
+        axes.plot(x[last_part: part],
+                  y[last_part: part],
+                  **kwargs)
+        last_part = part
+
+
 def plotproj(plotdef, data, outdir):
     '''
     Plot map.
@@ -275,7 +296,8 @@ def plotproj(plotdef, data, outdir):
                 pass
         else:
             x, y = proj_geom.xy
-            axes.plot(x, y, color=COLOR_COAST, linewidth=0.5)
+            plot_with_interruptions(axes, x, y, color=COLOR_COAST, linewidth=0.5,
+                                    delta_cut=plotdef.get('delta_cut', 1e100))
 
     # Plot frame
     frame = [
@@ -286,7 +308,8 @@ def plotproj(plotdef, data, outdir):
         line = project(line, plotdef['projstring'])
         x = line[:, 0]
         y = line[:, 1]
-        axes.plot(x, y, '-k')
+        plot_with_interruptions(axes, x, y, color='black', linestyle='-',
+                                delta_cut=plotdef.get('delta_cut', 1e6))
 
     graticule = build_graticule(
         plotdef['lonmin'],
@@ -300,7 +323,28 @@ def plotproj(plotdef, data, outdir):
         feature = project(feature, plotdef['projstring'])
         x = feature[:, 0]
         y = feature[:, 1]
-        axes.plot(x, y, color=COLOR_GRAT, linewidth=0.4)
+        plot_with_interruptions(axes, x, y, color=COLOR_GRAT, linewidth=0.4,
+                                delta_cut=plotdef.get('delta_cut', 1e6))
+
+    # Plot interrupted boundaries if necessary
+    interrupted_lines = []
+    if 'top_interrupted_lons' in plotdef:
+        for lon in plotdef['top_interrupted_lons']:
+            for delta in [-0.0001, 0.0001]:
+                merid = meridian(lon + delta, 0.0, plotdef['latmax'])
+                interrupted_lines.append(project(merid, plotdef['projstring']))
+
+    if 'bottom_interrupted_lons' in plotdef:
+        for lon in plotdef['bottom_interrupted_lons']:
+            for delta in [-0.0001, 0.0001]:
+                merid = meridian(lon + delta, plotdef['latmin'], 0)
+                interrupted_lines.append(project(merid, plotdef['projstring']))
+
+    for line in interrupted_lines:
+        x = line[:, 0]
+        y = line[:, 1]
+        plot_with_interruptions(axes, x, y, color=COLOR_GRAT, linewidth=0.4,
+                                delta_cut=plotdef.get('delta_cut', 1e100))
 
     # Switch off the axis lines...
     plt.axis('off')

docs/plot/plotdefs.json

@@ -145,7 +145,8 @@
         "name": "bipc",
         "projstring": "+proj=bipc +ns",
         "res": "low",
-        "type": "line"
+        "type": "line",
+        "delta_cut": 1e6
     },
     {
         "filename": "boggs.png",
@@ -552,7 +553,10 @@
         "name": "igh",
         "projstring": "+proj=igh",
         "res": "low",
-        "type": "line"
+        "type": "line",
+        "top_interrupted_lons": [-40.0],
+        "bottom_interrupted_lons": [80.0, -20.0, -100.0],
+        "delta_cut": 7e5
     },
     {
         "filename": "igh_o.png",
@@ -563,7 +567,10 @@
         "name": "igh_o",
         "projstring": "+proj=igh_o +lon_0=-160",
         "res": "low",
-        "type": "line"
+        "type": "line",
+        "top_interrupted_lons": [110.0, 20.0, -100.0],
+        "bottom_interrupted_lons": [-70.0, 20.0, 140.0],
+        "delta_cut": 7e5
     },
     {
         "filename": "imw_p.png",
@@ -585,7 +592,8 @@
         "name": "isea",
         "projstring": "+proj=isea",
         "res": "low",
-        "type": "line"
+        "type": "line",
+        "delta_cut": 1e6
     },
     {
         "filename": "kav5.png",
@@ -740,7 +748,8 @@
         "name": "lsat",
         "projstring": "+proj=lsat +ellps=GRS80 +lat_1=-60 +lat_2=60 +lsat=2 +path=2",
         "res": "low",
-        "type": "line"
+        "type": "line",
+        "delta_cut": 1e6
     },
     {
         "filename": "mbt_s.png",
@@ -839,7 +848,8 @@
         "name": "misrsom",
         "projstring": "+proj=misrsom +path=1",
         "res": "low",
-        "type": "line"
+        "type": "line",
+        "delta_cut": 1e7
     },
     {
         "filename": "moll.png",
@@ -969,7 +979,7 @@
         "lonmax": 180,
         "lonmin": -180,
         "name": "ob_tran",
-        "projstring": "+proj=ob_tran +o_proj=mill +o_lon_p=40 +o_lat_p=50 +lon_0=60",
+        "projstring": "+proj=ob_tran +o_proj=moll +o_lon_p=40 +o_lat_p=50 +lon_0=60",
         "res": "low",
         "type": "poly"
     },
@@ -1004,7 +1014,8 @@
         "name": "omerc",
         "projstring": "+proj=omerc +lat_1=45 +lat_2=55",
         "res": "low",
-        "type": "line"
+        "type": "line",
+        "delta_cut": 1e6
     },
     {
         "filename": "ortel.png",
@@ -1081,7 +1092,8 @@
         "name": "peirce_q_horizontal",
         "projstring": "+proj=peirce_q +lon_0=25 +shape=horizontal",
         "res": "low",
-        "type": "line"
+        "type": "line",
+        "delta_cut": 1e6
     },
     {
         "filename": "grieger_triptychial.png",
@@ -1312,7 +1324,8 @@
         "name": "gstmerc",
         "projstring": "+proj=gstmerc",
         "res": "low",
-        "type": "line"
+        "type": "line",
+        "delta_cut": 1e7
     },
     {
         "filename": "tcc.png",
@@ -1334,7 +1347,8 @@
         "name": "tcea",
         "projstring": "+proj=tcea",
         "res": "low",
-        "type": "line"
+        "type": "line",
+        "delta_cut": 1e6
     },
     {
         "filename": "times.png",
@@ -1444,7 +1458,8 @@
         "name": "utm",
         "projstring": "+proj=utm",
         "res": "low",
-        "type": "line"
+        "type": "line",
+        "delta_cut": 1e6
     },
     {
         "filename": "vandg.png",

docs/source/operations/projections/ob_tran.rst

@@ -26,7 +26,7 @@ General Oblique Transformation
    :align: center
    :alt:   General Oblique Transformation
 
-   proj-string: ``+proj=ob_tran +o_proj=mill +o_lon_p=40 +o_lat_p=50 +lon_0=60``
+   proj-string: ``+proj=ob_tran +o_proj=moll +o_lon_p=40 +o_lat_p=50 +lon_0=60``
 
 Usage
 ################################################################################