Commit 87ec296b authored by André Anjos's avatar André Anjos 💬

Documentation overhaul

parent 8f3758ce
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.dos.anjos@gmail.com>
.. Tue 15 Oct 14:59:05 2013
=========
C++ API
=========
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>`_.
Here is a dummy C example showing how to include the header and where to call
the import function:
.. code-block:: c++
#include <xbob.io.base/api.h>
PyMODINIT_FUNC initclient(void) {
PyObject* m Py_InitModule("client", ClientMethods);
if (!m) return;
/* imports dependencies */
if (import_xbob_blitz() < 0) {
PyErr_Print();
PyErr_SetString(PyExc_ImportError, "cannot import extension");
return 0;
}
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.base.get_include`.
Generic Functions
-----------------
.. cpp:function:: int PyBobIo_AsTypenum(bob::core::array::ElementType et)
Converts the input Bob element type into a ``NPY_<TYPE>`` enumeration value.
Returns ``NPY_NOTYPE`` in case of problems, and sets a
:py:class:`RuntimeError`.
.. cpp:function:: PyObject* PyBobIo_TypeInfoAsTuple (const bob::core::array::typeinfo& ti)
Converts the ``bob::core::array::typeinfo&`` object into a **new reference**
to a :py:class:`tuple` with 3 elements:
[0]
The data type as a :py:class:`numpy.dtype` object
[1]
The shape of the object, as a tuple of integers
[2]
The strides of the object, as a tuple of integers
Returns ``0`` in case of failure, or a **new reference** to the tuple
described above in case of success.
.. cpp:function:: int PyBobIo_FilenameConverter (PyObject* o, PyObject** b)
This function is meant to be used with :c:func:`PyArg_ParseTupleAndKeywords`
family of functions in the Python C-API. It converts an arbitrary input
object into a ``PyStringObject`` (in Python2.x) and into a ``PyBytesObject``
(in Python3.x). If the input object is of type ``PyUnicodeObject``, which is
the default in Python3.x, the unicode code is properly decoded using
:c:func:`PyUnicode_AsEncodedString` with ``encoding`` set to
``Py_FileSystemDefaultEncoding`` and ``errors`` set to ``"strict"``. On
versions of Python >= 3.2, this is just an alias for
:c:func:`PyUnicode_FSConverter`, which does a similar job.
Objects which are not ``PyUnicodeObject`` are coerced into a bytes/string
object using :c:func:`PyObject_Bytes` (on Python3.x) and
:c:func:`PyObject_Str` (on Python 2.x).
Returns 0 if an error is detected, 1 on success.
Bob File Support
----------------
.. cpp:type:: PyBobIoFileObject
The pythonic object representation for a ``bob::io::File`` object.
.. code-block:: cpp
typedef struct {
PyObject_HEAD
boost::shared_ptr<bob::io::File> f;
} PyBobIoFileObject;
.. cpp:member:: boost::shared_ptr<bob::io::File> f
A pointer to a file being read or written.
.. cpp:type:: PyBobIoFileIteratorObject
The pythonic object representation for an iterator over a ``bob::io::File``
object.
.. code-block:: cpp
typedef struct {
PyObject_HEAD
PyBobIoFileObject* pyfile;
Py_ssize_t curpos;
} PyBobIoFileIteratorObject;
.. cpp:member:: PyBobIoFileObject* pyfile
A pointer to the pythonic representation of a file.
.. cpp:member:: Py_ssize_t curpos
The current position at the file being pointed to.
Bob HDF5 Support
----------------
.. cpp:type:: PyBobIoHDF5FileObject
The pythonic object representation for a ``bob::io::HDF5File`` object.
.. code-block:: cpp
typedef struct {
PyObject_HEAD
boost::shared_ptr<bob::io::HDF5File> f;
} PyBobIoHDF5FileObject;
.. cpp:member:: boost::shared_ptr<bob::io::HDF5File> f
A pointer to a Bob object being used to read/write data into an HDF5
file.
.. cpp:function:: int PyBobIoHDF5File_Check(PyObject* o)
Checks if the input object ``o`` is a ``PyBobIoHDF5FileObject``. Returns
``1`` if it is, and ``0`` otherwise.
.. cpp:function:: int PyBobIoHDF5File_Converter(PyObject* o, PyBobIoHDF5FileObject** a)
This function is meant to be used with :c:func:`PyArg_ParseTupleAndKeywords`
family of functions in the Python C-API. It checks the input object to be of
type ``PyBobIoHDF5FileObject`` and sets a **new reference** to it (in
``*a``) if it is the case. Returns ``0`` in case of failure, ``1`` in case
of success.
.. include:: links.rst
......@@ -58,12 +58,12 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'xbob.io.base'
project = u'xbob.io.image'
import time
copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
# Grab the setup entry
distribution = pkg_resources.require('xbob.io.base')[0]
distribution = pkg_resources.require('xbob.io.image')[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_base'
#html_short_title = 'xbob_io_image'
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
......@@ -180,14 +180,14 @@ html_favicon = 'img/favicon.ico'
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# image URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'xbob_io_base_doc'
htmlhelp_basename = 'xbob_io_image_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_base.tex', u'Core Bob I/O Routines',
('index', 'xbob_io_image.tex', u'Image I/O Support for Bob',
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_base', u'Core Bob I/O Routines Documentation', [u'Idiap Research Institute'], 1)
('index', 'xbob_io_image', u'Image I/O Support for Bob', [u'Idiap Research Institute'], 1)
]
# Default processing flags for sphinx
......
This diff is collapsed.
......@@ -10,9 +10,18 @@
.. todolist::
This module contains base functionality from Bob bound to Python, available in
the C++ counter-part ``bob::io``. It includes input and output operations to
and from files.
This module provides a plugin for :py:mod:`xbob.io.base` that allows |project|
to read and write images using its native API (:py:func:`xbob.io.base.load` and
:py:func:`xbob.io.base.save`).
At present, this plugin provides support for the following types of images:
* TIFF
* JPEG
* GIF
* PNG
* BMP
* Netpbm images (PGM, PPM, PBM)
Documentation
-------------
......@@ -22,7 +31,6 @@ Documentation
guide
py_api
c_cpp_api
Indices and tables
------------------
......
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.dos.anjos@gmail.com>
.. Sat 16 Nov 20:52:58 2013
.. Fri 16 May 15:51:24 2014 CEST
============
Python API
============
This section includes information for using the pure Python API of ``xbob.io``.
This section includes information for using the pure Python API of
``xbob.io.image``.
.. automodule:: xbob.io.image
Classes
-------
.. autoclass:: xbob.io.File
.. autoclass:: xbob.io.HDF5File
Functions
---------
.. autofunction:: xbob.io.load
.. autofunction:: xbob.io.merge
.. autofunction:: xbob.io.save
.. autofunction:: xbob.io.append
.. autofunction:: xbob.io.peek
.. autofunction:: xbob.io.peek_all
.. autofunction:: xbob.io.create_directories_save
C++ API Helpers
---------------
.. autofunction:: xbob.io.get_include
Markdown is supported
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