add scatter3d docs and fix colorbar title

examples/reference/elements/plotly/Scatter3D.ipynb

@@ -20,6 +20,7 @@
    "outputs": [],
    "source": [
     "import numpy as np\n",
+    "import pandas as pd\n",
     "import holoviews as hv\n",
     "from holoviews import dim, opts\n",
     "\n",
@@ -30,7 +31,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "``Scatter3D`` represents three-dimensional coordinates which may be colormapped or scaled in size according to a value. They are therefore very similar to [``Points``](Points.ipynb) and [``Scatter``](Scatter.ipynb) types but have one additional coordinate dimension. Like other 3D elements the camera angle can be controlled using ``azimuth``, ``elevation`` and ``distance`` plot options:"
+    "``Scatter3D`` plots represents three-dimensional coordinates which are specified as key dimensions (`kdims`, default `kdims` are x, y, z). The points can be given a `marker`, `color` and `size`. Additionally a `colorbar` can be added.\n",
+    "\n",
+    "``Scatter3D`` plots are therefore very similar to [``Points``](Points.ipynb) and [``Scatter``](Scatter.ipynb) types, but have one additional coordinate dimension.\n",
+    "\n",
+    "Like other 3D elements the camera angle can be controlled using `azimuth`, `elevation` and `distance` plot options"
    ]
   },
   {
@@ -40,9 +45,27 @@
    "outputs": [],
    "source": [
     "y,x = np.mgrid[-5:5, -5:5] * 0.1\n",
-    "heights = np.sin(x**2+y**2)\n",
-    "hv.Scatter3D((x.flat, y.flat, heights.flat)).opts(\n",
-    "    cmap='fire', color='z', size=5)"
+    "z=np.sin(x**2+y**2)\n",
+    "\n",
+    "hv.Scatter3D((x.flat,y.flat,z.flat)).opts(cmap='fire', color='z', size=5, colorbar=True, height=600, width=600)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can also provide your data in a container and specify the `kdims` to use."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data = pd.DataFrame(dict(lat=x.flat, lon=y.flat, height=z.flat))\n",
+    "\n",
+    "hv.Scatter3D(data, kdims=[\"lat\", \"lon\", \"height\"]).opts(cmap='blues', color='height', size=3, colorbar=True, height=600, width=600, colorbar_opts={'title': 'height (m)'}, marker=\"diamond\")"
    ]
   },
   {
@@ -59,7 +82,7 @@
    "outputs": [],
    "source": [
     "(hv.Scatter3D(np.random.randn(100,4), vdims='Size') * hv.Scatter3D(np.random.randn(100,4)+2, vdims='Size')).opts(\n",
-    "    opts.Scatter3D(size=(5+dim('Size'))*2, marker='diamond')\n",
+    "    opts.Scatter3D(size=(5+dim('Size'))*2, marker='diamond', height=600, width=600)\n",
     ")"
    ]
   },
@@ -69,14 +92,45 @@
    "source": [
     "For full documentation and the available style and plot options, use ``hv.help(hv.Scatter3D).``"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(hv.Scatter3D.__doc__)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hv.help(hv.Scatter3D)"
+   ]
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "Python [conda env:holoviews_dev]",
+   "language": "python",
+   "name": "conda-env-holoviews_dev-py"
+  },
   "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
    "name": "python",
-   "pygments_lexer": "ipython3"
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.13"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 1
+ "nbformat_minor": 4
 }

holoviews/element/chart3d.py

@@ -70,8 +70,50 @@ class Scatter3D(Element3D, Points):
     """
     Scatter3D is a 3D element representing the position of a collection
     of coordinates in a 3D space. The key dimensions represent the
-    position of each coordinate along the x-, y- and z-axis while the
-    value dimensions can optionally supply additional information.
+    position of each coordinate along the x-, y- and z-axis.
+
+    Scatter3D is not available for the default Bokeh backend.
+
+    Example - Matplotlib
+    --------------------
+
+    .. code-block::
+
+        import holoviews as hv
+        from bokeh.sampledata.iris import flowers
+
+        hv.extension("matplotlib")
+
+        hv.Scatter3D(
+            flowers, kdims=["sepal_length", "sepal_width", "petal_length"]
+        ).opts(
+            color="petal_width",
+            alpha=0.7,
+            size=5,
+            cmap="fire",
+            marker='^'
+        )
+
+    Example - Plotly
+    ----------------
+
+    .. code-block::
+
+        import holoviews as hv
+        from bokeh.sampledata.iris import flowers
+
+        hv.extension("plotly")
+
+        hv.Scatter3D(
+            flowers, kdims=["sepal_length", "sepal_width", "petal_length"]
+        ).opts(
+            color="petal_width",
+            alpha=0.7,
+            size=5,
+            cmap="Portland",
+            colorbar=True,
+            marker="circle",
+        )
     """
 
     kdims = param.List(default=[Dimension('x'),

holoviews/plotting/plotly/element.py

@@ -603,11 +603,19 @@ def get_color_opts(self, eldim, element, ranges, style):
         opts = {}
         dim_name = dim_range_key(eldim)
         if self.colorbar:
-            if isinstance(eldim, dim):
-                title = str(eldim) if eldim.ops else str(eldim)[1:-1]
-            else:
-                title = eldim.pprint_label
-            opts['colorbar'] = dict(title=title, **self.colorbar_opts)
+            opts['colorbar'] = dict(**self.colorbar_opts)
+            if not "title" in opts['colorbar']:
+                if isinstance(eldim, dim):
+                    title = str(eldim)
+                    if eldim.ops:
+                        title = title
+                    elif title.startswith("dim('") and title.endswith("')"):
+                        title = title[5:-2]
+                    else:
+                        title = title[1:-1]
+                else:
+                    title = eldim.pprint_label
+                opts['colorbar']['title']=title
             opts['showscale'] = True
         else:
             opts['showscale'] = False

holoviews/tests/plotting/plotly/test_elementplot.py

@@ -223,3 +223,26 @@ def test_overlay_plot_zlabel(self):
         scatter = Path3D([]) * Scatter3D([(10, 1, 2), (100, 2, 3), (1000, 3, 5)]).opts(zlabel='Z-Axis')
         state = self._get_plot_state(scatter)
         self.assertEqual(state['layout']['scene']['zaxis']['title']['text'], 'Z-Axis')
+
+class TestColorbarPlot(TestPlotlyPlot):
+    def test_base(self):
+        y,x = np.mgrid[-5:5, -5:5] * 0.1
+        z=np.sin(x**2+y**2)
+        scatter = Scatter3D((x.flat,y.flat,z.flat))
+        state = self._get_plot_state(scatter)
+        assert state['layout']['scene']['zaxis']['title']=="z"
+
+    def test_colorbar(self):
+        y,x = np.mgrid[-5:5, -5:5] * 0.1
+        z=np.sin(x**2+y**2)
+        scatter = Scatter3D((x.flat,y.flat,z.flat)).opts(colorbar=True)
+        state = self._get_plot_state(scatter)
+        assert state['layout']['scene']['zaxis']['title']=="z"
+
+    def test_colorbar_opts_title(self):
+        y,x = np.mgrid[-5:5, -5:5] * 0.1
+        z=np.sin(x**2+y**2)
+        scatter = Scatter3D((x.flat,y.flat,z.flat)).opts(colorbar=True, colorbar_opts={"title": "some-title"})
+        plot = plotly_renderer.get_plot(scatter)
+        state = self._get_plot_state(scatter)
+        assert state['layout']['scene']['zaxis']['title']=="some-title"