Let Figure.text() support record-by-record transparency (#716)

Each text strings can have its own transparencies.

pygmt/base_plotting.py

@@ -1481,6 +1481,10 @@ def text(
  {p}
  {t}
  """
+
+ # pylint: disable=too-many-locals
+ # pylint: disable=too-many-branches
+
  kwargs = self._preprocess(**kwargs)
 
  # Ensure inputs are either textfiles, x/y/text, or position/text
@@ -1515,14 +1519,24 @@ def text(
  if position is not None and isinstance(position, str):
  kwargs["F"] += f'+c{position}+t"{text}"'
 
+ extra_arrays = []
+ # If an array of transparency is given, GMT will read it from
+ # the last numerical column per data record.
+ if "t" in kwargs and is_nonstr_iter(kwargs["t"]):
+ extra_arrays.append(kwargs["t"])
+ kwargs["t"] = ""
+
  with Session() as lib:
  file_context = dummy_context(textfiles) if kind == "file" else ""
  if kind == "vectors":
  if position is not None:
  file_context = dummy_context("")
  else:
  file_context = lib.virtualfile_from_vectors(
- np.atleast_1d(x), np.atleast_1d(y), np.atleast_1d(text)
+ np.atleast_1d(x),
+ np.atleast_1d(y),
+ *extra_arrays,
+ np.atleast_1d(text),
  )
  with file_context as fname:
  arg_str = " ".join([fname, build_arg_string(kwargs)])

pygmt/tests/test_text.py

@@ -5,10 +5,12 @@
 import os
 
 import pytest
+import numpy as np
 
 from .. import Figure
 from ..exceptions import GMTCLibError, GMTInvalidInput
 from ..helpers import GMTTempFile
+from ..helpers.testing import check_figures_equal
 
 TEST_DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
 POINTS_DATA = os.path.join(TEST_DATA_DIR, "points.txt")
@@ -295,3 +297,44 @@ def test_text_angle_font_justify_from_textfile():
  justify=True,
  )
  return fig
+
+
+@check_figures_equal()
+def test_text_transparency():
+ "Add texts with a constant transparency"
+ x = np.arange(1, 10)
+ y = np.arange(11, 20)
+ text = [f"TEXT-{i}-{j}" for i, j in zip(x, y)]
+
+ fig_ref, fig_test = Figure(), Figure()
+ # Use single-character arguments for the reference image
+ with GMTTempFile() as tmpfile:
+ np.savetxt(tmpfile.name, np.c_[x, y, text], fmt="%s")
+ fig_ref.basemap(R="0/10/10/20", J="X10c", B="")
+ fig_ref.text(textfiles=tmpfile.name, t=50)
+
+ fig_test.basemap(region=[0, 10, 10, 20], projection="X10c", frame=True)
+ fig_test.text(x=x, y=y, text=text, transparency=50)
+
+ return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_text_varying_transparency():
+ "Add texts with varying transparency"
+ x = np.arange(1, 10)
+ y = np.arange(11, 20)
+ text = [f"TEXT-{i}-{j}" for i, j in zip(x, y)]
+ transparency = np.arange(10, 100, 10)
+
+ fig_ref, fig_test = Figure(), Figure()
+ # Use single-character arguments for the reference image
+ with GMTTempFile() as tmpfile:
+ np.savetxt(tmpfile.name, np.c_[x, y, transparency, text], fmt="%s")
+ fig_ref.basemap(R="0/10/10/20", J="X10c", B="")
+ fig_ref.text(textfiles=tmpfile.name, t="")
+
+ fig_test.basemap(region=[0, 10, 10, 20], projection="X10c", frame=True)
+ fig_test.text(x=x, y=y, text=text, transparency=transparency)
+
+ return fig_ref, fig_test