Skip to content
Snippets Groups Projects
Commit 22e754c7 authored by André Anjos's avatar André Anjos :speech_balloon:
Browse files

Documentation patches

parent 18361e20
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/c_cpp_api.rst
+ 17
− 13
View file @ 22e754c7
......@@ -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
+ 6
− 6
View file @ 22e754c7
......@@ -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
+ 79
− 73
View file @ 22e754c7
......@@ -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
+ 5
− 5
View file @ 22e754c7
.. 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::
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment