Commit 38baf284 authored by André Anjos's avatar André Anjos 💬

Initial commit

parents
*~
*.swp
*.pyc
*.so
bin
eggs
parts
.installed.cfg
.mr.developer.cfg
*.egg-info
develop-eggs
sphinx
dist
.nfs*
.gdb_history
build
*.egg
src/
# After changing this file, run it through http://lint.travis-ci.org/
# Generates 4 builds, the ones for python3 will install external wheels
language: python
python:
- 2.6
- 2.7
matrix:
include:
- python: 3.2
env:
- NUMPYSPEC===1.7.1
- python: 3.3
env:
- NUMPYSPEC===1.8.0
before_install:
- sudo add-apt-repository -y ppa:biometrics/bob
- sudo add-apt-repository -y ppa:biometrics/bob.preview
- sudo apt-get update -qq
- sudo apt-get install -qq --force-yes bob-dev libjpeg8-dev libnetpbm10-dev libpng12-dev libtiff4-dev libgif-dev
- sudo apt-get install -qq python-imaging
- if [ -n "${NUMPYSPEC}" ]; then sudo apt-get install -qq libatlas-dev libatlas-base-dev liblapack-dev gfortran; fi
- if [ -n "${NUMPYSPEC}" ]; then pip install --upgrade pip setuptools; fi
- if [ -n "${NUMPYSPEC}" ]; then pip install --find-links http://wheels.astropy.org/ --find-links http://wheels2.astropy.org/ --use-wheel numpy$NUMPYSPEC sphinx nose; fi
- pip install cpp-coveralls
install:
- "python bootstrap.py"
- "CFLAGS=-coverage ./bin/buildout"
script:
- "./bin/python -c 'from xbob.io.base import get_config; print(get_config())'"
- "./bin/coverage run --source=xbob.io.base ./bin/nosetests -sv"
- "./bin/sphinx-build -b doctest doc sphinx"
- "./bin/sphinx-build -b html doc sphinx"
after_success:
- "coveralls --build-root=`pwd` --exclude=src"
Copyright (c) 2013, Andre Anjos - Idiap Research Institute
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer. Redistributions in binary
form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with
the distribution. Neither the name of the Idiap Research Institute nor the
names of its contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
include LICENSE README.rst bootstrap.py buildout.cfg
recursive-include doc conf.py *.rst
recursive-include xbob *.cpp *.h
recursive-include xbob/io/image/data *.*
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.anjos@idiap.ch>
.. Thu 29 Aug 2013 16:07:57 CEST
.. image:: https://travis-ci.org/bioidiap/xbob.io.matlab.svg?branch=master
:target: https://travis-ci.org/bioidiap/xbob.io.matlab
.. image:: https://coveralls.io/repos/bioidiap/xbob.io.matlab/badge.png
:target: https://coveralls.io/r/bioidiap/xbob.io.matlab
.. image:: http://img.shields.io/github/tag/bioidiap/xbob.io.matlab.png
:target: https://github.com/bioidiap/xbob.io.matlab
.. image:: http://img.shields.io/pypi/v/xbob.io.matlab.png
:target: https://pypi.python.org/pypi/xbob.io.matlab
.. image:: http://img.shields.io/pypi/dm/xbob.io.matlab.png
:target: https://pypi.python.org/pypi/xbob.io.matlab
===================================
Support for Matlab I/O in bob::io
===================================
This package contains no bindings. By importing it, you activate a transparent
plugin that makes possible reading and writing to Matlab(R) files using
:py:mod:`xbob.io.base` functionality.
Installation
------------
Install it through normal means, via PyPI or use ``zc.buildout`` to bootstrap
the package and run test units.
Documentation
-------------
You can generate the documentation for this package, after installation, using
Sphinx::
$ sphinx-build -b html doc sphinx
This shall place in the directory ``sphinx``, the current version for the
documentation of the package.
Usage
-----
In order to enable support for Matlab(R) file reading and writing in your
application, make sure to import this module, before calling
:py:func:`xbob.io.base.open` or similar::
>>> import xbob.io.base
>>> import xbob.io.matlab
>>> xbob.io.base.open('myfile.mat', 'r')
Testing
-------
You can run a set of tests using the nose test runner::
$ nosetests -sv xbob.io.matlab
.. warning::
If Bob <= 1.2.1 is installed on your python path, nose will automatically
load the old version of the insulate plugin available in Bob, which will
trigger the loading of incompatible shared libraries (from Bob itself), in
to your working binary. This will cause a stack corruption. Either remove
the centrally installed version of Bob, or build your own version of Python
in which Bob <= 1.2.1 is not installed.
You can run our documentation tests using sphinx itself::
$ sphinx-build -b doctest doc sphinx
You can test overall test coverage with::
$ nosetests --with-coverage --cover-package=xbob.io.matlab
The ``coverage`` egg must be installed for this to work properly.
Development
-----------
To develop this package, install using ``zc.buildout``, using the buildout
configuration found on the root of the package::
$ python bootstrap.py
...
$ ./bin/buildout
Tweak the options in ``buildout.cfg`` to disable/enable verbosity and debug
builds.
##############################################################################
#
# Copyright (c) 2006 Zope Foundation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Bootstrap a buildout-based project
Simply run this script in a directory containing a buildout.cfg.
The script accepts buildout command-line options, so you can
use the -c option to specify an alternate configuration file.
"""
import os
import shutil
import sys
import tempfile
from optparse import OptionParser
tmpeggs = tempfile.mkdtemp()
usage = '''\
[DESIRED PYTHON FOR BUILDOUT] bootstrap.py [options]
Bootstraps a buildout-based project.
Simply run this script in a directory containing a buildout.cfg, using the
Python that you want bin/buildout to use.
Note that by using --find-links to point to local resources, you can keep
this script from going over the network.
'''
parser = OptionParser(usage=usage)
parser.add_option("-v", "--version", help="use a specific zc.buildout version")
parser.add_option("-t", "--accept-buildout-test-releases",
dest='accept_buildout_test_releases',
action="store_true", default=False,
help=("Normally, if you do not specify a --version, the "
"bootstrap script and buildout gets the newest "
"*final* versions of zc.buildout and its recipes and "
"extensions for you. If you use this flag, "
"bootstrap and buildout will get the newest releases "
"even if they are alphas or betas."))
parser.add_option("-c", "--config-file",
help=("Specify the path to the buildout configuration "
"file to be used."))
parser.add_option("-f", "--find-links",
help=("Specify a URL to search for buildout releases"))
options, args = parser.parse_args()
######################################################################
# load/install setuptools
to_reload = False
try:
import pkg_resources
import setuptools
except ImportError:
ez = {}
try:
from urllib.request import urlopen
except ImportError:
from urllib2 import urlopen
# XXX use a more permanent ez_setup.py URL when available.
exec(urlopen('https://bitbucket.org/pypa/setuptools/raw/0.7.2/ez_setup.py'
).read(), ez)
setup_args = dict(to_dir=tmpeggs, download_delay=0)
ez['use_setuptools'](**setup_args)
if to_reload:
reload(pkg_resources)
import pkg_resources
# This does not (always?) update the default working set. We will
# do it.
for path in sys.path:
if path not in pkg_resources.working_set.entries:
pkg_resources.working_set.add_entry(path)
######################################################################
# Try to best guess the version of buildout given setuptools
if options.version is None:
try:
from distutils.version import LooseVersion
package = pkg_resources.require('setuptools')[0]
v = LooseVersion(package.version)
if v < LooseVersion('0.7'):
options.version = '2.1.1'
except:
pass
######################################################################
# Install buildout
ws = pkg_resources.working_set
cmd = [sys.executable, '-c',
'from setuptools.command.easy_install import main; main()',
'-mZqNxd', tmpeggs]
find_links = os.environ.get(
'bootstrap-testing-find-links',
options.find_links or
('http://downloads.buildout.org/'
if options.accept_buildout_test_releases else None)
)
if find_links:
cmd.extend(['-f', find_links])
setuptools_path = ws.find(
pkg_resources.Requirement.parse('setuptools')).location
requirement = 'zc.buildout'
version = options.version
if version is None and not options.accept_buildout_test_releases:
# Figure out the most recent final version of zc.buildout.
import setuptools.package_index
_final_parts = '*final-', '*final'
def _final_version(parsed_version):
for part in parsed_version:
if (part[:1] == '*') and (part not in _final_parts):
return False
return True
index = setuptools.package_index.PackageIndex(
search_path=[setuptools_path])
if find_links:
index.add_find_links((find_links,))
req = pkg_resources.Requirement.parse(requirement)
if index.obtain(req) is not None:
best = []
bestv = None
for dist in index[req.project_name]:
distv = dist.parsed_version
if _final_version(distv):
if bestv is None or distv > bestv:
best = [dist]
bestv = distv
elif distv == bestv:
best.append(dist)
if best:
best.sort()
version = best[-1].version
if version:
requirement = '=='.join((requirement, version))
cmd.append(requirement)
import subprocess
if subprocess.call(cmd, env=dict(os.environ, PYTHONPATH=setuptools_path)) != 0:
raise Exception(
"Failed to execute command:\n%s",
repr(cmd)[1:-1])
######################################################################
# Import and run buildout
ws.add_entry(tmpeggs)
ws.require(requirement)
import zc.buildout.buildout
if not [a for a in args if '=' not in a]:
args.append('bootstrap')
# if -c was provided, we push it back into args for buildout' main function
if options.config_file is not None:
args[0:0] = ['-c', options.config_file]
zc.buildout.buildout.main(args)
shutil.rmtree(tmpeggs)
; vim: set fileencoding=utf-8 :
; Andre Anjos <andre.anjos@idiap.ch>
; Mon 16 Apr 08:29:18 2012 CEST
[buildout]
parts = scripts
eggs = xbob.io.matlab
extensions = xbob.buildout
mr.developer
auto-checkout = *
develop = src/xbob.extension
src/xbob.blitz
src/xbob.io.base
.
; options for xbob.buildout extension
debug = true
verbose = true
prefixes = /idiap/group/torch5spro/nightlies/last/bob/linux-x86_64-release
/Users/andre/work/bob/b/dbg/
[sources]
xbob.extension = git https://github.com/bioidiap/xbob.extension branch=prototype
xbob.blitz = git https://github.com/bioidiap/xbob.blitz
xbob.io.base = git https://github.com/bioidiap/xbob.io.base
[scripts]
recipe = xbob.buildout:scripts
.. 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
#!/usr/bin/env python
# vim: set fileencoding=utf-8 :
# Andre Anjos <andre.anjos@idiap.ch>
# Tue 15 Oct 16:37:18 2013 CEST
#
# Copyright (C) 2011-2014 Idiap Research Institute, Martigny, Switzerland
import os
import sys
import glob
import pkg_resources
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.pngmath',
'sphinx.ext.ifconfig',
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
]
# The viewcode extension appeared only on Sphinx >= 1.0.0
import sphinx
if sphinx.__version__ >= "1.0":
extensions.append('sphinx.ext.viewcode')
# Always includes todos
todo_include_todos = True
# If we are on OSX, the 'dvipng' path maybe different
dvipng_osx = '/opt/local/libexec/texlive/binaries/dvipng'
if os.path.exists(dvipng_osx): pngmath_dvipng = dvipng_osx
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
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.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
# built documents.
#
# The short X.Y version.
version = distribution.version
# The full version, including alpha/beta/rc tags.
release = distribution.version
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['links.rst']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
if sphinx.__version__ >= "1.0":
html_theme = 'nature'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = 'xbob_io_base'
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = 'img/logo.png'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
html_favicon = 'img/favicon.ico'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# 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.
#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'