Commit 0800abba authored by Manuel Günther's avatar Manuel Günther
Browse files

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

parent c889bbb5
*~
*.swp
*.pyc
*.so
*.dylib
bin
eggs
parts
.installed.cfg
.mr.developer.cfg
*.egg-info
src
develop-eggs
built-docs
dist
sphinx
dist
.nfs*
.gdb_history
build
*.egg
src/
db.sql3
......@@ -6,6 +6,7 @@ matrix:
env:
- secure: OLw0gO15qHoP/tfxUMZ6XwNVsJ3uJ+c+I88h19ndEGqhqDKEDcI+trBPf5oqk781J7LfA62qBOYiraeEukVaNiWFOU0L2NmDI+KhaREb2kEezQ+9ydinq7DjCl81TiwGtH9s81NmPIiEx3CCZUlet4jDD2SjiZ600jIL2TS3BY4=
- secure: N2K8fksR1pxN71AgLOK5I4/1AgkuM+CNmlcrS5qmCy07W+QmT0SaSALb8ilU2QtZUrC4MQh1OvcoNuY41DtnsR4K0hMn9HVW8E9wfxHE4RAgYNxXg2lY2JYdhCFgGSSaL+JLrL33M9krbrdAZe6L+4PE47D9tys5N0Mrx5sx48Y=
- BOB_DOCUMENTATION_SERVER=https://www.idiap.ch/software/bob/docs/latest/bioidiap/%s/master
- python: 3.2
env:
- NUMPYSPEC===1.8.0
......@@ -15,7 +16,7 @@ matrix:
before_install:
- 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 http://wheels.astropy.org/ --find-links http://wheels2.astropy.org/ --use-wheel numpy$NUMPYSPEC; fi
......
================
BANCA Database
================
This package contains the access API and descriptions for the `BANCA English
Database <http://www.ee.surrey.ac.uk/CVSSP/banca/>`_. The actual raw data for
the database should be downloaded from the original URL. This API is only
compatible with the images from the BANCA English database. This package only
contains the `Bob <http://www.idiap.ch/software/bob/>`_ accessor methods to use
the DB directly from python, with our certified protocols.
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 ``setup.py`` for your own
`satellite package
<https://github.com/idiap/bob/wiki/Virtual-Work-Environments-with-Buildout>`_
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
2. You can manually download and install this package using commands like
``easy_install`` or ``pip``.
The package is available in two different distribution formats:
1. You can download it from `PyPI <http://pypi.python.org/pypi>`_, or
2. You can download it in its source form from `its git repository
<https://github.com/bioidiap/bob.db.banca>`_. 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 setup.py and download from PyPI
===========================================
That is the easiest. Edit your ``setup.py`` 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
script)::
install_requires=[
...
"bob.db.banca",
],
Proceed normally with your ``boostrap/buildout`` steps and you should be all
set. That means you can now import the ``bob.db.banca`` namespace into your scripts.
Modify your buildout.cfg and download from git
==============================================
You will need to add a dependence to `mr.developer
<http://pypi.python.org/pypi/mr.developer/>`_ to be able to install from our
git repositories. Your ``buildout.cfg`` file should contain the following
lines::
[buildout]
...
extensions = mr.developer
auto-checkout = *
eggs = bob
...
bob.db.banca
[sources]
bob.db.banca = git https://github.com/bioidiap/bob.db.banca.git
...
.. vim: set fileencoding=utf-8 :
.. Manuel Guenther <manuel.guenther@idiap.ch>
.. Fri Oct 31 14:18:57 CET 2014
.. image:: http://img.shields.io/badge/docs-stable-yellow.png
:target: http://pythonhosted.org/bob.db.banca/index.html
.. image:: http://img.shields.io/badge/docs-latest-orange.png
:target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.db.banca/master/index.html
.. image:: https://travis-ci.org/bioidiap/bob.db.banca.svg?branch=master
:target: https://travis-ci.org/bioidiap/bob.db.banca
.. image:: https://coveralls.io/repos/bioidiap/bob.db.banca/badge.png
:target: https://coveralls.io/r/bioidiap/bob.db.banca
.. image:: https://img.shields.io/badge/github-master-0000c0.png
:target: https://github.com/bioidiap/bob.db.banca/tree/master
.. image:: http://img.shields.io/pypi/v/bob.db.banca.png
:target: https://pypi.python.org/pypi/bob.db.banca
.. image:: http://img.shields.io/pypi/dm/bob.db.banca.png
:target: https://pypi.python.org/pypi/bob.db.banca
.. image:: https://img.shields.io/badge/original-data--files-a000a0.png
:target: http://www.ee.surrey.ac.uk/CVSSP/banca
==================================
BANCA Database Interface for Bob
==================================
This package contains an interface for the evaluation protocol of the BANCA_ database, particularly for the English protocol of BANCA_.
This package does not contain the original BANCA_ data files, which need to be obtained through the link above.
Installation
------------
To install this package -- alone or together with other `Packages of Bob <https://github.com/idiap/bob/wiki/Packages>`_ -- please read the `Installation Instructions <https://github.com/idiap/bob/wiki/Installation>`_.
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 <https://github.com/idiap/bob/wiki/Dependencies>`_ for your operating system.
Documentation
-------------
For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/bob.db.banca/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.db.banca/master/index.html>`_ 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.
.. _bob: https://www.idiap.ch/software/bob
.. _banca: http://www.ee.surrey.ac.uk/CVSSP/banca
......@@ -20,7 +20,7 @@
"""
from .query import Database
from .models import Client, Subworld, File, Protocol, ProtocolPurpose
from .models import Client, Subworld, File, Protocol, ProtocolPurpose, Annotation
def get_config():
"""Returns a string containing the configuration information.
......
......@@ -105,49 +105,49 @@ def add_protocols(session, verbose):
protocol_definitions = {}
# Protocol Mc
enrol = [1]
enroll = [1]
probe_c = [2, 3, 4]
probe_i = [1, 2, 3, 4]
protocol_definitions['Mc'] = [enrol, probe_c, probe_i]
protocol_definitions['Mc'] = [enroll, probe_c, probe_i]
# Protocol Md
enrol = [5]
enroll = [5]
probe_c = [6, 7, 8]
probe_i = [5, 6, 7, 8]
protocol_definitions['Md'] = [enrol, probe_c, probe_i]
protocol_definitions['Md'] = [enroll, probe_c, probe_i]
# Protocol Ma
enrol = [9]
enroll = [9]
probe_c = [10, 11, 12]
probe_i = [9, 10, 11, 12]
protocol_definitions['Ma'] = [enrol, probe_c, probe_i]
protocol_definitions['Ma'] = [enroll, probe_c, probe_i]
# Protocol Ud
enrol = [1]
enroll = [1]
probe_c = [6, 7, 8]
probe_i = [5, 6, 7, 8]
protocol_definitions['Ud'] = [enrol, probe_c, probe_i]
protocol_definitions['Ud'] = [enroll, probe_c, probe_i]
# Protocol Ua
enrol = [1]
enroll = [1]
probe_c = [10, 11, 12]
probe_i = [9, 10, 11, 12]
protocol_definitions['Ua'] = [enrol, probe_c, probe_i]
protocol_definitions['Ua'] = [enroll, probe_c, probe_i]
# Protocol P
enrol = [1]
enroll = [1]
probe_c = [2, 3, 4, 6, 7, 8, 10, 11, 12]
probe_i = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
protocol_definitions['P'] = [enrol, probe_c, probe_i]
protocol_definitions['P'] = [enroll, probe_c, probe_i]
# Protocol G
enrol = [1, 5, 9]
enroll = [1, 5, 9]
probe_c = [2, 3, 4, 6, 7, 8, 10, 11, 12]
probe_i = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
protocol_definitions['G'] = [enrol, probe_c, probe_i]
protocol_definitions['G'] = [enroll, probe_c, probe_i]
# 2. ADDITIONS TO THE SQL DATABASE
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
......@@ -181,7 +181,7 @@ def add_protocols(session, verbose):
session_list = protocol_definitions[proto][1]
session_list_i = protocol_definitions[proto][2]
# Adds 'regular' files (i.e. 'world', 'enrol', 'probe client')
# Adds 'regular' files (i.e. 'world', 'enroll', 'probe client')
if not session_list:
q = session.query(File).join(Client).filter(Client.sgroup == client_group).\
order_by(File.id)
......
......@@ -172,7 +172,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
......
......@@ -309,7 +309,7 @@ class Database(bob.db.verification.utils.SQLiteDatabase, bob.db.verification.uti
One of the BANCA protocols ('P', 'G', 'Mc', 'Md', 'Ma', 'Ud', 'Ua').
purposes
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.
......@@ -371,9 +371,9 @@ class Database(bob.db.verification.utils.SQLiteDatabase, bob.db.verification.uti
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_(Protocol.name.in_(protocol), ProtocolPurpose.sgroup.in_(groups), ProtocolPurpose.purpose == 'enrol'))
filter(and_(Protocol.name.in_(protocol), ProtocolPurpose.sgroup.in_(groups), ProtocolPurpose.purpose == 'enroll'))
if model_ids:
q = q.filter(Client.id.in_(model_ids))
q = q.order_by(File.client_id, File.session_id, File.claimed_id, File.shot_id)
......@@ -433,7 +433,7 @@ class Database(bob.db.verification.utils.SQLiteDatabase, bob.db.verification.uti
tgroups.append('eval')
if 'eval' in groups:
tgroups.append('dev')
return self.objects(protocol, 'enrol', model_ids, tgroups, 'client', languages)
return self.objects(protocol, 'enroll', model_ids, tgroups, 'client', languages)
def zobjects(self, protocol=None, model_ids=None, groups=None, languages=None):
"""Returns a set of Files to perform Z-norm score normalization.
......
......@@ -72,9 +72,9 @@ def test_objects():
for protocol in db.protocols():
# assure that the number of enroll files is independent from the protocol
for group in ('dev', 'eval'):
assert len(db.objects(groups=group, purposes='enrol')) == 390
assert len(db.objects(groups=group, purposes='enroll')) == 390
for model_id in db.model_ids(groups=group):
assert len(db.objects(groups=group, purposes='enrol', model_ids=model_id)) == 15
assert len(db.objects(groups=group, purposes='enroll', model_ids=model_id)) == 15
for model_id in db.tmodel_ids(groups=group):
assert len(db.tobjects(groups=group, model_ids=model_id)) == 15
......@@ -108,7 +108,7 @@ def test_driver_api():
# Tests the bob_dbmanage.py driver API
from bob.db.base.script.dbmanage import main
assert main('banca dumplist --self-test'.split()) == 0
assert main('banca dumplist --protocol=P --class=client --group=dev --purpose=enrol --model-id=1008 --self-test'.split()) == 0
assert main('banca dumplist --protocol=P --class=client --group=dev --purpose=enroll --model-id=1008 --self-test'.split()) == 0
assert main('banca checkfiles --self-test'.split()) == 0
assert main('banca reverse 05/1021_f_g2_s05_1026_en_3 --self-test'.split()) == 0
assert main('banca path 2327 --self-test'.split()) == 0
......
......@@ -3,21 +3,13 @@
# Andre Anjos <andre.anjos@idiap.ch>
# 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
# 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/>.
# 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'BANCA Database (Bob API)'
import time
copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
# Grab the setup entry
distribution = pkg_resources.require('bob.db.banca')[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.banca.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,
......@@ -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_banca.tex', u'Bob',
u'Biometrics Group, Idiap Research Institute', 'manual'),
]
......@@ -246,40 +240,15 @@ man_pages = [
('index', 'bob', u'BANCA (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
else:
# 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)
pass
......@@ -6,5 +6,26 @@
User's Guide
==============
This package contains the access API and descriptions for the BANCA_ English Database.
The actual raw data for the database should be downloaded from the original URL.
This API is only compatible with the images from the BANCA English database.
This package only contains the Bob_ accessor methods to use the DB directly from python, with our certified protocols.
The BANCA_ database interface provides several face verification protocols, i.e., ``'P'``, ``'G'``, ``'Mc'``, ``'Md'``, ``'Ma'``, ``'Ud'``, ``'Ua'``.
These protocols are defined in detail in [Bail2003]_.
.. [Bail2003] **Enrique Bailly-Bailliére and others**. *The BANCA Database and Evaluation Protocol*, Lecture Notes in Computer Science Vol. 2688, pages 625-638, 2003.
The Database Interface
----------------------
The BANCA database complies with the standard biometric verification database as described in :ref:`commons`, implementing both interfaces :py:class:`bob.db.verification.utils.ZTDatabase` and :py:class:`bob.db.verification.utils.SQLiteDatabase`.
.. todo::
Write users guide.
Explain the particularities of the BANCA_ database.
.. _banca: http://www.ee.surrey.ac.uk/CVSSP/banca
.. _bob: https://www.idiap.ch/software/bob
......@@ -2,8 +2,8 @@
.. Laurent El Shafey <laurent.el-shafey@idiap.ch>
.. Tue 28 Aug 2012 18:09:40 CEST
================
BANCA Database
================
============
Python API
============
.. automodule:: bob.db.banca
......@@ -63,6 +63,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