From 4e4dbbcfcb6c589b18ba05349fe24f3d8170fc5b Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 17 Sep 2020 18:42:48 -0400 Subject: [PATCH] Add common alias transparency (-t) to all plotting functions (#614) -t for transparency. See https://docs.generic-mapping-tools.org/latest/gmt.html#t-full Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> --- pygmt/base_plotting.py | 67 ++++++++++++++++++++++++++++++++++--- pygmt/helpers/decorators.py | 7 ++++ 2 files changed, 69 insertions(+), 5 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index a3f682bebf9..950e1b089de 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -68,6 +68,7 @@ def _preprocess(self, **kwargs): # pylint: disable=no-self-use G="land", S="water", U="timestamp", + t="transparency", ) @kwargs_to_strings(R="sequence") def coast(self, **kwargs): @@ -128,6 +129,7 @@ def coast(self, **kwargs): shorelines : str ``'[level/]pen'`` Draw shorelines [Default is no shorelines]. Append pen attributes. + {t} """ kwargs = self._preprocess(**kwargs) @@ -144,6 +146,7 @@ def coast(self, **kwargs): F="box", G="truncate", W="scale", + t="transparency", ) @kwargs_to_strings(R="sequence", G="sequence") def colorbar(self, **kwargs): @@ -205,6 +208,7 @@ def colorbar(self, **kwargs): scale : float Multiply all z-values in the CPT by the provided scale. By default the CPT is used as is. + {t} """ kwargs = self._preprocess(**kwargs) @@ -225,6 +229,7 @@ def colorbar(self, **kwargs): U="timestamp", W="pen", l="label", + t="transparency", ) @kwargs_to_strings(R="sequence", L="sequence", A="sequence_plus") def grdcontour(self, grid, **kwargs): @@ -281,6 +286,7 @@ def grdcontour(self, grid, **kwargs): to be of the format [*annotcontlabel*][/*contlabel*]. If either label contains a slash (/) character then use ``|`` as the separator for the two labels instead. + {t} """ kwargs = self._preprocess(**kwargs) kind = data_kind(grid, None, None) @@ -296,7 +302,15 @@ def grdcontour(self, grid, **kwargs): lib.call_module("grdcontour", arg_str) @fmt_docstring - @use_alias(R="region", J="projection", W="pen", B="frame", I="shading", C="cmap") + @use_alias( + R="region", + J="projection", + W="pen", + B="frame", + I="shading", + C="cmap", + t="transparency", + ) @kwargs_to_strings(R="sequence") def grdimage(self, grid, **kwargs): """ @@ -312,6 +326,7 @@ def grdimage(self, grid, **kwargs): ---------- grid : str or xarray.DataArray The file name of the input grid or the grid loaded as a DataArray. + {t} """ kwargs = self._preprocess(**kwargs) @@ -343,6 +358,7 @@ def grdimage(self, grid, **kwargs): Wf="facadepen", p="perspective", I="shading", + t="transparency", ) @kwargs_to_strings(R="sequence", p="sequence") def grdview(self, grid, **kwargs): @@ -419,6 +435,8 @@ def grdview(self, grid, **kwargs): intensity, and ambient arguments for that module, or just give ``+d`` to select the default arguments (``+a-45+nt1+m0``). + {t} + """ kwargs = self._preprocess(**kwargs) kind = data_kind(grid, None, None) @@ -458,6 +476,7 @@ def grdview(self, grid, **kwargs): l="label", C="cmap", U="timestamp", + t="transparency", ) @kwargs_to_strings(R="sequence", i="sequence_comma") def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): @@ -527,6 +546,8 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): {U} label : str Add a legend entry for the symbol or line being plotted. + + {t} """ kwargs = self._preprocess(**kwargs) @@ -576,6 +597,7 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): i="columns", l="label", C="levels", + t="transparency", ) @kwargs_to_strings(R="sequence", i="sequence_comma") def contour(self, x=None, y=None, z=None, data=None, **kwargs): @@ -633,6 +655,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs): to be of the format [*annotcontlabel*][/*contlabel*]. If either label contains a slash (/) character then use ``|`` as the separator for the two labels instead. + {t} """ kwargs = self._preprocess(**kwargs) @@ -663,6 +686,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs): Td="rose", Tm="compass", U="timestamp", + t="transparency", ) @kwargs_to_strings(R="sequence") def basemap(self, **kwargs): @@ -696,6 +720,7 @@ def basemap(self, **kwargs): Draws a map magnetic rose on the map at the location defined by the reference and anchor points {U} + {t} """ kwargs = self._preprocess(**kwargs) @@ -705,7 +730,14 @@ def basemap(self, **kwargs): lib.call_module("basemap", build_arg_string(kwargs)) @fmt_docstring - @use_alias(R="region", J="projection", U="timestamp", D="position", F="box") + @use_alias( + R="region", + J="projection", + U="timestamp", + D="position", + F="box", + t="transparency", + ) @kwargs_to_strings(R="sequence") def logo(self, **kwargs): """ @@ -731,6 +763,7 @@ def logo(self, **kwargs): Without further options, draws a rectangular border around the GMT logo. {U} + {t} """ kwargs = self._preprocess(**kwargs) @@ -740,7 +773,14 @@ def logo(self, **kwargs): lib.call_module("logo", build_arg_string(kwargs)) @fmt_docstring - @use_alias(R="region", J="projection", D="position", F="box", M="monochrome") + @use_alias( + R="region", + J="projection", + D="position", + F="box", + M="monochrome", + t="transparency", + ) @kwargs_to_strings(R="sequence") def image(self, imagefile, **kwargs): """ @@ -774,6 +814,7 @@ def image(self, imagefile, **kwargs): monochrome : bool Convert color image to monochrome grayshades using the (television) YIQ-transformation. + {t} """ kwargs = self._preprocess(**kwargs) with Session() as lib: @@ -781,7 +822,13 @@ def image(self, imagefile, **kwargs): lib.call_module("image", arg_str) @fmt_docstring - @use_alias(R="region", J="projection", D="position", F="box") + @use_alias( + R="region", + J="projection", + D="position", + F="box", + t="transparency", + ) @kwargs_to_strings(R="sequence") def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwargs): """ @@ -816,6 +863,7 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg rectangular border around the legend using **MAP_FRAME_PEN**. By default, uses '+gwhite+p1p' which draws a box around the legend using a 1 point black pen and adds a white background. + {t} """ kwargs = self._preprocess(**kwargs) @@ -844,6 +892,7 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg D="offset", G="fill", W="pen", + t="transparency", ) @kwargs_to_strings( R="sequence", @@ -949,6 +998,7 @@ def text( Sets the pen used to draw a rectangle around the text string (see *clearance*) [Default is width = default, color = black, style = solid]. + {t} """ kwargs = self._preprocess(**kwargs) @@ -998,7 +1048,13 @@ def text( lib.call_module("text", arg_str) @fmt_docstring - @use_alias(R="region", J="projection", B="frame", C="offset") + @use_alias( + R="region", + J="projection", + B="frame", + C="offset", + t="transparency", + ) @kwargs_to_strings(R="sequence") def meca( self, @@ -1094,6 +1150,7 @@ def meca( {J} {R} {B} + {t} """ # pylint warnings that need to be fixed diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 0a11c37277c..1618d12eea5 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -82,6 +82,13 @@ ``[g|p]`` Force output grid to be gridline (g) or pixel (p) node registered. Default is gridline (g).""", + "t": """\ + transparency : float + Set transparency level, in [0-100] percent range. + Default is 0, i.e., opaque. + Only visible when PDF or raster format output is selected. + Only the PNG format selection adds a transparency layer + in the image (for further processing). """, }