.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.dos.anjos@gmail.com>
.. Fri 16 May 11:48:13 2014 CEST

.. testsetup:: *

   import numpy
   import bob.io.base
   import bob.io.image
   import tempfile
   import os

   current_directory = os.path.realpath(os.curdir)
   temp_dir = tempfile.mkdtemp(prefix='bob_doctest_')
   os.chdir(temp_dir)

============
 User Guide
============

By importing this package, you can use |project| native array reading and
writing routines to load and save files using various image formats, using the simple plug-in technology for :py:mod:`bob.io.base`, i.e., :py:func:`bob.io.base.load` and :py:func:`bob.io.base.save`.

.. code-block:: python

   >> import bob.io.base
   >> import bob.io.image #under the hood: loads Bob plugin for image files
   >> x = bob.io.base.load('myfile.jpg')

In the following example, an image generated randomly using the method `NumPy`
:py:func:`numpy.random.random_integers`, is saved in lossless PNG format. The image
must be of type ``uint8`` or ``uint16``:

.. doctest::

  >>> my_image = numpy.random.random_integers(0,255,(3,256,256))
  >>> bob.io.base.save(my_image.astype('uint8'), 'testimage.png') # saving the image in png format
  >>> my_image_copy = bob.io.base.load('testimage.png')
  >>> assert (my_image_copy == my_image).all()

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
  os.chdir(current_directory)
  shutil.rmtree(temp_dir)