From 2d7e7ab373d13028452037c33102800ba52d9f3b Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Tue, 21 Jan 2020 16:13:03 -0500
Subject: [PATCH] legend items example

---
 doc/python/3d-volume.md       |  6 ++---
 doc/python/cone-plot.md       |  4 ++--
 doc/python/legend.md          | 44 +++++++++++++++++++++++++++++++++++
 doc/python/streamtube-plot.md | 10 ++++----
 4 files changed, 54 insertions(+), 10 deletions(-)

diff --git a/doc/python/3d-volume.md b/doc/python/3d-volume.md
index 54a5dd24c01..21094aab6ed 100644
--- a/doc/python/3d-volume.md
+++ b/doc/python/3d-volume.md
@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.2.3
+      format_version: '1.2'
+      jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
     language: python
@@ -43,7 +43,7 @@ In the three examples below, note that the default colormap is different whether
 import plotly.graph_objects as go
 import numpy as np
 X, Y, Z = np.mgrid[-8:8:40j, -8:8:40j, -8:8:40j]
-values =    np.sin(X*Y*Z) / (X*Y*Z)
+values = np.sin(X*Y*Z) / (X*Y*Z)
 
 fig = go.Figure(data=go.Volume(
     x=X.flatten(),
diff --git a/doc/python/cone-plot.md b/doc/python/cone-plot.md
index 77111044113..0ffcb4aad71 100644
--- a/doc/python/cone-plot.md
+++ b/doc/python/cone-plot.md
@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.2.3
+      format_version: '1.2'
+      jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
     language: python
diff --git a/doc/python/legend.md b/doc/python/legend.md
index ed2508981ab..4860e5dc79a 100644
--- a/doc/python/legend.md
+++ b/doc/python/legend.md
@@ -360,5 +360,49 @@ fig.add_trace(go.Scatter(
 fig.show()
 ```
 
+### Legend items for continuous fields (2D and 3D)
+
+Traces corresponding to 2D fields (e.g. `go.Heatmap`, `go.Histogram2d`) or 3D fields (e.g. `go.Isosurface`, `go.Volume`, `go.Cone`) can also appear in the legend. They come with legend icons corresponding to each trace type, which are colored using the same colorscale as the trace.
+
+The example below explores a vector field using several traces. Note that you can click on legend items to hide or to select (with a double click) a specific trace. This will make the exploration of your data easier! 
+
+```python
+import numpy as np
+import plotly.graph_objects as go
+
+# Define vector and scalar fields
+x, y, z = np.mgrid[0:1:8j, 0:1:8j, 0:1:8j]
+u =    np.sin(np.pi*x) * np.cos(np.pi*z)
+v = -2*np.sin(np.pi*y) * np.cos(2*np.pi*z)
+w = np.cos(np.pi*x)*np.sin(np.pi*z) + np.cos(np.pi*y)*np.sin(2*np.pi*z)
+magnitude = np.sqrt(u**2 + v**2 + w**2)
+mask1 = np.logical_and(y>=.4, y<=.6)
+mask2 = y>.6
+
+fig = go.Figure(go.Isosurface(
+                      x=x.ravel(), y=y.ravel(), z=z.ravel(),
+                      value=magnitude.ravel(),
+                      isomin=1.9, isomax=1.9, 
+                      colorscale="BuGn",
+                      name='isosurface'))
+
+
+fig.add_trace(go.Cone(x=x[mask1], y=y[mask1], z=z[mask1], 
+                      u=u[mask1], v=v[mask1], w=w[mask1],
+                      colorscale="Blues",
+                      name='cones'
+))
+fig.add_trace(go.Streamtube(
+                      x=x[mask2], y=y[mask2], z=z[mask2], 
+                      u=u[mask2], v=v[mask2], w=w[mask2],
+                      colorscale="Reds",
+                      name='streamtubes'
+))
+# Update all traces together
+fig.update_traces(showlegend=True, showscale=False)
+fig.update_layout(width=600, title_text='Exporation of a vector field using several traces')
+fig.show()
+```
+
 #### Reference
 See https://plot.ly/python/reference/#layout-legend for more information!
diff --git a/doc/python/streamtube-plot.md b/doc/python/streamtube-plot.md
index ce633e2c5e5..e4a0903b93b 100644
--- a/doc/python/streamtube-plot.md
+++ b/doc/python/streamtube-plot.md
@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.2.3
+      format_version: '1.2'
+      jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
     language: python
@@ -110,9 +110,9 @@ from plotly.subplots import make_subplots
 import numpy as np
 
 x, y, z = np.mgrid[0:10, 0:10, 0:10]
-x = x.T.flatten()
-y = y.T.flatten()
-z = z.T.flatten()
+x = x.flatten()
+y = y.flatten()
+z = z.flatten()
 
 u = np.zeros_like(x)
 v = np.zeros_like(y)