diff --git a/pygmt/figure.py b/pygmt/figure.py index 6a2c53fd844..83f3b2a59eb 100644 --- a/pygmt/figure.py +++ b/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: diff --git a/pygmt/tests/test_figure.py b/pygmt/tests/test_figure.py index fc1c5b3afb1..05dcb467c0e 100644 --- a/pygmt/tests/test_figure.py +++ b/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