Commit f1249e98 authored by Manuel Günther's avatar Manuel Günther

New README and documentation strategy; changed purpose 'enrol' to 'enroll'

parent 623deef8
......@@ -6,6 +6,7 @@ matrix:
- secure: gGugdsOA/a9BEl/gD3d7Tx6aO4HIXkWPZ8FTH8tB8GyAJZoc3RBcjWzkzKcQzBSSGGYtb0NpVyBrTY8ZI8cyP3uiMF1TsTcezVqv46Lo0pgAq907eBdAzE2e8daMTHtu/BdNx/swTHeKh6CnwjbhtCfmj/Xc2NqJkZvRzl7ORJw=
- secure: Zvra/7t33S8E4SF6tGzEt99F0Jz4Os/3tOso0jS+CXCxIpE0EmHadFxXIXje7tDRlSSnV4dxhTaICiAzbwQsxbZMkKjhc75OU/C+mpHCbJpzxcTm/L8Dj9mPMzlWjqjaREFnUGThr2biERkFUrinHSSQm8h7bizH4qltMhRXYTQ=
- python: 3.2
- NUMPYSPEC===1.8.0
......@@ -15,7 +16,7 @@ matrix:
- sudo add-apt-repository -y ppa:biometrics/bob
- sudo apt-get update -qq
- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libhdf5-serial-dev libatlas-dev libatlas-base-dev liblapack-dev
- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libhdf5-serial-dev libatlas-dev libatlas-base-dev liblapack-dev texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
- if [ -n "${NUMPYSPEC}" ]; then sudo apt-get install -qq gfortran; fi
- if [ -n "${NUMPYSPEC}" ]; then pip install --upgrade pip setuptools; fi
- if [ -n "${NUMPYSPEC}" ]; then pip install --find-links --find-links --use-wheel numpy$NUMPYSPEC ; fi
.. vim: set fileencoding=utf-8 :
.. Manuel Guenther <>
.. Thu Sep 4 11:35:05 CEST 2014
.. Fri Oct 31 14:18:57 CET 2014
.. image::
.. image::
.. image::
.. image::
.. image::
.. image::
.. image::
.. image::
.. image::
Biosecure Database
BioSecure Database Interface for Bob
This package contains the access API and descriptions for the `Biosecure
Database <>`_.
The actual raw data for the database should be downloaded from the original URL.
This package only contains the `Bob <>`_
accessor methods to use the DB directly from python, with our certified protocols.
This package contains an interface for the evaluation protocol of the BioSecure_ database, particularly for the images from the BioSecure_ database.
This package does not contain the original BioSecure_ data files, which need to be obtained through the link above.
You would normally not install this package unless you are maintaining it. What
you would do instead is to tie it in at the package you need to **use** it.
There are a few ways to achieve this:
1. You can add this package as a requirement at the ```` for your own
`satellite package
or to your Buildout ``.cfg`` file, if you prefer it that way. With this
method, this package gets automatically downloaded and installed on your
working environment, or
To install this package -- alone or together with other `Packages of Bob <>`_ -- please read the `Installation Instructions <>`_.
For Bob_ to be able to work properly, some dependent packages are required to be installed.
Please make sure that you have read the `Dependencies <>`_ for your operating system.
2. You can manually download and install this package using commands like
``easy_install`` or ``pip``.
For further documentation on this package, please read the `Stable Version <>`_ or the `Latest Version <>`_ of the documentation.
For a list of tutorials on this or the other packages ob Bob_, or information on submitting issues, asking questions and starting discussions, please visit its website.
The package is available in two different distribution formats:
.. _bob:
.. _biosecure:
1. You can download it from `PyPI <>`_, or
2. You can download it in its source form from `its git repository
<>`_. When you download the
version at the git repository, you will need to run a command to recreate
the backend SQLite file required for its operation. This means that the
database raw files must be installed somewhere in this case. With option
``a`` you can run in `dummy` mode and only download the raw data files for
the database once you are happy with your setup.
You can mix and match points 1/2 and a/b above based on your requirements. Here
are some examples:
Modify your and download from PyPI
That is the easiest. Edit your ```` in your satellite package and add
the following entry in the ``install_requires`` section (note: ``...`` means
`whatever extra stuff you may have in-between`, don't put that on your
Proceed normally with your ``boostrap/buildout`` steps and you should be all
set. That means you can now import the ``bob.db.biosecure`` namespace into your scripts.
Modify your buildout.cfg and download from git
You will need to add a dependence to `mr.developer
<>`_ to be able to install from our
git repositories. Your ``buildout.cfg`` file should contain the following
extensions = mr.developer
auto-checkout = *
eggs = bob
bob.db.biosecure = git
......@@ -20,7 +20,7 @@
from .query import Database
from .models import Client, File, Protocol, ProtocolPurpose
from .models import Client, File, Protocol, ProtocolPurpose, Annotation
def get_config():
"""Returns a string containing the configuration information.
......@@ -119,22 +119,22 @@ def add_protocols(session, verbose):
protocol_definitions = {}
# Protocol ca0
enrol = [1, 2]
enroll = [1, 2]
probe = [1, 2]
protocol_definitions['ca0'] = [enrol, probe]
protocol_definitions['ca0'] = [enroll, probe]
# Protocol caf
enrol = [1, 2]
enroll = [1, 2]
probe = [1, 2]
protocol_definitions['caf'] = [enrol, probe]
protocol_definitions['caf'] = [enroll, probe]
# Protocol wc
enrol = [1, 2]
enroll = [1, 2]
probe = [1, 2]
protocol_definitions['wc'] = [enrol, probe]
protocol_definitions['wc'] = [enroll, probe]
protocolPurpose_list = [('world', 'train'), ('dev', 'enrol'), ('dev', 'probe'), ('eval', 'enrol'), ('eval', 'probe')]
protocolPurpose_list = [('world', 'train'), ('dev', 'enroll'), ('dev', 'probe'), ('eval', 'enroll'), ('eval', 'probe')]
for proto in protocol_definitions:
p = Protocol(proto)
# Add protocol
......@@ -144,7 +144,7 @@ class ProtocolPurpose(Base):
group_choices = ('world', 'dev', 'eval')
sgroup = Column(Enum(*group_choices))
# Purpose associated with this protocol purpose object
purpose_choices = ('train', 'enrol', 'probe')
purpose_choices = ('train', 'enroll', 'probe')
purpose = Column(Enum(*purpose_choices))
# For Python: A direct link to the Protocol object that this ProtocolPurpose belongs to
......@@ -132,7 +132,7 @@ class Database(bob.db.verification.utils.SQLiteDatabase):
One of the Biosecure protocols ('ca0', 'caf', 'wc').
The purposes required to be retrieved ('enrol', 'probe', 'train') or a tuple
The purposes required to be retrieved ('enroll', 'probe', 'train') or a tuple
with several of them. If 'None' is given (this is the default), it is
considered the same as a tuple with all possible values. This field is
ignored for the data from the "world" group.
......@@ -177,9 +177,9 @@ class Database(bob.db.verification.utils.SQLiteDatabase):
retval += list(q)
if ('dev' in groups or 'eval' in groups):
if('enrol' in purposes):
if('enroll' in purposes):
q = self.query(File).join(Client).join((ProtocolPurpose, File.protocolPurposes)).join(Protocol).\
filter(and_(, ProtocolPurpose.sgroup.in_(groups), ProtocolPurpose.purpose == 'enrol'))
filter(and_(, ProtocolPurpose.sgroup.in_(groups), ProtocolPurpose.purpose == 'enroll'))
if model_ids:
q = q.filter(
q = q.order_by(File.client_id,, File.session_id, File.shot_id)
......@@ -80,7 +80,7 @@ def test_driver_api():
from bob.db.base.script.dbmanage import main
assert main('biosecure dumplist --self-test'.split()) == 0
assert main('biosecure dumplist --protocol=ca0 --class=client --group=dev --purpose=enrol --client=141 --self-test'.split()) == 0
assert main('biosecure dumplist --protocol=ca0 --class=client --group=dev --purpose=enroll --client=141 --self-test'.split()) == 0
assert main('biosecure checkfiles --self-test'.split()) == 0
assert main('biosecure reverse ca0/u141_s02_face_ds2-ca-0i_02 --self-test'.split()) == 0
assert main('biosecure path 748 --self-test'.split()) == 0
......@@ -3,21 +3,13 @@
# Andre Anjos <>
# Mon 13 Aug 2012 12:38:15 CEST
# Copyright (C) 2011-2012 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
# 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 <>.
# Copyright (C) 2011-2014 Idiap Research Institute, Martigny, Switzerland
import os
import sys
import glob
import pkg_resources
import sys, os
# 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
......@@ -71,15 +63,17 @@ project = u'Biosecure Database (Bob API)'
import time
copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
# Grab the setup entry
distribution = pkg_resources.require('bob.db.biosecure')[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.
from bob.db.biosecure.driver import Interface
version = Interface().version()
version = distribution.version
# The full version, including alpha/beta/rc tags.
release = version
release = distribution.version
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......@@ -140,12 +134,12 @@ if sphinx.__version__ >= "1.0":
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = ''
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 = ''
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,
......@@ -194,7 +188,7 @@ html_favicon = ''
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'bobdbdoc'
htmlhelp_basename = 'bob_db_biosecure_doc'
# -- Options for LaTeX output --------------------------------------------------
......@@ -208,7 +202,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', 'bobdbman.tex', u'Bob',
('index', 'bob_db_biosecure.tex', u'Bob',
u'Biometrics Group, Idiap Research Institute', 'manual'),
......@@ -246,40 +240,15 @@ man_pages = [
('index', 'bob', u'Biosecure Database (Bob API) Documentation', [u'Idiap Research Institute'], 1)
# We want to remove all private (i.e. _. or __.__) members
# that are not in the list of accepted functions
accepted_private_functions = ['__call__']
def member_function_test(app, what, name, obj, skip, options):
# test if we have a private function
if len(name) > 1 and name[0] == '_':
# test if this private function should be allowed
if name not in accepted_private_functions:
# omit privat functions that are not in the list of accepted private functions
return True
# test if the method is documented
if not hasattr(obj, '__doc__') or not obj.__doc__:
return True
# Skips selected members in auto-generated documentation. Unfortunately, old
# versions of Boost.Python will not generate a __self__ member for static
# methods and that screws-up Sphinx processing.
if sphinx.__version__ < "1.0":
# We have to remove objects that do not have a __self__ attribute set
import types
if isinstance(obj, types.BuiltinFunctionType) and \
not hasattr(obj, '__self__') and what == 'class':
app.warn("Skipping %s %s (no __self__)" % (what, name))
return True
return False
# Default processing flags for sphinx
autoclass_content = 'both'
autodoc_member_order = 'bysource'
autodoc_default_flags = ['members', 'undoc-members', 'special-members', 'inherited-members', 'show-inheritance']
autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-inheritance']
# For inter-documentation mapping:
from bob.extension.utils import link_documentation
intersphinx_mapping = link_documentation(['python', 'bob.db.base', 'bob.db.verification.utils'])
def setup(app):
app.connect('autodoc-skip-member', member_function_test)
.. vim: set fileencoding=utf-8 :
.. @author: Manuel Guenther <>
.. @date: Thu Dec 6 12:28:25 CET 2012
.. @date: Fri Oct 31 16:01:33 CET 2014
User's Guide
This package contains the access API and descriptions for the BioSecure_ database.
The actual raw data for the database should be downloaded from the original URL.
This API is only compatible with the DS2 Still face image part of the BioSecure_ database.
This package only contains the Bob_ accessor methods to use the DB directly from python.
The Database Interface
The :py:class:`bob.db.biosecure.Database` complies with the standard biometric verification database as described in :ref:`commons`, implementing the interface :py:class:`bob.db.verification.utils.SQLiteDatabase`.
.. todo::
Write users guide.
Explain the particularities of the :py:class:`bob.db.biosecure.Database` database.
.. _biosecure:
.. _bob:
......@@ -56,6 +56,7 @@ setup(
classifiers = [
'Framework :: Bob',
'Development Status :: 4 - Beta',
'Environment :: Console',
'Intended Audience :: Developers',
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