Merge branch 'main' into arg_with_space

Author: weiji14

.github/workflows/dvc-diff.yml

@@ -22,7 +22,7 @@ jobs:
       uses: iterative/[email protected]
 
     - name: Setup continuous machine learning (CML)
-      uses: iterative/[email protected].0
+      uses: iterative/[email protected].3
 
     - name: Pull image data from cloud storage
       run: dvc pull --remote upstream

.github/workflows/publish-to-pypi.yml

@@ -53,13 +53,13 @@ jobs:
         ls -lh dist/
 
     - name: Publish to Test PyPI
-      uses: pypa/gh-action-pypi-publish@v1.4.2
+      uses: pypa/gh-action-pypi-publish@v1.5.0
       with:
         password: ${{ secrets.TEST_PYPI_API_TOKEN }}
         repository_url: https://test.pypi.org/legacy/
 
     - name: Publish to PyPI
       if: startsWith(github.ref, 'refs/tags')
-      uses: pypa/gh-action-pypi-publish@v1.4.2
+      uses: pypa/gh-action-pypi-publish@v1.5.0
       with:
         password: ${{ secrets.PYPI_API_TOKEN }}

examples/gallery/lines/great_circles.py

@@ -0,0 +1,43 @@
+"""
+Generate points along great circles
+-----------------------------------
+
+The :meth:`pygmt.project` method can generate points along a great circle
+whose center and end points can be defined via the ``center`` and ``endpoint``
+parameters, respectively. Using the ``generate`` parameter allows to generate
+(*r*, *s*, *p*) points every *dist* units of *p* along a profile as
+output. By default all units (*r*, *s* and *p*) are set to degrees while
+``unit=True`` allows to set the unit for *p* to km.
+"""
+
+import pygmt
+
+fig = pygmt.Figure()
+
+# generate points every 10 degrees along a great circle from 10N,50W to 30N,5W
+points1 = pygmt.project(center=[-50, 10], endpoint=[-5, 30], generate=10)
+# generate points every 750 km along a great circle from 10N,50W to 57.5N,90W
+points2 = pygmt.project(center=[-50, 10], endpoint=[-90, 57.5], generate=750, unit=True)
+# generate points every 350 km along a great circle from 10N,50W to 68N,5W
+points3 = pygmt.project(center=[-50, 10], endpoint=[-5, 68], generate=350, unit=True)
+
+# create a plot with coast and Mercator projection (M)
+fig.basemap(region=[-100, 0, 0, 70], projection="M12c", frame=True)
+fig.coast(shorelines=True, area_thresh=5000)
+
+# plot individual points of first great circle as seagreen line
+fig.plot(x=points1.r, y=points1.s, pen="2p,seagreen")
+# plot individual points as seagreen squares atop
+fig.plot(x=points1.r, y=points1.s, style="s.45c", color="seagreen", pen="1p")
+
+# plot individual points of second great circle as orange line
+fig.plot(x=points2.r, y=points2.s, pen="2p,orange")
+# plot individual points as orange inverted triangles atop
+fig.plot(x=points2.r, y=points2.s, style="i.6c", color="orange", pen="1p")
+
+# plot individual points of third great circle as red line
+fig.plot(x=points3.r, y=points3.s, pen="2p,red3")
+# plot individual points as red circles atop
+fig.plot(x=points3.r, y=points3.s, style="c.3c", color="red3", pen="1p")
+
+fig.show()

pygmt/figure.py

@@ -3,6 +3,7 @@
 """
 import base64
 import os
+import warnings
 from tempfile import TemporaryDirectory
 
 try:
@@ -129,13 +130,14 @@ def region(self):
         C="gs_option",
         E="dpi",
         F="prefix",
-        I="icc_gray",
+        I="resize",
+        N="bb_style",
         T="fmt",
         Q="anti_aliasing",
         V="verbose",
     )
     @kwargs_to_strings()
-    def psconvert(self, **kwargs):
+    def psconvert(self, icc_gray=False, **kwargs):
         r"""
         Convert [E]PS file(s) to other formats.
 
@@ -153,9 +155,14 @@ def psconvert(self, **kwargs):
         Parameters
         ----------
         crop : str or bool
-            Adjust the BoundingBox and HiResBoundingBox to the minimum required
-            by the image content. Append ``u`` to first remove any GMT-produced
-            time-stamps. Default is True.
+            Adjust the BoundingBox and HiResBoundingBox to the minimum
+            required by the image content. Default is True. Append **+u** to
+            first remove any GMT-produced time-stamps. Append **+r** to
+            *round* the HighResBoundingBox instead of using the ``ceil``
+            function. This is going against Adobe Law but can be useful when
+            creating very small images where the difference of one pixel
+            might matter. If ``verbose`` is used we also report the
+            dimensions of the final illustration.
         gs_option : str
             Specify a single, custom option that will be passed on to
             GhostScript as is.
@@ -167,8 +174,33 @@ def psconvert(self, **kwargs):
             using the input names as base, which are appended with an
             appropriate extension. Use this option to provide a different name,
             but without extension. Extension is still determined automatically.
-        icc_gray : bool
-            Enforce gray-shades by using ICC profiles.
+        resize : str
+            [**+m**\ *margins*][**+s**\ [**m**]\ *width*\
+            [/\ *height*]][**+S**\ *scale*] ].
+            Adjust the BoundingBox and HiResBoundingBox by scaling and/or
+            adding margins. Append **+m** to specify extra margins to extend
+            the bounding box. Give either one (uniform), two (x and y) or four
+            (individual sides) margins; append unit [Default is set by
+            :term:`PROJ_LENGTH_UNIT`]. Append **+s**\ *width* to resize the
+            output image to exactly *width* units. The default unit is set
+            by :term:`PROJ_LENGTH_UNIT` but you can append a new unit and/or
+            impose different width and height (**Note**: This may change the
+            image aspect ratio). What happens here is that Ghostscript will do
+            the re-interpolation work and the final image will retain the DPI
+            resolution set by ``dpi``.  Append **+sm** to set a maximum size
+            and the new *width* is only imposed if the original figure width
+            exceeds it. Append /\ *height* to also impose a maximum height in
+            addition to the width. Alternatively, append **+S**\ *scale* to
+            scale the image by a constant factor.
+        bb_style : str
+            Set optional BoundingBox fill color, fading, or draw the outline
+            of the BoundingBox. Append **+f**\ *fade* to fade the entire plot
+            towards black (100%) [no fading, 0]. Append **+g** \*paint* to
+            paint the BoundingBox behind the illustration and append **+p**\
+            [*pen*] to draw the BoundingBox outline (append a pen or accept
+            the default pen of 0.25p,black). Note: If both **+g** and **+f**
+            are used then we use paint as the fade color instead of black.
+            Append **+i** to enforce gray-shades by using ICC profiles.
         anti_aliasing : str
             [**g**\|\ **p**\|\ **t**\][**1**\|\ **2**\|\ **4**].
             Set the anti-aliasing options for **g**\ raphics or **t**\ ext.
@@ -192,6 +224,18 @@ def psconvert(self, **kwargs):
         # Default cropping the figure to True
         if "A" not in kwargs:
             kwargs["A"] = ""
+
+        if icc_gray:
+            msg = (
+                "The 'icc_gray' parameter has been deprecated since v0.6.0"
+                " and will be removed in v0.8.0."
+            )
+            warnings.warn(msg, category=FutureWarning, stacklevel=2)
+            if "N" not in kwargs:
+                kwargs["N"] = "+i"
+            else:
+                kwargs["N"] += "+i"
+
         # Manually handle prefix -F argument so spaces aren't converted to \040
         # by build_arg_string function. For more information, see
         # https://github.com/GenericMappingTools/pygmt/pull/1487

pygmt/tests/test_figure.py

@@ -252,3 +252,14 @@ def test_figure_set_display_invalid():
     """
     with pytest.raises(GMTInvalidInput):
         set_display(method="invalid")
+
+
+def test_figure_icc_gray():
+    """
+    Check if icc_gray parameter works correctly if used.
+    """
+    fig = Figure()
+    fig.basemap(region=[0, 1, 0, 1], projection="X1c/1c", frame=True)
+    with pytest.warns(expected_warning=FutureWarning) as record:
+        fig.psconvert(icc_gray=True, prefix="Test")
+        assert len(record) == 1  # check that only one warning was raised