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

Initial commit

parents
No related branches found
No related tags found
No related merge requests found
*~
*.swp
*.pyc
*.so
bin
eggs
parts
.installed.cfg
.mr.developer.cfg
*.egg-info
develop-eggs
sphinx
dist
.nfs*
.gdb_history
build
*.egg
src/
opsnr.stt
[submodule "src/xbob.blitz"]
path = src/xbob.blitz
url = git@github.com:anjos/xbob.blitz
LICENSE 0 → 100644
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/test/data *.*
recursive-include xbob/io/fonts *.txt *.ttf
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.anjos@idiap.ch>
.. Thu 29 Aug 2013 16:07:57 CEST
=================================
Python bindings for bob.measure
=================================
This package contains a set of Pythonic bindings for Bob's measure packages and
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.
Testing
-------
You can run a set of tests using the nose test runner::
$ nosetests -sv xbob.measure
.. 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.measure
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 = xbob.blitz xbob.measure scripts
eggs = xbob.measure
ipdb
extensions = mr.developer
auto-checkout = *
prefixes = /Users/andre/work/bob/b/dbg
debug = true
verbose = true
[sources]
xbob.buildout = git git@github.com:bioidiap/xbob.buildout
xbob.extension = git git@github.com:bioidiap/xbob.extension branch=xbob
[xbob.blitz]
recipe = xbob.buildout:develop
setup = src/xbob.blitz
eggs = xbob.buildout xbob.extension
[xbob.measure]
recipe = xbob.buildout:develop
eggs = xbob.blitz
[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`` 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
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/api.h>
PyMODINIT_FUNC initclient(void) {
PyObject* m Py_InitModule("client", ClientMethods);
if (!m) return;
// imports the NumPy C-API
import_array();
// imports blitz.array C-API
import_blitz_array();
// imports xbob.core.random C-API
import_xbob_io();
}
.. note::
The include directory can be discovered using
:py:func:`xbob.io.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.
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.
Bob VideoReader Support
-----------------------
.. note::
The video C-API (and Python) is only available if the package was compiled
with FFMPEG or LibAV support.
.. cpp:type:: PyBobIoVideoReaderObject
The pythonic object representation for a ``bob::io::VideoReader`` object.
.. code-block:: cpp
typedef struct {
PyObject_HEAD
boost::shared_ptr<bob::io::VideoReader> v;
} PyBobIoVideoReaderObject;
.. cpp:member:: boost::shared_ptr<bob::io::VideoReader> v
A pointer to a Bob object being used to read the video contents
.. cpp:type:: PyBobIoVideoReaderIteratorObject
The pythonic object representation for an iterator over a
``bob::io::VideoReader`` object.
.. code-block:: cpp
typedef struct {
PyObject_HEAD
PyBobIoVideoReaderObject* pyreader;
boost::shared_ptr<bob::io::VideoReader::const_iterator> iter;
} PyBobIoFileIteratorObject;
.. cpp:member:: PyBobIoVideoReaderObject* pyreader
A pointer to the pythonic representation of the video reader.
.. cpp:member:: boost::shared_ptr<bob::io::VideoReader::const_iterator> iter
The current position at the file being pointed to, represented by a
formal iterator over the VideoReader.
.. cpp:type:: PyBobIoVideoReaderObject
The pythonic object representation for a ``bob::io::VideoWriter`` object.
.. code-block:: cpp
typedef struct {
PyObject_HEAD
boost::shared_ptr<bob::io::VideoWriter> v;
} PyBobIoVideoWriterObject;
.. cpp:member:: boost::shared_ptr<bob::io::VideoWriter> v
A pointer to a Bob object being used to write contents to the video.
.. 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-2013 Idiap Research Institute, Martigny, Switzerland
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, version 3 of the License.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
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',
'matplotlib.sphinxext.plot_directive',
]
# 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'
import time
copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
# Grab the setup entry
distribution = pkg_resources.require('xbob.io')[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'
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = ''
# 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 = ''
# 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_doc'
# -- Options for LaTeX output --------------------------------------------------
# The paper size ('letter' or 'a4').
latex_paper_size = 'a4'
# The font size ('10pt', '11pt' or '12pt').
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',
u'Biometrics Group, Idiap Research Institute', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
latex_logo = ''
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# Included after all input documents
rst_epilog = """
.. |version| replace:: %s
.. |project| replace:: Bob
""" % (version,)
# -- Options for manual page output --------------------------------------------
# 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)
]
# Default processing flags for sphinx
autoclass_content = 'both'
autodoc_member_order = 'bysource'
autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-inheritance']
def smaller_than(v1, v2):
"""Compares scipy/numpy version numbers"""
c1 = v1.split('.')
c2 = v2.split('.')[:len(c1)] #clip to the compared version
for i, k in enumerate(c2):
n1 = c1[i]
n2 = c2[i]
try:
n1 = int(n1)
n2 = int(n2)
except ValueError:
n1 = str(n1)
n2 = str(n2)
if n1 > n2: return False
return True
# Some name mangling to find the correct sphinx manuals for some packages
numpy_version = __import__('numpy').version.version
if smaller_than(numpy_version, '1.5.z'):
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.x'
else:
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.0'
numpy_manual = 'http://docs.scipy.org/doc/numpy-%s/' % numpy_version
# For inter-documentation mapping:
intersphinx_mapping = {
'http://docs.python.org/%d.%d/' % sys.version_info[:2]: None,
numpy_manual: None,
}
def setup(app):
pass
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.dos.anjos@gmail.com>
.. Tue 15 Oct 17:41:52 2013
.. testsetup:: iotest
import numpy
import xbob.io
============
User Guide
============
This section gives an overview of the operations for storing and retrieving the
basic data structures in |project|, such as `NumPy`_ arrays. |project| uses
`HDF5`_ format for storing binary coded data. Using the |project| support for
`HDF5`_, it is very simple to import and export data.
`HDF5`_ uses a neat descriptive language for representing the data in the HDF5
files, called Data Description Language (`DDL`_).
To perform the functionalities given in this section, you should have `NumPy`_
and |project| loaded into the `Python`_ environment.
.. testsetup:: *
import numpy
import xbob.io
import tempfile
import os
current_directory = os.path.realpath(os.curdir)
temp_dir = tempfile.mkdtemp(prefix='bob_doctest_')
os.chdir(temp_dir)
HDF5 standard utilities
-----------------------
Before explaining the basics of reading and writing to `HDF5`_ files, it is
important to list some `HDF5`_ standard utilities for checking the content of
an `HDF5`_ file. These are supplied by the `HDF5`_ project.
``h5dump``
Dumps the content of the file using the DDL.
``h5ls``
Lists the content of the file using DDL, but does not show the data.
``h5diff``
Finds the differences between HDF5 files.
I/O operations using the class `xbob.io.HDF5File`
-------------------------------------------------
Writing operations
------------------
Let's take a look at how to write simple scalar data such as integers or
floats.
.. doctest::
>>> an_integer = 5
>>> a_float = 3.1416
>>> f = xbob.io.HDF5File('testfile1.hdf5', 'w')
>>> f.set('my_integer', an_integer)
>>> f.set('my_float', a_float)
>>> del f
If after this you use the **h5dump** utility on the file ``testfile1.hdf5``,
you will verify that the file now contains:
.. code-block:: none
HDF5 "testfile1.hdf5" {
GROUP "/" {
DATASET "my_float" {
DATATYPE H5T_IEEE_F64LE
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
DATA {
(0): 3.1416
}
}
DATASET "my_integer" {
DATATYPE H5T_STD_I32LE
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
DATA {
(0): 5
}
}
}
}
.. note::
In |project|, when you open a HDF5 file, you can choose one of the following
options:
**'r'** Open the file in reading mode; writing operations will fail (this is the default).
**'a'** Open the file in reading and writing mode with appending.
**'w'** Open the file in reading and writing mode, but truncate it.
**'x'** Read/write/append with exclusive access.
The dump shows that there are two datasets inside a group named ``/`` in the
file. HDF5 groups are like file system directories. They create namespaces for
the data. In the root group (or directory), you will find the two variables,
named as you set them to be. The variable names are the complete path to the
location where they live. You could write a new variable in the same file but
in a different directory like this:
.. doctest::
>>> f = xbob.io.HDF5File('testfile1.hdf5', 'a')
>>> f.create_group('/test')
>>> f.set('/test/my_float', numpy.float32(6.28))
>>> del f
Line 1 opens the file for reading and writing, but without truncating it. This
will allow you to access the file contents. Next, the directory ``/test`` is
created and a new variable is written inside the subdirectory. As you can
verify, **for simple scalars**, you can also force the storage type. Where
normally one would have a 64-bit real value, you can impose that this variable
is saved as a 32-bit real value. You can verify the dump correctness with
``h5dump``:
.. code-block:: none
GROUP "/" {
...
GROUP "test" {
DATASET "my_float" {
DATATYPE H5T_IEEE_F32LE
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
DATA {
(0): 6.28
}
}
}
}
Notice the subdirectory ``test`` has been created and inside it a floating
point number has been stored. Such a float point number has a 32-bit precision
as it was defined.
.. note::
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:meth:`HDF5File.cd`. Look up its help for more information and usage
instructions.
Writing arrays is a little simpler as the :py:class:`numpy.ndarray` objects
encode all the type information we need to write and read them correctly. Here
is an example:
.. doctest::
>>> A = numpy.array(range(4), 'int8').reshape(2,2)
>>> f = xbob.io.HDF5File('testfile1.hdf5', 'a')
>>> f.set('my_array', A)
>>> del f
The result of running ``h5dump`` on the file ``testfile3.hdf5`` should be:
.. code-block:: none
...
DATASET "my_array" {
DATATYPE H5T_STD_I8LE
DATASPACE SIMPLE { ( 2, 2 ) / ( 2, 2 ) }
DATA {
(0,0): 0, 1,
(1,0): 2, 3
}
}
...
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`.
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:
.. doctest::
>>> f = xbob.io.HDF5File('testfile1.hdf5') #read only
>>> f.read('my_integer') #reads integer
5
>>> print(f.read('my_array')) # reads the array
[[0 1]
[2 3]]
>>> 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.
.. doctest::
>>> f = xbob.io.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'))
>>> print(f.lread('arrayset', 0))
[ 0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]
>>> print(f.lread('arrayset', 2))
[ 0. 3. 6. 9. 12. 15. 18. 21. 24. 27.]
>>> del f
This is what the ``h5dump`` of the file would look like:
.. code-block:: none
HDF5 "testfile4.hdf5" {
GROUP "/" {
DATASET "arrayset" {
DATATYPE H5T_IEEE_F64LE
DATASPACE SIMPLE { ( 3, 10 ) / ( H5S_UNLIMITED, 10 ) }
DATA {
(0,0): 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
(1,0): 0, 2, 4, 6, 8, 10, 12, 14, 16, 18,
(2,0): 0, 3, 6, 9, 12, 15, 18, 21, 24, 27
}
}
}
}
Notice that the expansion limits for the first dimension have been correctly
set by |project| so you can insert an *unlimited* number of 1D float vectors.
Of course, you can also read the whole contents of the arrayset in a single
shot:
.. doctest::
>>> f = xbob.io.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
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.
Array interfaces
----------------
What we have shown so far is the generic API to read and write data using HDF5.
You will use it when you want to import or export data from |project| into
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
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.
To create an :py:class:`xbob.io.File` from a file path, just do the following:
.. doctest::
>>> a = xbob.io.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:
.. doctest::
>>> array = a.read()
>>> array
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.]])
Every time you say :py:meth:`xbob.io.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:
.. doctest::
>>> f = xbob.io.File('copy1.hdf5', 'w')
>>> f.write(a)
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:
.. doctest::
>>> t = xbob.io.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:
.. doctest::
>>> xbob.io.save(t, 'copy2.hdf5')
.. note::
Under the hood, we still use the :py:class:`xbob.io.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.
Reading and writing images
--------------------------
|project| provides support to load and save data from many different file types
including Matlab ``.mat`` files, various image file types and video data. File
types and specific serialization and de-serialization is switched automatically
using filename extensions. Knowing this, saving an array in a different format
is just a matter of choosing the right extension. This is illustrated in the
following example, where an image generated randomly using the method `NumPy`
:py:meth:`numpy.random.random_integers`, is saved in JPEG format. The image
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')
.. tip::
To find out about which formats and extensions are supported in a given
installation of |project|, just call ``bob_config.py`` on your prompt. It
will print a list of compiled-in software and supported extensions.
The loaded image files can be 3D arrays (for RGB format) or 2D arrays (for
greyscale) of type ``uint8`` or ``uint16``.
Dealing with videos
-------------------
|project| has support for dealing with videos in an equivalent way to dealing
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')
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`.
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.
.. note::
Due to `FFmpeg`_ constrains, the width and height of the video need to be
multiples of two.
.. doctest::
>>> width = 50; height = 50;
>>> framerate = 24
>>> outv = xbob.io.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.number_of_frames
30
>>> inv = input.load()
>>> inv.shape
(30, 3, 50, 50)
>>> type(inv)
<... 'numpy.ndarray'>
Videos in |project| are represented as sequences of colored images, i.e. 4D
arrays of type ``uint8``. All the extensions and formats for videos supported
in version of |project| installed on your machine can be listed using the
|project|'s utility ``bob_config.py``.
.. testcleanup:: *
import shutil
os.chdir(current_directory)
shutil.rmtree(temp_dir)
.. warning::
Please read :doc:`video` for details on choosing codecs and formats that are
adequate to your application, as well as drawbacks and pitfalls with video
encoding and decoding.
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`__.
.. _audiosignal:
Loading and saving audio files
------------------------------
|project| does not yet support audio files (no wav codec). However, it is
possible to use the `SciPy`_ module :py:mod:`scipy.io.wavfile` to do the job.
For instance, to read a wave file, just use the
:py:func:`scipy.io.wavfile.read` function.
.. code-block:: python
>>> import scipy.io.wavfile
>>> filename = '/home/user/sample.wav'
>>> samplerate, data = scipy.io.wavfile.read(filename)
>>> print(type(data))
<... 'numpy.ndarray'>
>>> print(data.shape)
(132474, 2)
In the above example, the stereo audio signal is represented as a 2D `NumPy`
:py:class:`numpy.ndarray`. The first dimension corresponds to the time index
(132474 frames) and the second dimesnion correpsonds to one of the audio
channel (2 channels, stereo). The values in the array correpsond to the wave
magnitudes.
To save a `NumPy` :py:class:`numpy.ndarray` into a wave file, the
:py:func:`scipy.io.wavfile.write` could be used, which also requires the
framerate to be specified.
.. include:: links.rst
.. Place here your external references
.. _ddl: http://www.hdfgroup.org/HDF5/doc/ddl.html
.. _matlab-hdf5: http://www.mathworks.ch/help/techdoc/ref/hdf5write.html
__ matlab-hdf5_
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.anjos@idiap.ch>
.. Mon 4 Nov 20:58:04 2013 CET
..
.. Copyright (C) 2011-2013 Idiap Research Institute, Martigny, Switzerland
====================
Bob's I/O Routines
====================
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.
Reference
---------
.. toctree::
:maxdepth: 2
guide
video
py_api
c_cpp_api
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. include:: links.rst
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.anjos@idiap.ch>
.. Tue 20 Mar 2012 08:57:32 CET
..
.. Copyright (C) 2011-2013 Idiap Research Institute, Martigny, Switzerland
..
.. This program is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, version 3 of the License.
..
.. This program is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.. GNU General Public License for more details.
..
.. You should have received a copy of the GNU General Public License
.. along with this program. If not, see <http://www.gnu.org/licenses/>.
.. This file contains all links we use for documentation in a centralized place
.. Place here references to all citations in lower case
.. _argparse: http://code.google.com/p/argparse/
.. _blitz++: http://www.oonumerics.org/blitz
.. _bob's idiap guide: http://github.com/idiap/bob/wiki/Using-Bob-at-Idiap
.. _bob's website: https://www.idiap.ch/software/bob
.. _boost: http://www.boost.org
.. _buildbot: http://trac.buildbot.net
.. _buildout: http://pypi.python.org/pypi/zc.buildout/
.. _c++: http://www2.research.att.com/~bs/C++.html
.. _cmake: http://www.cmake.org
.. _doxygen: http://www.doxygen.org
.. _dvipng: http://savannah.nongnu.org/projects/dvipng/
.. _ffmpeg: http://ffmpeg.org
.. _libav: http://libav.org
.. _fftw: http://www.fftw.org/
.. _fink: http://www.finkproject.org
.. _git: http://git-scm.com/
.. _github: http://github.com/
.. _google perftools: http://code.google.com/p/google-perftools
.. _hdf5: http://www.hdfgroup.org/HDF5
.. _idiap: http://www.idiap.ch
.. _ipython: http://ipython.scipy.org
.. _lapack: http://www.netlib.org/lapack
.. _latex: http://www.latex-project.org/
.. _libjpeg: http://libjpeg.sourceforge.net/
.. _libnetpbm: http://netpbm.sourceforge.net/doc/libnetpbm.html
.. _libpng: http://libpng.org/pub/png/libpng.html
.. _libsvm: http://www.csie.ntu.edu.tw/~cjlin/libsvm/
.. _libtiff: http://www.remotesensing.org/libtiff/
.. _giflib: http://giflib.sourceforge.net/
.. _macports installation instructions: http://www.macports.org/install.php
.. _macports: http://www.macports.org
.. _matio: http://matio.sourceforge.net
.. _matlab: http://www.mathworks.ch/products/matlab/
.. _matplotlib: http://matplotlib.sourceforge.net
.. _numpy: http://numpy.scipy.org
.. _nose: http://nose.readthedocs.org
.. _opencv: http://opencv.willowgarage.com/
.. _pil: http://www.pythonware.com/products/pil/
.. _pillow: https://pypi.python.org/pypi/Pillow/
.. _python: http://www.python.org
.. _pypi: http://pypi.python.org
.. _qt4: http://qt.nokia.com/
.. _satellite packages: https://github.com/idiap/bob/wiki/Satellite-Packages
.. _scipy: http://www.scipy.org
.. _setuptools: http://trac.edgewall.org/wiki/setuptools
.. _sphinx: http://sphinx.pocoo.org
.. _sqlalchemy: http://www.sqlalchemy.org/
.. _sqlite: http://www.sqlite.org/
.. _submit a new bug report: https://github.com/idiap/bob/issues
.. _torch 3 vision: http://torch3vision.idiap.ch
.. _torch 3: http://www.torch.ch
.. _torch 5: http://torch5.sourceforge.net
.. _torch: https://github.com/andresy/torch
.. _vlfeat launchpad webpage: https://launchpad.net/~gezakovacs/+archive/vlfeat
.. _vlfeat: http://www.vlfeat.org/
.. Place here references to licenses
.. _apache-2.0: http://www.opensource.org/licenses/Apache-2.0
.. _artistic-2.0: http://www.opensource.org/licenses/Artistic-2.0
.. _bsd-2-clause: http://www.opensource.org/licenses/BSD-2-Clause
.. _bsd-3-clause: http://www.opensource.org/licenses/BSD-3-Clause
.. _bsl-1.0: http://www.opensource.org/licenses/BSL-1.0
.. _gpl-2.0: http://www.opensource.org/licenses/GPL-2.0
.. _gpl-3.0: http://www.opensource.org/licenses/GPL-3.0
.. _hdf5 license: ftp://ftp.hdfgroup.org/HDF5/current/src/unpacked/COPYING
.. _lgpl-2.1: http://www.opensource.org/licenses/LGPL-2.1
.. _libpng license: http://www.libpng.org/pub/png/src/libpng-LICENSE.txt
.. _mit: http://www.opensource.org/licenses/MIT
.. _python-2.0: http://www.opensource.org/licenses/Python-2.0
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.dos.anjos@gmail.com>
.. Sat 16 Nov 20:52:58 2013
============
Python API
============
This section includes information for using the pure Python API of ``xbob.io``.
Classes
-------
.. autoclass:: xbob.io.File
.. autoclass:: xbob.io.HDF5File
.. autoclass:: xbob.io.VideoReader
.. autoclass:: xbob.io.VideoWriter
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
This diff is collapsed.
setup.py 0 → 100644
#!/usr/bin/env python
# vim: set fileencoding=utf-8 :
# Andre Anjos <andre.anjos@idiap.ch>
# Mon 16 Apr 08:18:08 2012 CEST
from setuptools import setup, find_packages, dist
dist.Distribution(dict(setup_requires=['xbob.blitz']))
from xbob.blitz.extension import Extension
import os
package_dir = os.path.dirname(os.path.realpath(__file__))
package_dir = os.path.join(package_dir, 'xbob', 'io', 'include')
include_dirs = [package_dir]
packages = ['bob-io >= 1.3']
version = '2.0.0a0'
define_macros = [("XBOB_IO_VERSION", '"%s"' % version)]
setup(
name='xbob.io',
version=version,
description='Bindings for bob.io',
url='http://github.com/anjos/xbob.io',
license='BSD',
author='Andre Anjos',
author_email='andre.anjos@idiap.ch',
long_description=open('README.rst').read(),
packages=find_packages(),
include_package_data=True,
install_requires=[
'setuptools',
'xbob.blitz',
],
namespace_packages=[
"xbob",
],
ext_modules = [
Extension("xbob.io._externals",
[
"xbob/io/externals.cpp",
],
packages = packages,
define_macros = define_macros,
include_dirs = include_dirs,
),
Extension("xbob.io._library",
[
"xbob/io/bobskin.cpp",
"xbob/io/file.cpp",
"xbob/io/videoreader.cpp",
"xbob/io/videowriter.cpp",
"xbob/io/hdf5.cpp",
"xbob/io/main.cpp",
],
packages = packages,
define_macros = define_macros,
include_dirs = include_dirs,
),
],
entry_points={
'console_scripts': [
'xbob_video_test.py = xbob.io.script.video_test:main',
],
},
classifiers = [
'Development Status :: 3 - Alpha',
'Intended Audience :: Developers',
'License :: OSI Approved :: BSD License',
'Natural Language :: English',
'Programming Language :: Python',
'Programming Language :: Python :: 3',
'Topic :: Software Development :: Libraries :: Python Modules',
],
)
Subproject commit 0c025f75ef8fc80c34ef0460febae775568450a1
#see http://peak.telecommunity.com/DevCenter/setuptools#namespace-packages
__import__('pkg_resources').declare_namespace(__name__)
from ._library import __version__, __api_version__
from . import plot
from . import load
from . import calibration
import numpy
def mse (estimation, target):
"""Calculates the mean square error between a set of outputs and target
values using the following formula:
.. math::
MSE(\hat{\Theta}) = E[(\hat{\Theta} - \Theta)^2]
Estimation (:math:`\hat{\Theta}`) and target (:math:`\Theta`) are supposed to
have 2 dimensions. Different examples are organized as rows while different
features in the estimated values or targets are organized as different
columns.
"""
return numpy.mean((estimation - target)**2, 0)
def rmse (estimation, target):
"""Calculates the root mean square error between a set of outputs and target
values using the following formula:
.. math::
RMSE(\hat{\Theta}) = \sqrt(E[(\hat{\Theta} - \Theta)^2])
Estimation (:math:`\hat{\Theta}`) and target (:math:`\Theta`) are supposed to
have 2 dimensions. Different examples are organized as rows while different
features in the estimated values or targets are organized as different
columns.
"""
return numpy.sqrt(mse(estimation, target))
def relevance (input, machine):
"""Calculates the relevance of every input feature to the estimation process
using the following definition from:
Neural Triggering System Operating on High Resolution Calorimetry
Information, Anjos et al, April 2006, Nuclear Instruments and Methods in
Physics Research, volume 559, pages 134-138
.. math::
R(x_{i}) = |E[(o(x) - o(x|x_{i}=E[x_{i}]))^2]|
In other words, the relevance of a certain input feature **i** is the change
on the machine output value when such feature is replaced by its mean for all
input vectors. For this to work, the `input` parameter has to be a 2D array
with features arranged column-wise while different examples are arranged
row-wise.
"""
o = machine(input)
i2 = input.copy()
retval = numpy.ndarray((input.shape[1],), 'float64')
retval.fill(0)
for k in range(input.shape[1]):
i2[:,:] = input #reset
i2[:,k] = numpy.mean(input[:,k])
retval[k] = (mse(machine(i2), o).sum())**0.5
return retval
def recognition_rate(cmc_scores):
"""Calculates the recognition rate from the given input, which is identical to the rank 1 (C)MC value.
The input has a specific format, which is a list of two-element tuples.
Each of the tuples contains the negative and the positive scores for one test item.
To read the lists from score files in 4 or 5 column format, please use the bob.measure.load.cmc_four_column or bob.measure.load.cmc_five_column function.
The recognition rate is defined as the number of test items,
for which the positive score is greater than or equal to all negative scores,
divided by the number of all test items.
If several positive scores for one test item exist, the *highest* score is taken.
"""
correct = 0.
for neg, pos in cmc_scores:
# get the maximum positive score for the current probe item
# (usually, there is only one positive score, but just in case...)
max_pos = numpy.max(pos)
# check if the positive score is smaller than all negative scores
if (neg <= max_pos).all():
correct += 1
# return relative number of
return correct / float(len(cmc_scores))
def cmc(cmc_scores):
"""Calculates the cumulative match characteristic (CMC) from the given input.
The input has a specific format, which is a list of two-element tuples.
Each of the tuples contains the negative and the positive scores for one test item.
To read the lists from score files in 4 or 5 column format, please use the bob.measure.load.cmc_four_column or bob.measure.load.cmc_five_column function.
For each test item the probability that the rank r of the positive score is calculated.
The rank is computed as the number of negative scores that are higher than the positive score.
If several positive scores for one test item exist, the *highest* positive score is taken.
The CMC finally computes, how many test items have rank r or higher.
"""
# compute MC
match_characteristic = numpy.zeros((max([len(neg) for (neg,pos) in cmc_scores])+1,), numpy.int)
for neg, pos in cmc_scores:
# get the maximum positive score for the current probe item
# (usually, there is only one positive score, but just in case...)
max_pos = numpy.max(pos)
# count the number of negative scores that are higher than the best positive score
index = numpy.sum(neg > max_pos)
match_characteristic[index] += 1
# cumulate
probe_count = float(len(cmc_scores))
cumulative_match_characteristic = numpy.ndarray(match_characteristic.shape, numpy.float64)
count = 0.
for i in range(match_characteristic.shape[0]):
count += match_characteristic[i]
cumulative_match_characteristic[i] = count / probe_count
return cumulative_match_characteristic
__all__ = [k for k in dir() if not k.startswith('_')]
if 'k' in locals(): del k
#!/usr/bin/env python
# vim: set fileencoding=utf-8 :
# @author: Manuel Guenther <Manuel.Guenther@idiap.ch>
# @date: Thu May 16 11:41:49 CEST 2013
#
# Copyright (C) 2011-2013 Idiap Research Institute, Martigny, Switzerland
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, version 3 of the License.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""Measures for calibration"""
import math
import numpy
from ..math import pavx
def cllr(negatives, positives):
"""Computes the 'cost of log likelihood ratio' measure as given in the bosaris toolkit"""
sum_pos, sum_neg = 0., 0.
for pos in positives:
sum_pos += math.log(1. + math.exp(-pos), 2.)
for neg in negatives:
sum_neg += math.log(1. + math.exp(neg), 2.)
return (sum_pos / len(positives) + sum_neg / len(negatives)) / 2.
def min_cllr(negatives, positives):
"""Computes the 'minimum cost of log likelihood ratio' measure as given in the bosaris toolkit"""
# first, sort both scores
neg = sorted(negatives)
pos = sorted(positives)
N = len(neg)
P = len(pos)
I = N+P
# now, iterate through both score sets and add a 0 for negative and 1 for positive scores
n, p = 0,0
ideal = numpy.zeros(I)
neg_indices = [0]*N
pos_indices = [0]*P
for i in range(I):
if p < P and (n == N or neg[n] > pos[p]):
pos_indices[p] = i
p += 1
ideal[i] = 1
else:
neg_indices[n] = i
n += 1
# compute the pool adjacent violaters method on the ideal LLR scores
popt = numpy.ndarray(ideal.shape, dtype=numpy.float)
pavx(ideal, popt)
# disable runtime warnings for a short time since log(0) will raise a warning
old_warn_setup = numpy.seterr(divide='ignore')
# ... compute logs
posterior_log_odds = numpy.log(popt)-numpy.log(1.-popt);
log_prior_odds = math.log(float(P)/float(N));
# ... activate old warnings
numpy.seterr(**old_warn_setup)
llrs = posterior_log_odds - log_prior_odds;
# some weired addition
# for i in range(I):
# llrs[i] += float(i)*1e-6/float(I)
# unmix positive and negative scores
new_neg = numpy.zeros(N)
for n in range(N):
new_neg[n] = llrs[neg_indices[n]]
new_pos = numpy.zeros(P)
for p in range(P):
new_pos[p] = llrs[pos_indices[p]]
# compute cllr of these new 'optimal' LLR scores
return cllr(new_neg, new_pos)
/**
* @author Andre Anjos <andre.anjos@idiap.ch>
* @date Tue 5 Nov 12:22:48 2013
*
* @brief C/C++ API for bob::io
*/
#ifndef XBOB_IO_H
#define XBOB_IO_H
#include <xbob.io/config.h>
#include <bob/config.h>
#include <bob/io/File.h>
#include <bob/io/HDF5File.h>
#if WITH_FFMPEG
#include <bob/io/VideoReader.h>
#include <bob/io/VideoWriter.h>
#endif /* WITH_FFMPEG */
#include <boost/preprocessor/stringize.hpp>
#include <boost/shared_ptr.hpp>
#include <Python.h>
#define XBOB_IO_MODULE_PREFIX xbob.io
#define XBOB_IO_MODULE_NAME _library
/*******************
* C API functions *
*******************/
/**************
* Versioning *
**************/
#define PyXbobIo_APIVersion_NUM 0
#define PyXbobIo_APIVersion_TYPE int
/*****************************
* Bindings for xbob.io.file *
*****************************/
/* Type definition for PyBobIoFileObject */
typedef struct {
PyObject_HEAD
/* Type-specific fields go here. */
boost::shared_ptr<bob::io::File> f;
} PyBobIoFileObject;
#define PyBobIoFile_Type_NUM 1
#define PyBobIoFile_Type_TYPE PyTypeObject
typedef struct {
PyObject_HEAD
/* Type-specific fields go here. */
PyBobIoFileObject* pyfile;
Py_ssize_t curpos;
} PyBobIoFileIteratorObject;
#define PyBobIoFileIterator_Type_NUM 2
#define PyBobIoFileIterator_Type_TYPE PyTypeObject
/************************
* I/O generic bindings *
************************/
#define PyBobIo_AsTypenum_NUM 3
#define PyBobIo_AsTypenum_RET int
#define PyBobIo_AsTypenum_PROTO (bob::core::array::ElementType et)
#define PyBobIo_TypeInfoAsTuple_NUM 4
#define PyBobIo_TypeInfoAsTuple_RET PyObject*
#define PyBobIo_TypeInfoAsTuple_PROTO (const bob::core::array::typeinfo& ti)
#if WITH_FFMPEG
/******************
* Video bindings *
******************/
typedef struct {
PyObject_HEAD
/* Type-specific fields go here. */
boost::shared_ptr<bob::io::VideoReader> v;
} PyBobIoVideoReaderObject;
#define PyBobIoVideoReader_Type_NUM 5
#define PyBobIoVideoReader_Type_TYPE PyTypeObject
typedef struct {
PyObject_HEAD
/* Type-specific fields go here. */
PyBobIoVideoReaderObject* pyreader;
boost::shared_ptr<bob::io::VideoReader::const_iterator> iter;
} PyBobIoVideoReaderIteratorObject;
#define PyBobIoVideoReaderIterator_Type_NUM 5
#define PyBobIoVideoReaderIterator_Type_TYPE PyTypeObject
typedef struct {
PyObject_HEAD
/* Type-specific fields go here. */
boost::shared_ptr<bob::io::VideoWriter> v;
} PyBobIoVideoWriterObject;
#define PyBobIoVideoWriter_Type_NUM 6
#define PyBobIoVideoWriter_Type_TYPE PyTypeObject
#endif /* WITH_FFMPEG */
/*****************
* HDF5 bindings *
*****************/
typedef struct {
PyObject_HEAD
/* Type-specific fields go here. */
boost::shared_ptr<bob::io::HDF5File> f;
} PyBobIoHDF5FileObject;
#define PyBobIoHDF5File_Type_NUM 7
#define PyBobIoHDF5File_Type_TYPE PyTypeObject
#define PyBobIoHDF5File_Check_NUM 8
#define PyBobIoHDF5File_Check_RET int
#define PyBobIoHDF5File_Check_PROTO (PyObject* o)
#define PyBobIoHDF5File_Converter_NUM 9
#define PyBobIoHDF5File_Converter_RET int
#define PyBobIoHDF5File_Converter_PROTO (PyObject* o, PyBobIoHDF5FileObject** a)
/* Total number of C API pointers */
#if WITH_FFMPEG
# define PyXbobIo_API_pointers 10
#else
# define PyXbobIo_API_pointers 11
#endif /* WITH_FFMPEG */
#ifdef XBOB_IO_MODULE
/* This section is used when compiling `xbob.core.random' itself */
/**************
* Versioning *
**************/
extern int PyXbobIo_APIVersion;
/*****************************
* Bindings for xbob.io.file *
*****************************/
extern PyBobIoFile_Type_TYPE PyBobIoFile_Type;
extern PyBobIoFileIterator_Type_TYPE PyBobIoFileIterator_Type;
/************************
* I/O generic bindings *
************************/
PyBobIo_AsTypenum_RET PyBobIo_AsTypenum PyBobIo_AsTypenum_PROTO;
PyBobIo_TypeInfoAsTuple_RET PyBobIo_TypeInfoAsTuple PyBobIo_TypeInfoAsTuple_PROTO;
#if WITH_FFMPEG
/******************
* Video bindings *
******************/
extern PyBobIoVideoReader_Type_TYPE PyBobIoVideoReader_Type;
extern PyBobIoVideoReaderIterator_Type_TYPE PyBobIoVideoReaderIterator_Type;
extern PyBobIoVideoWriter_Type_TYPE PyBobIoVideoWriter_Type;
#endif /* WITH_FFMPEG */
/*****************
* HDF5 bindings *
*****************/
extern PyBobIoHDF5File_Type_TYPE PyBobIoHDF5File_Type;
PyBobIoHDF5File_Check_RET PyBobIoHDF5File_Check PyBobIoHDF5File_Check_PROTO;
PyBobIoHDF5File_Converter_RET PyBobIoHDF5File_Converter PyBobIoHDF5File_Converter_PROTO;
#else
/* This section is used in modules that use `blitz.array's' C-API */
/************************************************************************
* Macros to avoid symbol collision and allow for separate compilation. *
* We pig-back on symbols already defined for NumPy and apply the same *
* set of rules here, creating our own API symbol names. *
************************************************************************/
# if defined(PY_ARRAY_UNIQUE_SYMBOL)
# define XBOB_IO_MAKE_API_NAME_INNER(a) XBOB_IO_ ## a
# define XBOB_IO_MAKE_API_NAME(a) XBOB_IO_MAKE_API_NAME_INNER(a)
# define PyXbobIo_API XBOB_IO_MAKE_API_NAME(PY_ARRAY_UNIQUE_SYMBOL)
# endif
# if defined(NO_IMPORT_ARRAY)
extern void **PyXbobIo_API;
# else
# if defined(PY_ARRAY_UNIQUE_SYMBOL)
void **PyXbobIo_API;
# else
static void **PyXbobIo_API=NULL;
# endif
# endif
static void **PyXbobIo_API;
/**************
* Versioning *
**************/
# define PyXbobIo_APIVersion (*(PyXbobIo_APIVersion_TYPE *)PyXbobIo_API[PyXbobIo_APIVersion_NUM])
/*****************************
* Bindings for xbob.io.file *
*****************************/
# define PyBobIoFile_Type (*(PyBobIoFile_Type_TYPE *)PyXbobIo_API[PyBobIoFile_Type_NUM])
# define PyBobIoFileIterator_Type (*(PyBobIoFileIterator_Type_TYPE *)PyXbobIo_API[PyBobIoFileIterator_Type_NUM])
/************************
* I/O generic bindings *
************************/
# define PyBobIo_AsTypenum (*(PyBobIo_AsTypenum_RET (*)PyBobIo_AsTypenum_PROTO) PyXbobIo_API[PyBobIo_AsTypenum_NUM])
# define PyBobIo_TypeInfoAsTuple (*(PyBobIo_TypeInfoAsTuple_RET (*)PyBobIo_TypeInfoAsTuple_PROTO) PyXbobIo_API[PyBobIo_TypeInfoAsTuple_NUM])
#if WITH_FFMPEG
/******************
* Video bindings *
******************/
# define PyBobIoVideoReader_Type (*(PyBobIoVideoReader_Type_TYPE *)PyXbobIo_API[PyBobIoVideoReader_Type_NUM])
# define PyBobIoVideoReaderIterator_Type (*(PyBobIoVideoReaderIterator_Type_TYPE *)PyXbobIo_API[PyBobIoVideoReaderIterator_Type_NUM])
# define PyBobIoVideoWriterIterator_Type (*(PyBobIoVideoWriterIterator_Type_TYPE *)PyXbobIo_API[PyBobIoVideoWriterIterator_Type_NUM])
#endif /* WITH_FFMPEG */
/*****************
* HDF5 bindings *
*****************/
# define PyBobIoHDF5File_Type (*(PyBobIoHDF5File_Type_TYPE *)PyXbobIo_API[PyBobIoHDF5File_Type_NUM])
# define PyBobIoHDF5File_Check (*(PyBobIoHDF5File_Check_RET (*)PyBobIoHDF5File_Check_PROTO) PyXbobIo_API[PyBobIoHDF5File_Check_NUM])
# define PyBobIoHDF5File_Converter (*(PyBobIoHDF5File_Converter_RET (*)PyBobIoHDF5File_Converter_PROTO) PyXbobIo_API[PyBobIoHDF5File_Converter_NUM])
# if !defined(NO_IMPORT_ARRAY)
/**
* Returns -1 on error, 0 on success. PyCapsule_Import will set an exception
* if there's an error.
*/
static int import_xbob_io(void) {
PyObject *c_api_object;
PyObject *module;
module = PyImport_ImportModule(BOOST_PP_STRINGIZE(XBOB_IO_MODULE_PREFIX) "." BOOST_PP_STRINGIZE(XBOB_IO_MODULE_NAME));
if (module == NULL) return -1;
c_api_object = PyObject_GetAttrString(module, "_C_API");
if (c_api_object == NULL) {
Py_DECREF(module);
return -1;
}
# if PY_VERSION_HEX >= 0x02070000
if (PyCapsule_CheckExact(c_api_object)) {
PyXbobIo_API = (void **)PyCapsule_GetPointer(c_api_object,
PyCapsule_GetName(c_api_object));
}
# else
if (PyCObject_Check(c_api_object)) {
XbobIo_API = (void **)PyCObject_AsVoidPtr(c_api_object);
}
# endif
Py_DECREF(c_api_object);
Py_DECREF(module);
if (!XbobIo_API) {
PyErr_Format(PyExc_ImportError,
# if PY_VERSION_HEX >= 0x02070000
"cannot find C/C++ API capsule at `%s.%s._C_API'",
# else
"cannot find C/C++ API cobject at `%s.%s._C_API'",
# endif
BOOST_PP_STRINGIZE(XBOB_IO_MODULE_PREFIX),
BOOST_PP_STRINGIZE(XBOB_IO_MODULE_NAME));
return -1;
}
/* Checks that the imported version matches the compiled version */
int imported_version = *(int*)PyXbobIo_API[PyIo_APIVersion_NUM];
if (XBOB_IO_API_VERSION != imported_version) {
PyErr_Format(PyExc_ImportError, "%s.%s import error: you compiled against API version 0x%04x, but are now importing an API with version 0x%04x which is not compatible - check your Python runtime environment for errors", BOOST_PP_STRINGIZE(XBOB_IO_MODULE_PREFIX), BOOST_PP_STRINGIZE(XBOB_IO_MODULE_NAME), XBOB_IO_API_VERSION, imported_version);
return -1;
}
/* If you get to this point, all is good */
return 0;
}
# endif //!defined(NO_IMPORT_ARRAY)
#endif /* XBOB_IO_MODULE */
#endif /* XBOB_IO_H */
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment