Figure.plot3d: Add the "symbol" parameter to support plotting data po…

…ints with varying symbols (#3559)

pygmt/src/plot3d.py

@@ -50,7 +50,15 @@
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
 def plot3d(
-    self, data=None, x=None, y=None, z=None, size=None, direction=None, **kwargs
+    self,
+    data=None,
+    x=None,
+    y=None,
+    z=None,
+    size=None,
+    symbol=None,
+    direction=None,
+    **kwargs,
 ):
     r"""
     Plot lines, polygons, and symbols in 3-D.
@@ -89,6 +97,8 @@ def plot3d(
     size : 1-D array
         The size of the data points in units specified in ``style``.
         Only valid if using ``x``/``y``/``z``.
+    symbol : 1-D array
+        The symbols of the data points. Only valid if using ``x``/``y``.
     direction : list of two 1-D arrays
         If plotting vectors (using ``style="V"`` or ``style="v"``), then
         should be a list of two 1-D arrays with the vector directions. These
@@ -204,13 +214,19 @@ def plot3d(
             if is_nonstr_iter(kwargs.get(flag)):
                 extra_arrays.append(kwargs.get(flag))
                 kwargs[flag] = ""
+        # Symbol must be at the last column
+        if is_nonstr_iter(symbol):
+            if "S" not in kwargs:
+                kwargs["S"] = True
+            extra_arrays.append(symbol)
     else:
         for name, value in [
             ("direction", direction),
             ("fill", kwargs.get("G")),
             ("size", size),
             ("intensity", kwargs.get("I")),
             ("transparency", kwargs.get("t")),
+            ("symbol", symbol),
         ]:
             if is_nonstr_iter(value):
                 raise GMTInvalidInput(f"'{name}' can't be 1-D array if 'data' is used.")

pygmt/tests/baseline/test_plot3d_symbol.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 5593426a0fde7cc591e89b8309f73402
+  size: 9170
+  hash: md5
+  path: test_plot3d_symbol.png

pygmt/tests/test_plot3d.py

@@ -315,6 +315,28 @@ def test_plot3d_sizes_colors_transparencies():
     return fig
 
 
+@pytest.mark.mpl_image_compare
+def test_plot3d_symbol():
+    """
+    Plot the data using array-like symbols.
+    """
+    fig = Figure()
+    fig.plot3d(
+        x=[1, 2, 3, 4],
+        y=[1, 2, 3, 4],
+        z=[1, 2, 3, 4],
+        region=[0, 5, 0, 5, 0, 5],
+        projection="X4c",
+        zsize="3c",
+        fill="blue",
+        size=[0.1, 0.2, 0.3, 0.4],
+        symbol=["c", "t", "i", "u"],
+        frame=["WSenZ", "afg"],
+        perspective=[135, 30],
+    )
+    return fig
+
+
 @pytest.mark.mpl_image_compare
 @pytest.mark.mpl_image_compare(filename="test_plot3d_matrix.png")
 @pytest.mark.parametrize("fill", ["#aaaaaa", 170])