Documentation patches

doc/c_cpp_api.rst

@@ -6,10 +6,10 @@
  C++ API
 =========
 
-The C++ API of ``xbob.io`` allows users to leverage from automatic converters
-for classes in :py:class:`xbob.io`.  To use the C API, clients should first,
-include the header file ``<xbob.io/api.h>`` on their compilation units and
-then, make sure to call once ``import_xbob_io()`` at their module
+The C++ API of ``xbob.io.base`` allows users to leverage from automatic converters
+for classes in :py:class:`xbob.io.base`.  To use the C API, clients should first,
+include the header file ``<xbob.io.base/api.h>`` on their compilation units and
+then, make sure to call once ``import_xbob_io_base()`` at their module
 instantiation, as explained at the `Python manual
 <http://docs.python.org/2/extending/extending.html#using-capsules>`_.
 
@@ -18,7 +18,7 @@ the import function:
 
 .. code-block:: c++
 
-   #include <xbob.io/api.h>
+   #include <xbob.io.base/api.h>
 
    PyMODINIT_FUNC initclient(void) {
 
@@ -26,21 +26,25 @@ the import function:
 
      if (!m) return;
 
-     // imports the NumPy C-API
-     import_array();
+     /* imports dependencies */
+     if (import_xbob_blitz() < 0) {
+       PyErr_Print();
+       PyErr_SetString(PyExc_ImportError, "cannot import extension");
+       return 0;
+     }
 
-     // imports blitz.array C-API
-     import_xbob_blitz();
-
-     // imports xbob.io C-API
-     import_xbob_io();
+     if (import_xbob_io_base() < 0) {
+       PyErr_Print();
+       PyErr_SetString(PyExc_ImportError, "cannot import extension");
+       return 0;
+     }
 
    }
 
 .. note::
 
   The include directory can be discovered using
-  :py:func:`xbob.io.get_include`.
+  :py:func:`xbob.io.base.get_include`.
 
 Generic Functions
 -----------------

doc/conf.py

@@ -58,12 +58,12 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'xbob.io'
+project = u'xbob.io.base'
 import time
 copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
 
 # Grab the setup entry
-distribution = pkg_resources.require('xbob.io')[0]
+distribution = pkg_resources.require('xbob.io.base')[0]
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -129,7 +129,7 @@ if sphinx.__version__ >= "1.0":
 #html_title = None
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = 'xbob_io'
+#html_short_title = 'xbob_io_base'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
@@ -187,7 +187,7 @@ html_favicon = 'img/favicon.ico'
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'xbob_io_doc'
+htmlhelp_basename = 'xbob_io_base_doc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -201,7 +201,7 @@ latex_font_size = '10pt'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'xbob_io.tex', u'Bob I/O Routines',
+  ('index', 'xbob_io_base.tex', u'Core Bob I/O Routines',
    u'Biometrics Group, Idiap Research Institute', 'manual'),
 ]
 
@@ -241,7 +241,7 @@ rst_epilog = """
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'xbob_io', u'Bob I/O Routines Documentation', [u'Idiap Research Institute'], 1)
+    ('index', 'xbob_io_base', u'Core Bob I/O Routines Documentation', [u'Idiap Research Institute'], 1)
 ]
 
 # Default processing flags for sphinx

doc/guide.rst

@@ -5,7 +5,7 @@
 .. testsetup:: iotest
 
    import numpy
-   import xbob.io
+   import xbob.io.base
 
 ============
  User Guide
@@ -25,7 +25,7 @@ and |project| loaded into the `Python`_ environment.
 .. testsetup:: *
 
    import numpy
-   import xbob.io
+   import xbob.io.base
    import tempfile
    import os
 
@@ -49,8 +49,8 @@ an `HDF5`_ file. These are supplied by the `HDF5`_ project.
 ``h5diff``
   Finds the differences between HDF5 files.
 
-I/O operations using the class `xbob.io.HDF5File`
--------------------------------------------------
+I/O operations using the class `xbob.io.base.HDF5File`
+------------------------------------------------------
 
 Writing operations
 ------------------
@@ -62,7 +62,7 @@ floats.
 
    >>> an_integer = 5
    >>> a_float = 3.1416
-   >>> f = xbob.io.HDF5File('testfile1.hdf5', 'w')
+   >>> f = xbob.io.base.HDF5File('testfile1.hdf5', 'w')
    >>> f.set('my_integer', an_integer)
    >>> f.set('my_float', a_float)
    >>> del f
@@ -113,7 +113,7 @@ in a different directory like this:
 
 .. doctest::
 
-  >>> f = xbob.io.HDF5File('testfile1.hdf5', 'a')
+  >>> f = xbob.io.base.HDF5File('testfile1.hdf5', 'a')
   >>> f.create_group('/test')
   >>> f.set('/test/my_float', numpy.float32(6.28))
   >>> del f
@@ -149,7 +149,7 @@ as it was defined.
 
   If you need to place lots of variables in a subfolder, it may be better to
   setup the prefix folder before starting the writing operations on the
-  :py:class:`xbob.io.HDF5File` object. You can do this using the method
+  :py:class:`xbob.io.base.HDF5File` object. You can do this using the method
   :py:meth:`HDF5File.cd`.  Look up its help for more information and usage
   instructions.
 
@@ -160,7 +160,7 @@ is an example:
 .. doctest::
 
   >>> A = numpy.array(range(4), 'int8').reshape(2,2)
-  >>> f = xbob.io.HDF5File('testfile1.hdf5', 'a')
+  >>> f = xbob.io.base.HDF5File('testfile1.hdf5', 'a')
   >>> f.set('my_array', A)
   >>> del f
 
@@ -180,22 +180,23 @@ The result of running ``h5dump`` on the file ``testfile3.hdf5`` should be:
   ...
 
 You don't need to limit yourself to single variables, you can also save lists
-of scalars and arrays using the function :py:meth:`xbob.io.HDF5.append` instead
-of :py:meth:`xbob.io.HDF5.set`.
+of scalars and arrays using the function :py:meth:`xbob.io.base.HDF5.append`
+instead of :py:meth:`xbob.io.base.HDF5.set`.
 
 Reading operations
 ------------------
 
 Reading data from a file that you just wrote to is just as easy. For this task
-you should use :py:meth:`xbob.io.HDF5File.read`. The read method will read all
-the contents of the variable pointed to by the given path. This is the normal
-way to read a variable you have written with :py:meth:`xbob.io.HDF5File.set`. If
-you decided to create a list of scalar or arrays, the way to read that up would
-be using :py:meth:`xbob.io.HDF5File.lread` instead. Here is an example:
+you should use :py:meth:`xbob.io.base.HDF5File.read`. The read method will read
+all the contents of the variable pointed to by the given path. This is the
+normal way to read a variable you have written with
+:py:meth:`xbob.io.base.HDF5File.set`. If you decided to create a list of scalar
+or arrays, the way to read that up would be using
+:py:meth:`xbob.io.base.HDF5File.lread` instead. Here is an example:
 
 .. doctest::
 
-  >>> f = xbob.io.HDF5File('testfile1.hdf5') #read only
+  >>> f = xbob.io.base.HDF5File('testfile1.hdf5') #read only
   >>> f.read('my_integer') #reads integer
   5
   >>> print(f.read('my_array')) # reads the array
@@ -204,13 +205,13 @@ be using :py:meth:`xbob.io.HDF5File.lread` instead. Here is an example:
   >>> del f
 
 Now let's look at an example where we have used
-:py:meth:`xbob.io.HDF5File.append` instead of :py:meth:`xbob.io.HDF5File.set`
-to write data to a file. That is normally the case when you write lists of
-variables to a dataset.
+:py:meth:`xbob.io.base.HDF5File.append` instead of
+:py:meth:`xbob.io.base.HDF5File.set` to write data to a file. That is normally
+the case when you write lists of variables to a dataset.
 
 .. doctest::
 
-  >>> f = xbob.io.HDF5File('testfile2.hdf5', 'w')
+  >>> f = xbob.io.base.HDF5File('testfile2.hdf5', 'w')
   >>> f.append('arrayset', numpy.array(range(10), 'float64'))
   >>> f.append('arrayset', 2*numpy.array(range(10), 'float64'))
   >>> f.append('arrayset', 3*numpy.array(range(10), 'float64'))
@@ -245,19 +246,21 @@ shot:
 
 .. doctest::
 
-  >>> f = xbob.io.HDF5File('testfile2.hdf5')
+  >>> f = xbob.io.base.HDF5File('testfile2.hdf5')
   >>> print(f.read('arrayset'))
   [[  0.   1.   2.   3.   4.   5.   6.   7.   8.   9.]
    [  0.   2.   4.   6.   8.  10.  12.  14.  16.  18.]
    [  0.   3.   6.   9.  12.  15.  18.  21.  24.  27.]]
 
-As you can see, the only difference between :py:meth:`xbob.io.HDF5File.read`
-and :py:meth:`xbob.io.HDF5File.lread` is on how |project| considers the
+As you can see, the only difference between
+:py:meth:`xbob.io.base.HDF5File.read` and
+:py:meth:`xbob.io.base.HDF5File.lread` is on how |project| considers the
 available data (as a single array with N dimensions or as a set of arrays with
 N-1 dimensions). In the first example, you would have also been able to read
-the variable `my_array` as an arrayset using :py:meth:`xbob.io.HDF5File.lread`
-instead of :py:meth:`xbob.io.HDF5File.read`. In this case, each position
-readout would return a 1D uint8 array instead of a 2D array.
+the variable `my_array` as an arrayset using
+:py:meth:`xbob.io.base.HDF5File.lread` instead of
+:py:meth:`xbob.io.base.HDF5File.read`. In this case, each position readout
+would return a 1D uint8 array instead of a 2D array.
 
 Array interfaces
 ----------------
@@ -268,25 +271,27 @@ other software frameworks, debug your data or just implement your own classes
 that can serialize and de-serialize from HDF5 file containers. In |project|,
 most of the time you will be working with :py:class:`numpy.ndarrays`\s. In
 special situations though, you may be asked to handle
-:py:class:`xbob.io.File`\s. :py:class:`xbob.io.File` objects create a
+:py:class:`xbob.io.base.File`\s. :py:class:`xbob.io.base.File` objects create a
 transparent connection between C++ (`Blitz++`_) / Python (`NumPy`_) arrays and
 file access.  You specify the filename from which you want to input data and
-the :py:class:`xbob.io.File` object decides what is the best codec to be used
-(from the extension) and how to read the data back into your array.
+the :py:class:`xbob.io.base.File` object decides what is the best codec to be
+used (from the extension) and how to read the data back into your array.
 
-To create an :py:class:`xbob.io.File` from a file path, just do the following:
+To create an :py:class:`xbob.io.base.File` from a file path, just do the
+following:
 
 .. doctest::
 
-  >>> a = xbob.io.File('testfile2.hdf5', 'r')
+  >>> a = xbob.io.base.File('testfile2.hdf5', 'r')
   >>> a.filename
   'testfile2.hdf5'
 
-:py:class:`xbob.io.File`\s simulate containers for :py:class:`numpy.ndarray`\s,
-transparently accessing the file data when requested. Note, however, that when
-you instantiate an :py:class:`xbob.io.File` it does **not** load the file
-contents into memory. It waits until you emit another explicit instruction to
-do so. We do this with the :py:meth:`xbob.io.File.read` method:
+:py:class:`xbob.io.base.File`\s simulate containers for
+:py:class:`numpy.ndarray`\s, transparently accessing the file data when
+requested. Note, however, that when you instantiate an
+:py:class:`xbob.io.base.File` it does **not** load the file contents into
+memory. It waits until you emit another explicit instruction to do so. We do
+this with the :py:meth:`xbob.io.base.File.read` method:
 
 .. doctest::
 
@@ -296,44 +301,44 @@ do so. We do this with the :py:meth:`xbob.io.File.read` method:
          [  0.,   2.,   4.,   6.,   8.,  10.,  12.,  14.,  16.,  18.],
          [  0.,   3.,   6.,   9.,  12.,  15.,  18.,  21.,  24.,  27.]])
 
-Every time you say :py:meth:`xbob.io.File.read`, the file contents will be read
-from the file and into a new array.
+Every time you say :py:meth:`xbob.io.base.File.read`, the file contents will be
+read from the file and into a new array.
 
-Saving arrays to the :py:class:`xbob.io.File` is as easy, just call the
-:py:meth:`xbob.io.File.write` method:
+Saving arrays to the :py:class:`xbob.io.base.File` is as easy, just call the
+:py:meth:`xbob.io.base.File.write` method:
 
 .. doctest::
 
-  >>> f = xbob.io.File('copy1.hdf5', 'w')
+  >>> f = xbob.io.base.File('copy1.hdf5', 'w')
   >>> f.write(array)
 
 Numpy ndarray shortcuts
 -----------------------
 
 To just load an :py:class:`numpy.ndarray` in memory, you can use a short cut
-that lives at :py:func:`xbob.io.load`. With it, you don't have to go through
-the :py:class:`xbob.io.File` container:
+that lives at :py:func:`xbob.io.base.load`. With it, you don't have to go
+through the :py:class:`xbob.io.base.File` container:
 
 .. doctest::
 
-  >>> t = xbob.io.load('testfile2.hdf5')
+  >>> t = xbob.io.base.load('testfile2.hdf5')
   >>> t
   array([[  0.,   1.,   2.,   3.,   4.,   5.,   6.,   7.,   8.,   9.],
          [  0.,   2.,   4.,   6.,   8.,  10.,  12.,  14.,  16.,  18.],
          [  0.,   3.,   6.,   9.,  12.,  15.,  18.,  21.,  24.,  27.]])
 
-You can also directly save :py:class:`numpy.ndarray`\s without going
-through the :py:class:`xbob.io.Array` container:
+You can also directly save :py:class:`numpy.ndarray`\s without going through
+the :py:class:`xbob.io.base.Array` container:
 
 .. doctest::
 
-  >>> xbob.io.save(t, 'copy2.hdf5')
+  >>> xbob.io.base.save(t, 'copy2.hdf5')
 
 .. note::
 
-  Under the hood, we still use the :py:class:`xbob.io.File` API to execute
+  Under the hood, we still use the :py:class:`xbob.io.base.File` API to execute
   the read and write operations. Have a look at the manual section for
-  :py:mod:`xbob.io` for more details and other shortcuts available.
+  :py:mod:`xbob.io.base` for more details and other shortcuts available.
 
 Reading and writing images
 --------------------------
@@ -350,8 +355,8 @@ must be of type uint8 or uint16.
 .. doctest::
 
   >>> my_image = numpy.random.random_integers(0,255,(3,256,256))
-  >>> xbob.io.save(my_image.astype('uint8'), 'testimage.jpg') # saving the image in jpeg format
-  >>> my_image_copy = xbob.io.load('testimage.jpg')
+  >>> xbob.io.base.save(my_image.astype('uint8'), 'testimage.jpg') # saving the image in jpeg format
+  >>> my_image_copy = xbob.io.base.load('testimage.jpg')
 
 .. tip::
 
@@ -371,25 +376,25 @@ with images:
 .. doctest::
 
   >>> my_video = numpy.random.random_integers(0,255,(30,3,256,256))
-  >>> xbob.io.save(my_video.astype('uint8'), 'testvideo.avi') # saving the video avi format with a default codec
-  >>> my_video_copy = xbob.io.load('testvideo.avi')
+  >>> xbob.io.base.save(my_video.astype('uint8'), 'testvideo.avi') # saving the video avi format with a default codec
+  >>> my_video_copy = xbob.io.base.load('testvideo.avi')
 
 Video reading and writing is performed using an `FFmpeg`_ (or `libav`_ if
-`FFmpeg`_ is not available) bridge. |project|'s :py:meth:`xbob.io.save` method
-will allow you to choose the output format with the same extension mechanism as
-mentioned earlier. `FFmpeg`_ will then choose a default codec for the format
-and perform encoding. The output file can be as easily loaded using
-:py:meth:`xbob.io.load`.
+`FFmpeg`_ is not available) bridge. |project|'s :py:meth:`xbob.io.base.save`
+method will allow you to choose the output format with the same extension
+mechanism as mentioned earlier. `FFmpeg`_ will then choose a default codec for
+the format and perform encoding. The output file can be as easily loaded using
+:py:meth:`xbob.io.base.load`.
 
 For finer control over the loading, saving, format and codecs used for a
 specific encoding or decoding operation, you must directly use either
-:py:class:`xbob.io.VideoReader` or :py:class:`xbob.io.VideoWriter` classes. For
-example, it is possible to use :py:class:`xbob.io.VideoReader` to read videos
-frame by frame and avoid overloading your machine's memory. In the following
-example you can see how to create a video, save it using the class
-:py:class:`xbob.io.VideoWriter` and load it again using the class
-:py:class:`xbob.io.VideoReader`. The created video will have 30 frames
-generated randomly.
+:py:class:`xbob.io.base.VideoReader` or :py:class:`xbob.io.base.VideoWriter`
+classes. For example, it is possible to use
+:py:class:`xbob.io.base.VideoReader` to read videos frame by frame and avoid
+overloading your machine's memory. In the following example you can see how to
+create a video, save it using the class :py:class:`xbob.io.base.VideoWriter`
+and load it again using the class :py:class:`xbob.io.base.VideoReader`. The
+created video will have 30 frames generated randomly.
 
 .. note::
 
@@ -400,12 +405,12 @@ generated randomly.
 
   >>> width = 50; height = 50;
   >>> framerate = 24
-  >>> outv = xbob.io.VideoWriter('testvideo.avi', height, width, framerate, codec='mpeg1video') # output video
+  >>> outv = xbob.io.base.VideoWriter('testvideo.avi', height, width, framerate, codec='mpeg1video') # output video
   >>> for i in range(0, 30):
   ...   newframe = (numpy.random.random_integers(0,255,(3,height,width)))
   ...   outv.append(newframe.astype('uint8'))
   >>> outv.close()
-  >>> input = xbob.io.VideoReader('testvideo.avi')
+  >>> input = xbob.io.base.VideoReader('testvideo.avi')
   >>> input.number_of_frames
   30
   >>> inv = input.load()
@@ -434,12 +439,13 @@ in version of |project| installed on your machine can be listed using the
 Loading and saving Matlab data
 ------------------------------
 
-An alternative for saving data in ``.mat`` files using :py:meth:`xbob.io.save`,
-would be to save them as a `HDF5`_ file which then can be easily read in
-Matlab. Similarly, instead of having to read ``.mat`` files using
-:py:meth:`xbob.io.load`, you can save your Matlab data in `HDF5`_ format, which
-then can be easily read from |project|. Detailed instructions about how to save
-and load data from Matlab to and from `HDF5`_ files can be found `here`__.
+An alternative for saving data in ``.mat`` files using
+:py:meth:`xbob.io.base.save`, would be to save them as a `HDF5`_ file which
+then can be easily read in Matlab. Similarly, instead of having to read
+``.mat`` files using :py:meth:`xbob.io.base.load`, you can save your Matlab
+data in `HDF5`_ format, which then can be easily read from |project|. Detailed
+instructions about how to save and load data from Matlab to and from `HDF5`_
+files can be found `here`__.
 
 .. _audiosignal:
 

doc/index.rst

 .. vim: set fileencoding=utf-8 :
 .. Andre Anjos <andre.anjos@idiap.ch>
-.. Mon  4 Nov 20:58:04 2013 CET
+.. Wed 14 May 15:22:33 2014 CEST
 ..
-.. Copyright (C) 2011-2013 Idiap Research Institute, Martigny, Switzerland
+.. Copyright (C) 2011-2014 Idiap Research Institute, Martigny, Switzerland
 
-====================
- Bob's I/O Routines
-====================
+=========================
+ Bob's Core I/O Routines
+=========================
 
 .. todolist::