Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add common alias transparency (-t) to all plotting functions #614

Merged
merged 3 commits into from
Sep 17, 2020
Merged

Add common alias transparency (-t) to all plotting functions #614

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
37b7300
Add alias -t (transparency) for all plotting functions
seisman Sep 17, 2020
2b8d5a2
Reformat using the latest black
seisman Sep 17, 2020
5509e82
Update pygmt/helpers/decorators.py
seisman Sep 17, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 62 additions & 5 deletions pygmt/base_plotting.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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)
Expand All @@ -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):
Expand Down Expand Up @@ -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)
Expand All @@ -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):
Expand Down Expand Up @@ -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)
Expand All @@ -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):
"""
Expand All @@ -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)
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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)
Expand All @@ -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):
"""
Expand All @@ -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)
Expand All @@ -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):
"""
Expand Down Expand Up @@ -774,14 +814,21 @@ 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:
arg_str = " ".join([imagefile, build_arg_string(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):
"""
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -1094,6 +1150,7 @@ def meca(
{J}
{R}
{B}
{t}
"""

# pylint warnings that need to be fixed
Expand Down
7 changes: 7 additions & 0 deletions pygmt/helpers/decorators.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member Author

@seisman seisman Sep 17, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

transparency can also be an array for a few modules, e.g., plot, plot3d and text, so that symbols and texts can have varying transparency. It needs more work and should be addressed in separated PRs.

I will open a feature request after merging this PR.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, but could you add at least one unit test for transparency on a module that won't have array-like transparency inputs (e.g. image)?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It means adding another baseline image to the repository. 😄

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe just a gallery example then, if not too much work 😶 I suppose we could come up with a smart check_figures_equal test but happy to leave that to the next PR.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is an upcoming example in #607, but I'm not sure if the example does too many things (symbols, transparency and legends.).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah right, missed the transparency part on that example. I don't think we can have too many examples, if anything we have too little right now (a lot of catching up to do with matplotlib at https://matplotlib.org/gallery/index.html)!

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). """,
}


Expand Down