From cfac43610312e1e093c01310c44d8bcd77261afe Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Fri, 1 Nov 2019 09:16:42 -0400
Subject: [PATCH 01/11] new tutorial on displaying image data

---
 python/images.md |   7 +-
 python/imshow.md | 187 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 191 insertions(+), 3 deletions(-)
 create mode 100644 python/imshow.md

diff --git a/python/images.md b/python/images.md
index 961520b17..96b600d63 100644
--- a/python/images.md
+++ b/python/images.md
@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.1'
-      jupytext_version: 1.1.7
+      jupytext_version: 1.1.1
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.5
+    version: 3.7.3
   plotly:
     description: How to add images to charts as background images or logos.
     display_as: file_settings
@@ -32,12 +32,13 @@ jupyter:
     order: 31
     permalink: python/images/
     thumbnail: thumbnail/images.png
-    
     v4upgrade: true
 ---
 
 #### Add a Background Image
 
+In this page we explain how to add static, non-interactive images as background, logo or annotation images to a figure. For exploring image data in interactive charts, see the [tutorial on displaying image data](./imshow/).
+
 ```python
 import plotly.graph_objects as go
 
diff --git a/python/imshow.md b/python/imshow.md
new file mode 100644
index 000000000..7bc9297a6
--- /dev/null
+++ b/python/imshow.md
@@ -0,0 +1,187 @@
+---
+jupyter:
+  jupytext:
+    notebook_metadata_filter: all
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.1'
+      jupytext_version: 1.1.1
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+  language_info:
+    codemirror_mode:
+      name: ipython
+      version: 3
+    file_extension: .py
+    mimetype: text/x-python
+    name: python
+    nbconvert_exporter: python
+    pygments_lexer: ipython3
+    version: 3.7.3
+  plotly:
+    description: How to display image data in Python with Plotly.
+    display_as: scientific
+    has_thumbnail: true
+    ipynb: ~notebook_demo/34
+    language: python
+    layout: base
+    name: Imshow
+    order: 3
+    page_type: example_index
+    permalink: python/imshow/
+    redirect_from: python/imshow/
+    thumbnail: thumbnail/imshow.jpg
+    v4upgrade: true
+---
+
+### Displaying RBG image data with px.imshow
+
+`px.imshow` displays multichannel (RGB) or single-channel ("grayscale") image data.
+
+```python
+import plotly.express as px
+import numpy as np
+img_rgb = np.array([[[255, 0, 0], [0, 255, 0], [0, 0, 255]],
+                    [[0, 255, 0], [0, 0, 255], [255, 0, 0]]
+                   ], dtype=np.uint8)
+fig = px.imshow(img_rgb)
+fig.show()
+```
+
+### Read image arrays from image files
+
+In order to create a numerical array to be passed to `px.imshow`, you can use a third-party library like [PIL](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.open), [scikit-image](https://scikit-image.org/docs/dev/user_guide/getting_started.html) or [opencv](https://opencv-python-tutroals.readthedocs.io/en/latest/py_tutorials/py_gui/py_image_display/py_image_display.html). We show below how to open an image from a file with `skimage.io.imread`, and alternatively how to load a demo image from `skimage.data`.
+
+```python
+import plotly.express as px
+from skimage import io
+img = io.imread('https://upload.wikimedia.org/wikipedia/commons/thumb/0/00/Crab_Nebula.jpg/240px-Crab_Nebula.jpg')
+fig = px.imshow(img)
+fig.show()
+```
+
+```python
+import plotly.express as px
+from skimage import data
+img = data.astronaut()
+fig = px.imshow(img)
+fig.show()
+```
+
+### Display single-channel 2D image as grayscale
+
+For a 2D image, `px.imshows` uses a colorscale to map scalar data to colors. The default colorscale is `gray`, ie grayscale images. 
+
+```python
+import plotly.express as px
+import numpy as np
+img = np.arange(100).reshape((10, 10))
+fig = px.imshow(img)
+fig.show()
+```
+
+### Choose the colorscale to display a single-channel image
+
+For a 2D image, `px.imshows` uses a colorscale to map scalar data to colors. The default colorscale is `gray`, ie grayscale images.
+
+```python
+import plotly.express as px
+import numpy as np
+img = np.arange(100).reshape((10, 10))
+fig = px.imshow(img, colorscale='Viridis')
+fig.show()
+```
+
+### Display multichannel image data with go.Image
+
+It is also possible to use the `go.Image` trace from the low-level `graph_objects` API in order to display image data. Note that `go.Image` only accepts multichannel images. For single images, use [`go.Heatmap`](https://plot.ly/python/heatmaps/).
+
+Note that the `go.Image` trace is different from the `go.layout.Image` class, which can be used for [adding background images or logos to figures](./images/). 
+
+```python
+import plotly.graph_objects as go
+img_rgb = [[[255, 0, 0], [0, 255, 0], [0, 0, 255]],
+           [[0, 255, 0], [0, 0, 255], [255, 0, 0]]]
+fig = go.Figure(go.Image(z=img_rgb))
+fig.show()
+```
+
+### Defining the data range covered by the color range with zmin and zmax
+
+The data range and color range are mapped together using the parameters `zmin` and `zmax`, which correspond respectively to the data values mapped to black `[0, 0, 0]` and white `[255, 255, 255]`, or to the extreme colors of the colorscale in the case on single-channel data. 
+
+`px.imshow` and `go.Image` use slightly different default values for `zmin` and `zmax`. For `go.Image`, the default value is `zmin=[0, 0, 0]` and `zmax=[255, 255, 255]`, no matter the data type. On the other hand, `px.imshow` adapts the default `zmin` and `zmax` to the data type:
+- for integer data types, `zmin` and `zmax` correspond to the extreme values of the data type, for example 0 and 255 for `uint8`, 0 and 65535 for `uint16`, etc.
+- for float numbers, when the data range is more arbitrary, the minimum and maximum values of the image (across all channels) is used.
+
+These defaults can be overriden by setting the values of `zmin` and `zmax`. For `go.Image`, `zmin` and `zmax` need to be given for all channels, whereas it is also possible to pass a scalar value (used for all channels) go `px.imshow`.
+
+```python
+import plotly.express as px
+from skimage import data
+img = data.astronaut()
+# Increase contrast by clipping the data range between 50 and 200
+fig = px.imshow(img, zmin=50, zmax=200)
+# We customize the hovertemplate to show both the data and the color values
+# See https://plot.ly/python/v3/hover-text-and-formatting/#hovertemplate
+fig.update_traces(hovertemplate="x: %{x} <br> y: %{y} <br> z: %{z} <br> color: %{color}")
+fig.show()
+```
+
+```python
+import plotly.express as px
+from skimage import data
+img = data.astronaut()
+# Stretch the contrast of the red channel only, resulting in a more red image
+fig = px.imshow(img, zmin=[50, 0, 0], zmax=[200, 255, 255])
+fig.show()
+```
+
+### Ticks and margins around image data
+
+```python
+import plotly.express as px
+from skimage import data
+img = data.astronaut()
+fig = px.imshow(img, showticks=False)
+fig.update_layout(width=400, height=400, margin=dict(l=10, r=10, b=10, t=10))
+fig.show()
+```
+
+### Combining image charts and other traces
+
+```python
+import plotly.express as px
+import plotly.graph_objects as go
+from skimage import data
+img = data.camera()
+fig = px.imshow(img)
+fig.add_trace(go.Contour(z=img, showscale=False, 
+                         contours=dict(start=0, end=70, size=70, coloring='lines'),
+                         line_width=2))
+fig.add_trace(go.Scatter(x=[230], y=[100], marker=dict(color='red', size=16)))
+fig.show()
+```
+
+### Displaying an image and the histogram of color values
+
+```python
+from plotly.subplots import make_subplots
+from skimage import data
+img = data.chelsea()
+fig = make_subplots(1, 2)
+# We use go.Image because at the moment px functions are not compatible with subplots
+fig.add_trace(go.Image(z=img), 1, 1)
+for channel, color in enumerate(['red', 'green', 'blue']):
+    fig.add_trace(go.Histogram(x=img[..., channel].ravel(), opacity=0.5, 
+                               marker_color=color, name='%s channel' %color), 1, 2)
+fig.update_layout(height=400)
+fig.show()
+```
+
+#### Reference
+See https://plot.ly/python/reference/#image for more information and chart attribute options!
+

From 2056d13e74dd03b7960995c7fd1494081d3f8960 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Tue, 5 Nov 2019 09:33:52 -0500
Subject: [PATCH 02/11] minor changes

---
 python/images.md | 42 ++++++++++++++++++------------------------
 python/imshow.md | 11 +++++++----
 2 files changed, 25 insertions(+), 28 deletions(-)

diff --git a/python/images.md b/python/images.md
index 96b600d63..b12b19acf 100644
--- a/python/images.md
+++ b/python/images.md
@@ -37,7 +37,7 @@ jupyter:
 
 #### Add a Background Image
 
-In this page we explain how to add static, non-interactive images as background, logo or annotation images to a figure. For exploring image data in interactive charts, see the [tutorial on displaying image data](./imshow/).
+In this page we explain how to add static, non-interactive images as background, logo or annotation images to a figure. For exploring image data in interactive charts, see the [tutorial on displaying image data](/python/imshow).
 
 ```python
 import plotly.graph_objects as go
@@ -51,8 +51,7 @@ fig.add_trace(
 )
 
 # Add images
-fig.update_layout(
-    images=[
+fig.add_layout_image(
         go.layout.Image(
             source="https://images.plot.ly/language-icons/api-home/python-logo.png",
             xref="x",
@@ -64,7 +63,6 @@ fig.update_layout(
             sizing="stretch",
             opacity=0.5,
             layer="below")
-    ]
 )
 
 # Set templates
@@ -117,14 +115,14 @@ fig.add_trace(
 )
 
 # Add image
-fig.update_layout(
-    images=[dict(
+fig.add_layout_image(
+    dict(
         source="https://raw.githubusercontent.com/cldougl/plot_images/add_r_img/vox.png",
         xref="paper", yref="paper",
         x=1, y=1.05,
         sizex=0.2, sizey=0.2,
         xanchor="right", yanchor="bottom"
-    )],
+    )
 )
 
 # update layout properties
@@ -176,30 +174,26 @@ for (x, y), n in zip(simulated_absorptions, names):
     fig.add_trace(go.Scatter(x=x, y=y, name=n))
 
 # Add images
-fig.update_layout(
-    images=[go.layout.Image(
+fig.add_layout_image(
+    go.layout.Image(
         source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/benzene.png",
-        xref="paper",
-        yref="paper",
         x=0.75,
         y=0.65,
-        sizex=0.3,
-        sizey=0.3,
-        xanchor="right",
-        yanchor="bottom"
-    ), go.layout.Image(
+    ))
+fig.add_layout_image(go.layout.Image(
         source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/naphthalene.png",
-        xref="paper",
-        yref="paper",
         x=0.9,
         y=0.3,
+        )
+)
+fig.update_layout_images(dict(
+        xref="paper",
+        yref="paper",
         sizex=0.3,
         sizey=0.3,
         xanchor="right",
         yanchor="bottom"
-        )
-    ]
-)
+))
 
 # Add annotations
 fig.update_layout(
@@ -282,8 +276,8 @@ fig.update_yaxes(
 )
 
 # Add image
-fig.update_layout(
-    images=[go.layout.Image(
+fig.add_layout_image(
+    go.layout.Image(
         x=0,
         sizex=img_width * scale_factor,
         y=img_height * scale_factor,
@@ -293,7 +287,7 @@ fig.update_layout(
         opacity=1.0,
         layer="below",
         sizing="stretch",
-        source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg")]
+        source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg")
 )
 
 # Configure other layout
diff --git a/python/imshow.md b/python/imshow.md
index 7bc9297a6..7e1923b75 100644
--- a/python/imshow.md
+++ b/python/imshow.md
@@ -37,6 +37,10 @@ jupyter:
     v4upgrade: true
 ---
 
+This tutorial shows how to display and explore image data. If you would like
+instead a logo or static image, use `go.layout.Image` as explained
+[here](/python/images).
+
 ### Displaying RBG image data with px.imshow
 
 `px.imshow` displays multichannel (RGB) or single-channel ("grayscale") image data.
@@ -73,7 +77,7 @@ fig.show()
 
 ### Display single-channel 2D image as grayscale
 
-For a 2D image, `px.imshows` uses a colorscale to map scalar data to colors. The default colorscale is `gray`, ie grayscale images. 
+For a 2D image, `px.imshow` uses a colorscale to map scalar data to colors. The default colorscale is `gray`, ie grayscale images. 
 
 ```python
 import plotly.express as px
@@ -85,7 +89,6 @@ fig.show()
 
 ### Choose the colorscale to display a single-channel image
 
-For a 2D image, `px.imshows` uses a colorscale to map scalar data to colors. The default colorscale is `gray`, ie grayscale images.
 
 ```python
 import plotly.express as px
@@ -97,9 +100,9 @@ fig.show()
 
 ### Display multichannel image data with go.Image
 
-It is also possible to use the `go.Image` trace from the low-level `graph_objects` API in order to display image data. Note that `go.Image` only accepts multichannel images. For single images, use [`go.Heatmap`](https://plot.ly/python/heatmaps/).
+It is also possible to use the `go.Image` trace from the low-level `graph_objects` API in order to display image data. Note that `go.Image` only accepts multichannel images. For single images, use [`go.Heatmap`](/python/heatmaps).
 
-Note that the `go.Image` trace is different from the `go.layout.Image` class, which can be used for [adding background images or logos to figures](./images/). 
+Note that the `go.Image` trace is different from the `go.layout.Image` class, which can be used for [adding background images or logos to figures](/python/images). 
 
 ```python
 import plotly.graph_objects as go

From 10d64b940437e287513109b843ad6e39d0e37bed Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 6 Nov 2019 11:04:47 -0500
Subject: [PATCH 03/11] minor changes

---
 python/imshow.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/python/imshow.md b/python/imshow.md
index 7e1923b75..b8ad536e0 100644
--- a/python/imshow.md
+++ b/python/imshow.md
@@ -129,7 +129,7 @@ img = data.astronaut()
 # Increase contrast by clipping the data range between 50 and 200
 fig = px.imshow(img, zmin=50, zmax=200)
 # We customize the hovertemplate to show both the data and the color values
-# See https://plot.ly/python/v3/hover-text-and-formatting/#hovertemplate
+# See https://plot.ly/python/hover-text-and-formatting/#customize-tooltip-text-with-a-hovertemplate
 fig.update_traces(hovertemplate="x: %{x} <br> y: %{y} <br> z: %{z} <br> color: %{color}")
 fig.show()
 ```
@@ -176,7 +176,7 @@ from plotly.subplots import make_subplots
 from skimage import data
 img = data.chelsea()
 fig = make_subplots(1, 2)
-# We use go.Image because at the moment px functions are not compatible with subplots
+# We use go.Image because subplots require traces, whereas px functions return a figure
 fig.add_trace(go.Image(z=img), 1, 1)
 for channel, color in enumerate(['red', 'green', 'blue']):
     fig.add_trace(go.Histogram(x=img[..., channel].ravel(), opacity=0.5, 

From 4654c069c8aa6bd01a40f44447afb4f3ad912596 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 6 Nov 2019 11:13:32 -0500
Subject: [PATCH 04/11] updated how to disable ticks

---
 python/imshow.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/python/imshow.md b/python/imshow.md
index b8ad536e0..bac3b075c 100644
--- a/python/imshow.md
+++ b/python/imshow.md
@@ -149,8 +149,9 @@ fig.show()
 import plotly.express as px
 from skimage import data
 img = data.astronaut()
-fig = px.imshow(img, showticks=False)
+fig = px.imshow(img)
 fig.update_layout(width=400, height=400, margin=dict(l=10, r=10, b=10, t=10))
+fig.update_xaxes(showticklabels=False).update_yaxes(showticklabels=False)
 fig.show()
 ```
 

From f97dfc40bad7acf84b9f6a7a27dcd81efb709ecd Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Thu, 7 Nov 2019 09:26:12 -0500
Subject: [PATCH 05/11] zmax update

---
 python/imshow.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/python/imshow.md b/python/imshow.md
index bac3b075c..ff49b70a8 100644
--- a/python/imshow.md
+++ b/python/imshow.md
@@ -82,7 +82,7 @@ For a 2D image, `px.imshow` uses a colorscale to map scalar data to colors. The
 ```python
 import plotly.express as px
 import numpy as np
-img = np.arange(100).reshape((10, 10))
+img = np.arange(15**2).reshape((15, 15))
 fig = px.imshow(img)
 fig.show()
 ```
@@ -116,11 +116,11 @@ fig.show()
 
 The data range and color range are mapped together using the parameters `zmin` and `zmax`, which correspond respectively to the data values mapped to black `[0, 0, 0]` and white `[255, 255, 255]`, or to the extreme colors of the colorscale in the case on single-channel data. 
 
-`px.imshow` and `go.Image` use slightly different default values for `zmin` and `zmax`. For `go.Image`, the default value is `zmin=[0, 0, 0]` and `zmax=[255, 255, 255]`, no matter the data type. On the other hand, `px.imshow` adapts the default `zmin` and `zmax` to the data type:
+For single-channel data, the defaults values of `zmin` and `zmax` used by `px.imshow` and `go.Heatmap` are the the extrema of the data range. For multichannel data, `px.imshow` and `go.Image` use slightly different default values for `zmin` and `zmax`. For `go.Image`, the default value is `zmin=[0, 0, 0]` and `zmax=[255, 255, 255]`, no matter the data type. On the other hand, `px.imshow` adapts the default `zmin` and `zmax` to the data type:
 - for integer data types, `zmin` and `zmax` correspond to the extreme values of the data type, for example 0 and 255 for `uint8`, 0 and 65535 for `uint16`, etc.
-- for float numbers, when the data range is more arbitrary, the minimum and maximum values of the image (across all channels) is used.
+- for float numbers, the maximum value of the data is computed, and zmax is 1 if the max is smaller than 1, 255 if the max is smaller than 255, etc. (with higher thresholds 2**16 - 1 and 2**32 -1).
 
-These defaults can be overriden by setting the values of `zmin` and `zmax`. For `go.Image`, `zmin` and `zmax` need to be given for all channels, whereas it is also possible to pass a scalar value (used for all channels) go `px.imshow`.
+These defaults can be overriden by setting the values of `zmin` and `zmax`. For `go.Image`, `zmin` and `zmax` need to be given for all channels, whereas it is also possible to pass a scalar value (used for all channels) to `px.imshow`.
 
 ```python
 import plotly.express as px
@@ -189,3 +189,7 @@ fig.show()
 #### Reference
 See https://plot.ly/python/reference/#image for more information and chart attribute options!
 
+
+```python
+fig = px.imshow
+```

From 4f3bc892af2d78b94b3f4475e9b48977ee8b53b2 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Fri, 1 Nov 2019 09:16:42 -0400
Subject: [PATCH 06/11] new tutorial on displaying image data

---
 python/images.md |   6 +-
 python/imshow.md | 187 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 191 insertions(+), 2 deletions(-)
 create mode 100644 python/imshow.md

diff --git a/python/images.md b/python/images.md
index f31937110..e75fc2a73 100644
--- a/python/images.md
+++ b/python/images.md
@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.1'
-      jupytext_version: 1.1.7
+      jupytext_version: 1.1.1
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.5
+    version: 3.7.3
   plotly:
     description: How to add images to charts as background images or logos.
     display_as: file_settings
@@ -34,6 +34,8 @@ jupyter:
 
 #### Add a Background Image
 
+In this page we explain how to add static, non-interactive images as background, logo or annotation images to a figure. For exploring image data in interactive charts, see the [tutorial on displaying image data](./imshow/).
+
 ```python
 import plotly.graph_objects as go
 
diff --git a/python/imshow.md b/python/imshow.md
new file mode 100644
index 000000000..7bc9297a6
--- /dev/null
+++ b/python/imshow.md
@@ -0,0 +1,187 @@
+---
+jupyter:
+  jupytext:
+    notebook_metadata_filter: all
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.1'
+      jupytext_version: 1.1.1
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+  language_info:
+    codemirror_mode:
+      name: ipython
+      version: 3
+    file_extension: .py
+    mimetype: text/x-python
+    name: python
+    nbconvert_exporter: python
+    pygments_lexer: ipython3
+    version: 3.7.3
+  plotly:
+    description: How to display image data in Python with Plotly.
+    display_as: scientific
+    has_thumbnail: true
+    ipynb: ~notebook_demo/34
+    language: python
+    layout: base
+    name: Imshow
+    order: 3
+    page_type: example_index
+    permalink: python/imshow/
+    redirect_from: python/imshow/
+    thumbnail: thumbnail/imshow.jpg
+    v4upgrade: true
+---
+
+### Displaying RBG image data with px.imshow
+
+`px.imshow` displays multichannel (RGB) or single-channel ("grayscale") image data.
+
+```python
+import plotly.express as px
+import numpy as np
+img_rgb = np.array([[[255, 0, 0], [0, 255, 0], [0, 0, 255]],
+                    [[0, 255, 0], [0, 0, 255], [255, 0, 0]]
+                   ], dtype=np.uint8)
+fig = px.imshow(img_rgb)
+fig.show()
+```
+
+### Read image arrays from image files
+
+In order to create a numerical array to be passed to `px.imshow`, you can use a third-party library like [PIL](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.open), [scikit-image](https://scikit-image.org/docs/dev/user_guide/getting_started.html) or [opencv](https://opencv-python-tutroals.readthedocs.io/en/latest/py_tutorials/py_gui/py_image_display/py_image_display.html). We show below how to open an image from a file with `skimage.io.imread`, and alternatively how to load a demo image from `skimage.data`.
+
+```python
+import plotly.express as px
+from skimage import io
+img = io.imread('https://upload.wikimedia.org/wikipedia/commons/thumb/0/00/Crab_Nebula.jpg/240px-Crab_Nebula.jpg')
+fig = px.imshow(img)
+fig.show()
+```
+
+```python
+import plotly.express as px
+from skimage import data
+img = data.astronaut()
+fig = px.imshow(img)
+fig.show()
+```
+
+### Display single-channel 2D image as grayscale
+
+For a 2D image, `px.imshows` uses a colorscale to map scalar data to colors. The default colorscale is `gray`, ie grayscale images. 
+
+```python
+import plotly.express as px
+import numpy as np
+img = np.arange(100).reshape((10, 10))
+fig = px.imshow(img)
+fig.show()
+```
+
+### Choose the colorscale to display a single-channel image
+
+For a 2D image, `px.imshows` uses a colorscale to map scalar data to colors. The default colorscale is `gray`, ie grayscale images.
+
+```python
+import plotly.express as px
+import numpy as np
+img = np.arange(100).reshape((10, 10))
+fig = px.imshow(img, colorscale='Viridis')
+fig.show()
+```
+
+### Display multichannel image data with go.Image
+
+It is also possible to use the `go.Image` trace from the low-level `graph_objects` API in order to display image data. Note that `go.Image` only accepts multichannel images. For single images, use [`go.Heatmap`](https://plot.ly/python/heatmaps/).
+
+Note that the `go.Image` trace is different from the `go.layout.Image` class, which can be used for [adding background images or logos to figures](./images/). 
+
+```python
+import plotly.graph_objects as go
+img_rgb = [[[255, 0, 0], [0, 255, 0], [0, 0, 255]],
+           [[0, 255, 0], [0, 0, 255], [255, 0, 0]]]
+fig = go.Figure(go.Image(z=img_rgb))
+fig.show()
+```
+
+### Defining the data range covered by the color range with zmin and zmax
+
+The data range and color range are mapped together using the parameters `zmin` and `zmax`, which correspond respectively to the data values mapped to black `[0, 0, 0]` and white `[255, 255, 255]`, or to the extreme colors of the colorscale in the case on single-channel data. 
+
+`px.imshow` and `go.Image` use slightly different default values for `zmin` and `zmax`. For `go.Image`, the default value is `zmin=[0, 0, 0]` and `zmax=[255, 255, 255]`, no matter the data type. On the other hand, `px.imshow` adapts the default `zmin` and `zmax` to the data type:
+- for integer data types, `zmin` and `zmax` correspond to the extreme values of the data type, for example 0 and 255 for `uint8`, 0 and 65535 for `uint16`, etc.
+- for float numbers, when the data range is more arbitrary, the minimum and maximum values of the image (across all channels) is used.
+
+These defaults can be overriden by setting the values of `zmin` and `zmax`. For `go.Image`, `zmin` and `zmax` need to be given for all channels, whereas it is also possible to pass a scalar value (used for all channels) go `px.imshow`.
+
+```python
+import plotly.express as px
+from skimage import data
+img = data.astronaut()
+# Increase contrast by clipping the data range between 50 and 200
+fig = px.imshow(img, zmin=50, zmax=200)
+# We customize the hovertemplate to show both the data and the color values
+# See https://plot.ly/python/v3/hover-text-and-formatting/#hovertemplate
+fig.update_traces(hovertemplate="x: %{x} <br> y: %{y} <br> z: %{z} <br> color: %{color}")
+fig.show()
+```
+
+```python
+import plotly.express as px
+from skimage import data
+img = data.astronaut()
+# Stretch the contrast of the red channel only, resulting in a more red image
+fig = px.imshow(img, zmin=[50, 0, 0], zmax=[200, 255, 255])
+fig.show()
+```
+
+### Ticks and margins around image data
+
+```python
+import plotly.express as px
+from skimage import data
+img = data.astronaut()
+fig = px.imshow(img, showticks=False)
+fig.update_layout(width=400, height=400, margin=dict(l=10, r=10, b=10, t=10))
+fig.show()
+```
+
+### Combining image charts and other traces
+
+```python
+import plotly.express as px
+import plotly.graph_objects as go
+from skimage import data
+img = data.camera()
+fig = px.imshow(img)
+fig.add_trace(go.Contour(z=img, showscale=False, 
+                         contours=dict(start=0, end=70, size=70, coloring='lines'),
+                         line_width=2))
+fig.add_trace(go.Scatter(x=[230], y=[100], marker=dict(color='red', size=16)))
+fig.show()
+```
+
+### Displaying an image and the histogram of color values
+
+```python
+from plotly.subplots import make_subplots
+from skimage import data
+img = data.chelsea()
+fig = make_subplots(1, 2)
+# We use go.Image because at the moment px functions are not compatible with subplots
+fig.add_trace(go.Image(z=img), 1, 1)
+for channel, color in enumerate(['red', 'green', 'blue']):
+    fig.add_trace(go.Histogram(x=img[..., channel].ravel(), opacity=0.5, 
+                               marker_color=color, name='%s channel' %color), 1, 2)
+fig.update_layout(height=400)
+fig.show()
+```
+
+#### Reference
+See https://plot.ly/python/reference/#image for more information and chart attribute options!
+

From 67c18302626f3fe2b9c2e59493d53153be6f26e8 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Tue, 5 Nov 2019 09:33:52 -0500
Subject: [PATCH 07/11] minor changes

---
 python/images.md | 42 ++++++++++++++++++------------------------
 python/imshow.md | 11 +++++++----
 2 files changed, 25 insertions(+), 28 deletions(-)

diff --git a/python/images.md b/python/images.md
index e75fc2a73..7c081bf69 100644
--- a/python/images.md
+++ b/python/images.md
@@ -34,7 +34,7 @@ jupyter:
 
 #### Add a Background Image
 
-In this page we explain how to add static, non-interactive images as background, logo or annotation images to a figure. For exploring image data in interactive charts, see the [tutorial on displaying image data](./imshow/).
+In this page we explain how to add static, non-interactive images as background, logo or annotation images to a figure. For exploring image data in interactive charts, see the [tutorial on displaying image data](/python/imshow).
 
 ```python
 import plotly.graph_objects as go
@@ -48,8 +48,7 @@ fig.add_trace(
 )
 
 # Add images
-fig.update_layout(
-    images=[
+fig.add_layout_image(
         go.layout.Image(
             source="https://images.plot.ly/language-icons/api-home/python-logo.png",
             xref="x",
@@ -61,7 +60,6 @@ fig.update_layout(
             sizing="stretch",
             opacity=0.5,
             layer="below")
-    ]
 )
 
 # Set templates
@@ -114,14 +112,14 @@ fig.add_trace(
 )
 
 # Add image
-fig.update_layout(
-    images=[dict(
+fig.add_layout_image(
+    dict(
         source="https://raw.githubusercontent.com/cldougl/plot_images/add_r_img/vox.png",
         xref="paper", yref="paper",
         x=1, y=1.05,
         sizex=0.2, sizey=0.2,
         xanchor="right", yanchor="bottom"
-    )],
+    )
 )
 
 # update layout properties
@@ -173,30 +171,26 @@ for (x, y), n in zip(simulated_absorptions, names):
     fig.add_trace(go.Scatter(x=x, y=y, name=n))
 
 # Add images
-fig.update_layout(
-    images=[go.layout.Image(
+fig.add_layout_image(
+    go.layout.Image(
         source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/benzene.png",
-        xref="paper",
-        yref="paper",
         x=0.75,
         y=0.65,
-        sizex=0.3,
-        sizey=0.3,
-        xanchor="right",
-        yanchor="bottom"
-    ), go.layout.Image(
+    ))
+fig.add_layout_image(go.layout.Image(
         source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/naphthalene.png",
-        xref="paper",
-        yref="paper",
         x=0.9,
         y=0.3,
+        )
+)
+fig.update_layout_images(dict(
+        xref="paper",
+        yref="paper",
         sizex=0.3,
         sizey=0.3,
         xanchor="right",
         yanchor="bottom"
-        )
-    ]
-)
+))
 
 # Add annotations
 fig.update_layout(
@@ -279,8 +273,8 @@ fig.update_yaxes(
 )
 
 # Add image
-fig.update_layout(
-    images=[go.layout.Image(
+fig.add_layout_image(
+    go.layout.Image(
         x=0,
         sizex=img_width * scale_factor,
         y=img_height * scale_factor,
@@ -290,7 +284,7 @@ fig.update_layout(
         opacity=1.0,
         layer="below",
         sizing="stretch",
-        source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg")]
+        source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg")
 )
 
 # Configure other layout
diff --git a/python/imshow.md b/python/imshow.md
index 7bc9297a6..7e1923b75 100644
--- a/python/imshow.md
+++ b/python/imshow.md
@@ -37,6 +37,10 @@ jupyter:
     v4upgrade: true
 ---
 
+This tutorial shows how to display and explore image data. If you would like
+instead a logo or static image, use `go.layout.Image` as explained
+[here](/python/images).
+
 ### Displaying RBG image data with px.imshow
 
 `px.imshow` displays multichannel (RGB) or single-channel ("grayscale") image data.
@@ -73,7 +77,7 @@ fig.show()
 
 ### Display single-channel 2D image as grayscale
 
-For a 2D image, `px.imshows` uses a colorscale to map scalar data to colors. The default colorscale is `gray`, ie grayscale images. 
+For a 2D image, `px.imshow` uses a colorscale to map scalar data to colors. The default colorscale is `gray`, ie grayscale images. 
 
 ```python
 import plotly.express as px
@@ -85,7 +89,6 @@ fig.show()
 
 ### Choose the colorscale to display a single-channel image
 
-For a 2D image, `px.imshows` uses a colorscale to map scalar data to colors. The default colorscale is `gray`, ie grayscale images.
 
 ```python
 import plotly.express as px
@@ -97,9 +100,9 @@ fig.show()
 
 ### Display multichannel image data with go.Image
 
-It is also possible to use the `go.Image` trace from the low-level `graph_objects` API in order to display image data. Note that `go.Image` only accepts multichannel images. For single images, use [`go.Heatmap`](https://plot.ly/python/heatmaps/).
+It is also possible to use the `go.Image` trace from the low-level `graph_objects` API in order to display image data. Note that `go.Image` only accepts multichannel images. For single images, use [`go.Heatmap`](/python/heatmaps).
 
-Note that the `go.Image` trace is different from the `go.layout.Image` class, which can be used for [adding background images or logos to figures](./images/). 
+Note that the `go.Image` trace is different from the `go.layout.Image` class, which can be used for [adding background images or logos to figures](/python/images). 
 
 ```python
 import plotly.graph_objects as go

From cc59b3cca2127a3f21ccda5bb81b9ebb56bc12a8 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 6 Nov 2019 11:04:47 -0500
Subject: [PATCH 08/11] minor changes

---
 python/imshow.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/python/imshow.md b/python/imshow.md
index 7e1923b75..b8ad536e0 100644
--- a/python/imshow.md
+++ b/python/imshow.md
@@ -129,7 +129,7 @@ img = data.astronaut()
 # Increase contrast by clipping the data range between 50 and 200
 fig = px.imshow(img, zmin=50, zmax=200)
 # We customize the hovertemplate to show both the data and the color values
-# See https://plot.ly/python/v3/hover-text-and-formatting/#hovertemplate
+# See https://plot.ly/python/hover-text-and-formatting/#customize-tooltip-text-with-a-hovertemplate
 fig.update_traces(hovertemplate="x: %{x} <br> y: %{y} <br> z: %{z} <br> color: %{color}")
 fig.show()
 ```
@@ -176,7 +176,7 @@ from plotly.subplots import make_subplots
 from skimage import data
 img = data.chelsea()
 fig = make_subplots(1, 2)
-# We use go.Image because at the moment px functions are not compatible with subplots
+# We use go.Image because subplots require traces, whereas px functions return a figure
 fig.add_trace(go.Image(z=img), 1, 1)
 for channel, color in enumerate(['red', 'green', 'blue']):
     fig.add_trace(go.Histogram(x=img[..., channel].ravel(), opacity=0.5, 

From 9d01e297c9c89fc3444e9c8375f10de24c238155 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 6 Nov 2019 11:13:32 -0500
Subject: [PATCH 09/11] updated how to disable ticks

---
 python/imshow.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/python/imshow.md b/python/imshow.md
index b8ad536e0..bac3b075c 100644
--- a/python/imshow.md
+++ b/python/imshow.md
@@ -149,8 +149,9 @@ fig.show()
 import plotly.express as px
 from skimage import data
 img = data.astronaut()
-fig = px.imshow(img, showticks=False)
+fig = px.imshow(img)
 fig.update_layout(width=400, height=400, margin=dict(l=10, r=10, b=10, t=10))
+fig.update_xaxes(showticklabels=False).update_yaxes(showticklabels=False)
 fig.show()
 ```
 

From 4e937414b2f51fa7b4f3ffa8614fd54197fb222d Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Thu, 7 Nov 2019 09:26:12 -0500
Subject: [PATCH 10/11] zmax update

---
 python/imshow.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/python/imshow.md b/python/imshow.md
index bac3b075c..ff49b70a8 100644
--- a/python/imshow.md
+++ b/python/imshow.md
@@ -82,7 +82,7 @@ For a 2D image, `px.imshow` uses a colorscale to map scalar data to colors. The
 ```python
 import plotly.express as px
 import numpy as np
-img = np.arange(100).reshape((10, 10))
+img = np.arange(15**2).reshape((15, 15))
 fig = px.imshow(img)
 fig.show()
 ```
@@ -116,11 +116,11 @@ fig.show()
 
 The data range and color range are mapped together using the parameters `zmin` and `zmax`, which correspond respectively to the data values mapped to black `[0, 0, 0]` and white `[255, 255, 255]`, or to the extreme colors of the colorscale in the case on single-channel data. 
 
-`px.imshow` and `go.Image` use slightly different default values for `zmin` and `zmax`. For `go.Image`, the default value is `zmin=[0, 0, 0]` and `zmax=[255, 255, 255]`, no matter the data type. On the other hand, `px.imshow` adapts the default `zmin` and `zmax` to the data type:
+For single-channel data, the defaults values of `zmin` and `zmax` used by `px.imshow` and `go.Heatmap` are the the extrema of the data range. For multichannel data, `px.imshow` and `go.Image` use slightly different default values for `zmin` and `zmax`. For `go.Image`, the default value is `zmin=[0, 0, 0]` and `zmax=[255, 255, 255]`, no matter the data type. On the other hand, `px.imshow` adapts the default `zmin` and `zmax` to the data type:
 - for integer data types, `zmin` and `zmax` correspond to the extreme values of the data type, for example 0 and 255 for `uint8`, 0 and 65535 for `uint16`, etc.
-- for float numbers, when the data range is more arbitrary, the minimum and maximum values of the image (across all channels) is used.
+- for float numbers, the maximum value of the data is computed, and zmax is 1 if the max is smaller than 1, 255 if the max is smaller than 255, etc. (with higher thresholds 2**16 - 1 and 2**32 -1).
 
-These defaults can be overriden by setting the values of `zmin` and `zmax`. For `go.Image`, `zmin` and `zmax` need to be given for all channels, whereas it is also possible to pass a scalar value (used for all channels) go `px.imshow`.
+These defaults can be overriden by setting the values of `zmin` and `zmax`. For `go.Image`, `zmin` and `zmax` need to be given for all channels, whereas it is also possible to pass a scalar value (used for all channels) to `px.imshow`.
 
 ```python
 import plotly.express as px
@@ -189,3 +189,7 @@ fig.show()
 #### Reference
 See https://plot.ly/python/reference/#image for more information and chart attribute options!
 
+
+```python
+fig = px.imshow
+```

From bd06f3b44a6b1676bc035702ad39083b597fa02b Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Mon, 11 Nov 2019 23:26:41 -0500
Subject: [PATCH 11/11] fix color_continuous_scale

---
 python/imshow.md | 12 ++++--------
 1 file changed, 4 insertions(+), 8 deletions(-)

diff --git a/python/imshow.md b/python/imshow.md
index ff49b70a8..56dbba5b6 100644
--- a/python/imshow.md
+++ b/python/imshow.md
@@ -77,7 +77,7 @@ fig.show()
 
 ### Display single-channel 2D image as grayscale
 
-For a 2D image, `px.imshow` uses a colorscale to map scalar data to colors. The default colorscale is `gray`, ie grayscale images. 
+For a 2D image, `px.imshow` uses a colorscale to map scalar data to colors. The default colorscale is the one of the active template (see [the tutorial on templates](/python/templates/)). 
 
 ```python
 import plotly.express as px
@@ -94,7 +94,7 @@ fig.show()
 import plotly.express as px
 import numpy as np
 img = np.arange(100).reshape((10, 10))
-fig = px.imshow(img, colorscale='Viridis')
+fig = px.imshow(img, color_continuous_scale='gray')
 fig.show()
 ```
 
@@ -116,7 +116,7 @@ fig.show()
 
 The data range and color range are mapped together using the parameters `zmin` and `zmax`, which correspond respectively to the data values mapped to black `[0, 0, 0]` and white `[255, 255, 255]`, or to the extreme colors of the colorscale in the case on single-channel data. 
 
-For single-channel data, the defaults values of `zmin` and `zmax` used by `px.imshow` and `go.Heatmap` are the the extrema of the data range. For multichannel data, `px.imshow` and `go.Image` use slightly different default values for `zmin` and `zmax`. For `go.Image`, the default value is `zmin=[0, 0, 0]` and `zmax=[255, 255, 255]`, no matter the data type. On the other hand, `px.imshow` adapts the default `zmin` and `zmax` to the data type:
+For single-channel data, the defaults values of `zmin` and `zmax` used by `px.imshow` and `go.Heatmap` are the extrema of the data range. For multichannel data, `px.imshow` and `go.Image` use slightly different default values for `zmin` and `zmax`. For `go.Image`, the default value is `zmin=[0, 0, 0]` and `zmax=[255, 255, 255]`, no matter the data type. On the other hand, `px.imshow` adapts the default `zmin` and `zmax` to the data type:
 - for integer data types, `zmin` and `zmax` correspond to the extreme values of the data type, for example 0 and 255 for `uint8`, 0 and 65535 for `uint16`, etc.
 - for float numbers, the maximum value of the data is computed, and zmax is 1 if the max is smaller than 1, 255 if the max is smaller than 255, etc. (with higher thresholds 2**16 - 1 and 2**32 -1).
 
@@ -162,7 +162,7 @@ import plotly.express as px
 import plotly.graph_objects as go
 from skimage import data
 img = data.camera()
-fig = px.imshow(img)
+fig = px.imshow(img, color_continuous_scale='gray')
 fig.add_trace(go.Contour(z=img, showscale=False, 
                          contours=dict(start=0, end=70, size=70, coloring='lines'),
                          line_width=2))
@@ -189,7 +189,3 @@ fig.show()
 #### Reference
 See https://plot.ly/python/reference/#image for more information and chart attribute options!
 
-
-```python
-fig = px.imshow
-```