docs on facets and animations + add subplots titles

Author: emmanuelle

doc/python/imshow.md

@@ -399,5 +399,57 @@ for compression_level in range(0, 9):
 fig.show()
 ```
 
+### Exploring 3-D images and timeseries with `facet_col`
+
+*Introduced in plotly 4.11*
+
+For three-dimensional image datasets, obtained for example by MRI or CT in medical imaging, one can explore the dataset by representing its different planes as facets. The `facet_col` argument specifies along which axes the image is sliced through to make the facets. With `facet_col_wrap` , one can set the maximum number of columns.
+
+It is recommended to use `binary_string=True` for facetted plots of images in order to keep a small figure size and a short rendering time.
+
+See the [tutorial on facet plots](/python/facet-plots/) for more information on creating and styling facet plots.
+
+```python
+import plotly.express as px
+from skimage import io
+from skimage.data import image_fetcher
+path = image_fetcher.fetch('data/cells.tif')
+data = io.imread(path)
+img = data[25:40]
+fig = px.imshow(img, facet_col=0, binary_string=True, facet_col_wrap=5, height=700)
+fig.show()
+```
+
+```python
+import plotly.express as px
+from skimage import io
+from skimage.data import image_fetcher
+path = image_fetcher.fetch('data/cells.tif')
+data = io.imread(path)
+img = data[25:40]
+fig = px.imshow(img, facet_col=0, binary_string=True, facet_col_wrap=5)
+# To have square facets one needs to unmatch axes
+fig.update_xaxes(matches=None)
+fig.update_yaxes(matches=None)
+fig.show()
+```
+
+### Exploring 3-D images and timeseries with `animation_frame`
+
+*Introduced in plotly 4.11*
+
+For three-dimensional image datasets, obtained for example by MRI or CT in medical imaging, one can explore the dataset by sliding through its different planes in an animation. The `animation_frame` argument of `px.imshow` sets the axis along which the 3-D image is sliced in the animation.
+
+```python
+import plotly.express as px
+from skimage import io
+from skimage.data import image_fetcher
+path = image_fetcher.fetch('data/cells.tif')
+data = io.imread(path)
+img = data[25:40]
+fig = px.imshow(img, animation_frame=0, binary_string=True)
+fig.show()
+```
+
 #### Reference
 See https://plotly.com/python/reference/#image for more information and chart attribute options!

packages/python/plotly/plotly/express/_imshow.py

@@ -288,14 +288,17 @@ def imshow(
     args = locals()
     apply_default_cascade(args)
     labels = labels.copy()
+    col_labels = []
     if facet_col is not None:
         nslices = img.shape[facet_col]
-        ncols = int(facet_col_wrap)
+        ncols = int(facet_col_wrap) if facet_col_wrap is not None else nslices
         nrows = nslices // ncols + 1 if nslices % ncols else nslices // ncols
+        col_labels = ["plane = %d" % i for i in range(nslices)]
     else:
         nrows = 1
         ncols = 1
-    fig = init_figure(args, "xy", [], nrows, ncols, [], [])
+    slice_through = (facet_col is not None) or (animation_frame is not None)
+    fig = init_figure(args, "xy", [], nrows, ncols, col_labels, [])
     # ----- Define x and y, set labels if img is an xarray -------------------
     if xarray_imported and isinstance(img, xarray.DataArray):
         if binary_string:
@@ -353,16 +356,13 @@ def imshow(
 
     # --------------- Starting from here img is always a numpy array --------
     img = np.asanyarray(img)
-    slice_through = False
     if facet_col is not None:
         img = np.moveaxis(img, facet_col, 0)
         facet_col = True
-        slice_through = True
     if animation_frame is not None:
         img = np.moveaxis(img, animation_frame, 0)
         animation_frame = True
         args["animation_frame"] = "plane"
-        slice_through = True
 
     # Default behaviour of binary_string: True for RGB images, False for 2D
     if binary_string is None: