Figure.psconvert: Add new aliases and deprecate parameter "icc_gray" (remove in v0.8.0) (#1673)

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>
Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Author: 3 people

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,17 @@ 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"
         # allow for spaces in figure name
         kwargs["F"] = f'"{kwargs.get("F")}"' if kwargs.get("F") else None
         with Session() as lib:

pygmt/tests/test_figure.py

@@ -251,3 +251,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