Allow conversion of batched images and videos to matplotlib and back

bob/io/image/utils.py

@@ -2,55 +2,110 @@ import numpy as np
 
 
 def to_matplotlib(img):
-    '''Returns a view of the image compatible with matplotlib.
+    """Returns a view of the image from Bob format to matplotlib format.
+    This function works with images, batches of images, videos, and higher
+    dimensional arrays that contain images.
 
     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)``.
+        A N dimensional array containing an image in Bob format (channels
+        first): For an ND array (N >= 3), the image should have the following
+        format: ``(..., c, h, w)``.
 
     Returns
     -------
     numpy.ndarray
         A view of the ``img`` compatible with
         :py:func:`matplotlib.pyplot.imshow`.
-    '''
-    if img.ndim == 3:
-        img = np.moveaxis(img, 0, -1)
-    return img
+    """
+    if img.ndim < 3:
+        return img
+    return np.moveaxis(img, -3, -1)
 
 
 def to_bob(img):
-    '''Returns a view of the image compatible with Bob.
+    """Returns a view of the image from matplotlib format to Bob format.
+    This function works with images, batches of images, videos, and higher
+    dimensional arrays that contain images.
 
     Parameters
     ----------
     img : numpy.ndarray
-        A 2 or 3 dimensional array containing an image in matplotlib style: For
-        a 2D array (grayscale image) should be ``(y, x)``; For a 3D array
-        (color image) should be ``(y, x, n)``.
+        An image in matplotlib format (channels last): For an ND array (N >= 3),
+        the image should have the following format: ``(..., h, w, c)``.
 
     Returns
     -------
     numpy.ndarray
-        A view of the ``img`` compatible with Bob ``(n, y, x)`` for 3D images.
-    '''
-    if img.ndim == 3:
-        img = np.moveaxis(img, -1, 0)
-    return img
+        A view of the ``img`` compatible with Bob.
+    """
+    if img.ndim < 3:
+        return img
+    return np.moveaxis(img, -1, -3)
+
+
+def opencvbgr_to_bob(img):
+    """Returns a view of the image from OpenCV BGR format to Bob RGB format.
+    This function works with images, batches of images, videos, and higher
+    dimensional arrays that contain images.
+
+    Parameters
+    ----------
+    img : numpy.ndarray
+        An image loaded by OpenCV. It needs to have at least 3 dimensions.
+
+    Returns
+    -------
+    numpy.ndarray
+        A view of the ``img`` compatible with Bob.
+
+    Raises
+    ------
+    ValueError
+        If the image dimension is less than 3.
+    """
+    if img.ndim < 3:
+        raise ValueError("You need to provide at least a 3 dimensional image")
+    img = img[..., ::-1]
+    return to_bob(img)
+
+
+def bob_to_opencvbgr(img):
+    """Returns a view of the image from Bob format to OpenCV BGR format.
+    This function works with images, batches of images, videos, and higher
+    dimensional arrays that contain images.
+
+    Parameters
+    ----------
+    img : numpy.ndarray
+        An image loaded by Bob. It needs to have at least 3 dimensions.
+
+    Returns
+    -------
+    numpy.ndarray
+        A view of the ``img`` compatible with OpenCV.
+
+    Raises
+    ------
+    ValueError
+        If the image dimension is less than 3.
+    """
+    if img.ndim < 3:
+        raise ValueError("You need to provide at least a 3 dimensional image")
+    img = img[..., ::-1, :, :]
+    return to_matplotlib(img)
 
 
 def imshow(img, cmap=None, **kwargs):
-    '''Plots the images that are returned by :py:func:`bob.io.base.load`
+    """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)``;
-        A 3D array (color image) should be in the ``(n, y, x)`` format.
+        bob style: For a 2D array (grayscale image) should be ``(h, w)``;
+        A 3D array (color image) should be in the ``(c, h, w)`` format.
     cmap : matplotlib.colors.Colormap
         Colormap, optional, default: ``None``.
         If ``cmap`` is ``None`` and ``img.ndim`` is 2, defaults to 'gray'.
@@ -62,10 +117,10 @@ def imshow(img, cmap=None, **kwargs):
     -------
     object
         Returns whatever ``plt.imshow`` returns.
-    '''
+    """
     import matplotlib.pyplot as plt
 
     if cmap is None and img.ndim == 2:
-        cmap = 'gray'
+        cmap = "gray"
 
     return plt.imshow(to_matplotlib(img), cmap=cmap, **kwargs)

doc/guide.rst

@@ -83,6 +83,10 @@ Or you can just get a view (not copy) of your image that is
   >>> assert img_view_for_matplotlib.base is img
 
 You can also get the original image back using :py:func:`bob.io.image.to_bob`.
+This function works with images, batches of images, videos, and higher
+dimensional arrays that contain images.
+Moreover, see :any:`bob.io.image.opencvbgr_to_bob` and
+:any:`bob.io.image.bob_to_opencvbgr`.
 
 
 .. testcleanup:: *

version.txt

-2.4.7b0
\ No newline at end of file
+2.5.0b0