diff --git a/bob/io/image/utils.py b/bob/io/image/utils.py index 3f0986ddf1048935a92ee957eb96cc5550eb60de..16ccb62a660808c3b09685de599e2a17afa8152c 100644 --- a/bob/io/image/utils.py +++ b/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) diff --git a/doc/guide.rst b/doc/guide.rst index 28319834c0135210ec4d51d578369de6ad7d6d30..189eb51bcc9955a88fb76f4bf91dbc2a96a3d10f 100644 --- a/doc/guide.rst +++ b/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:: * diff --git a/version.txt b/version.txt index 5198d63a7871fdebdc79c2710cfa3c4e883cead5..3d7fc74812ca4a496cf52a75607c5a2c7063f1c2 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -2.4.7b0 \ No newline at end of file +2.5.0b0