From e2440b58422fc10c4b0fd06671028938320ef8e8 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Tue, 29 Oct 2024 09:55:12 +0800
Subject: [PATCH] Figure.plot3d: Add the "symbol" parameter to support plotting
 data points with varying symbols

---
 pygmt/src/plot3d.py                           | 18 ++++++++++++++-
 .../tests/baseline/test_plot3d_symbol.png.dvc |  5 +++++
 pygmt/tests/test_plot3d.py                    | 22 +++++++++++++++++++
 3 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 pygmt/tests/baseline/test_plot3d_symbol.png.dvc

diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py
index 31695a82464..60dac2d5d37 100644
--- a/pygmt/src/plot3d.py
+++ b/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,6 +214,11 @@ 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),
@@ -211,6 +226,7 @@ def plot3d(
             ("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.")
diff --git a/pygmt/tests/baseline/test_plot3d_symbol.png.dvc b/pygmt/tests/baseline/test_plot3d_symbol.png.dvc
new file mode 100644
index 00000000000..c980b998eea
--- /dev/null
+++ b/pygmt/tests/baseline/test_plot3d_symbol.png.dvc
@@ -0,0 +1,5 @@
+outs:
+- md5: 5593426a0fde7cc591e89b8309f73402
+  size: 9170
+  hash: md5
+  path: test_plot3d_symbol.png
diff --git a/pygmt/tests/test_plot3d.py b/pygmt/tests/test_plot3d.py
index 60453b3fe63..f3a616d75e6 100644
--- a/pygmt/tests/test_plot3d.py
+++ b/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])