Add an imshow method to easily plot images

bob/io/image/__init__.py

@@ -10,6 +10,7 @@ from . import version
 from .version import module as __version__
 
 from ._library import *
+from .utils import imshow, to_matplotlib
 
 import os
 
@@ -122,5 +123,26 @@ def get_macros():
   return macros
 
 
+# gets sphinx autodoc done right - don't remove it
+def __appropriate__(*args):
+  """Says object was actually declared here, an not on the import module.
+
+  Parameters:
+
+    *args: An iterable of objects to modify
+
+  Resolves `Sphinx referencing issues
+  <https://github.com/sphinx-doc/sphinx/issues/3048>`
+  """
+
+  for obj in args:
+    obj.__module__ = __name__
+
+
+__appropriate__(
+    imshow,
+    to_matplotlib,
+  )
+
 # gets sphinx autodoc done right - don't remove it
 __all__ = [_ for _ in dir() if not _.startswith('_')]

bob/io/image/utils.py

+#!/usr/bin/env python
+
+
+def to_matplotlib(img):
+    '''Returns a view of the image compatible with matplotlib.
+
+    Parameters:
+        img (numpy.ndarray): A 2 or 3 dimensional array containing an image in
+            bob style: For a 2D array (grayscale image) should be ``(y, x)``;
+            For a 3D array (color image) should be ``(n, y, x)``.
+
+    Returns:
+        numpy.ndarray: A view of the ``img`` compatible with
+            :py:func:`matplotlib.pyplot.imshow`.
+    '''
+    import numpy as np
+
+    if img.ndim == 3:
+        return np.moveaxis(img, 0, -1)
+    else:
+        return img
+
+
+def imshow(img, cmap=None, **kwargs):
+    '''Plots the images that are returned by :py:func:`bob.io.base.load`
+
+    Parameters:
+        img (numpy.ndarray): A 2 or 3 dimensional array containing an image in
+            bob style: For a 2D array (grayscale image) should be ``(y, x)``;
+            For a 3D array (color image) should be ``(n, y, x)``.
+        cmap (matplotlib.colors.Colormap): Colormap, optional, default: ``None``.
+            If ``cmap`` is ``None`` and ``img.ndim`` is 2, defaults to 'gray'.
+            ``cmap`` is ignored when ``img`` has RGB(A) information.
+        kwargs: These are passed directly to :py:func:`matplotlib.pyplot.imshow`
+    '''
+    import matplotlib.pyplot as plt
+
+    if cmap is None and img.ndim == 2:
+        cmap = 'gray'
+
+    plt.imshow(to_matplotlib(img), cmap=cmap, **kwargs)

doc/conf.py

@@ -25,6 +25,7 @@ extensions = [
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
+    'matplotlib.sphinxext.plot_directive'
     ]
 
 import sphinx
@@ -239,9 +240,12 @@ autodoc_default_flags = [
 from bob.extension.utils import link_documentation, load_requirements
 sphinx_requirements = "extra-intersphinx.txt"
 if os.path.exists(sphinx_requirements):
-    intersphinx_mapping = link_documentation(additional_packages=load_requirements(sphinx_requirements))
+  intersphinx_mapping = link_documentation(
+      additional_packages=['python','numpy'] + \
+          load_requirements(sphinx_requirements)
+          )
 else:
-    intersphinx_mapping = link_documentation()
+  intersphinx_mapping = link_documentation()
 
 
 # We want to remove all private (i.e. _. or __.__) members

doc/guide.rst

@@ -41,6 +41,33 @@ must be of type ``uint8`` or ``uint16``:
 The loaded image files can be 3D arrays (for RGB format) or 2D arrays (for
 greyscale) of type ``uint8`` or ``uint16``.
 
+In order to visualize the loaded image you can use :py:func:`bob.io.image.imshow`:
+
+.. doctest::
+
+  >>> from bob.io.base import test_utils
+  >>> path = test_utils.datafile('grace_hopper.png', 'bob.io.image')
+  >>> img = bob.io.base.load(path)
+  >>> bob.io.image.imshow(img)  # doctest: +SKIP
+
+.. plot::
+
+   import bob.io.base
+   import bob.io.image
+   from bob.io.base import test_utils
+
+   path = test_utils.datafile('grace_hopper.png', 'bob.io.image')
+   img = bob.io.base.load(path)
+   bob.io.image.imshow(img)
+
+Or you can just get a view (not copy) of your image that is :py:mod:`matplotlib.pyplot` compatible:
+
+.. doctest::
+
+  >>> img_view_for_matplotlib = bob.io.image.to_matplotlib(img)
+  >>> assert img_view_for_matplotlib.shape[-1] == 3
+  >>> assert img_view_for_matplotlib.base is img
+
 .. testcleanup:: *
 
   import shutil

requirements.txt

@@ -3,3 +3,4 @@ bob.extension
 bob.blitz
 bob.core
 bob.io.base
+matplotlib