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

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

parent 6253c70a
*~
*.swp
*.pyc
*.so
*.dylib
bin
eggs
parts
.installed.cfg
.mr.developer.cfg
*.egg-info
src
develop-eggs
dist
sphinx
dist
.nfs*
.gdb_history
build
*.egg
src/
......@@ -6,6 +6,7 @@ matrix:
env:
- secure: IsIuB+1cKlkdqXxNmAGp/me3JrYcuTzrZVcP2x9XWsJR43AW7jlPet9fB1lsU6pzfymCww3eody+J4ZiTcKWjL91BLHLNbBcny6EdzwZzdt26sH7moF53WEe678bwcmrkBEDbbaTODPKJDKFNHWy2QjBd46KzFBsvUBMzPL8skA=
- secure: RyfuwYiUnkICmUMqV/oV1X0rckwa3FHxwt2zCf/uDPzQitccXf64byZp+yh6Va1epIc4pLXZ4nI2UBg2P222Q7xjOciXJShQZAXANeajhIfoLdC/mM/TvwJLOqviFrSh2fJlnuj1/Rwya3yhW0fkDlwJjyoc7vrJthIy1wgRExo=
- 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 matplotlib==1.3.0 sphinx nose==1.3.0; fi
......
===================
ATNT/ORL Database
===================
.. 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.atnt/index.html
.. image:: http://img.shields.io/badge/docs-latest-orange.png
:target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.db.atnt/master/index.html
.. image:: https://travis-ci.org/bioidiap/bob.db.atnt.svg?branch=master
:target: https://travis-ci.org/bioidiap/bob.db.atnt
.. image:: https://coveralls.io/repos/bioidiap/bob.db.atnt/badge.png
:target: https://coveralls.io/r/bioidiap/bob.db.atnt
.. image:: https://img.shields.io/badge/github-master-0000c0.png
:target: https://github.com/bioidiap/bob.db.atnt/tree/master
.. image:: http://img.shields.io/pypi/v/bob.db.atnt.png
:target: https://pypi.python.org/pypi/bob.db.atnt
.. image:: http://img.shields.io/pypi/dm/bob.db.atnt.png
:target: https://pypi.python.org/pypi/bob.db.atnt
.. image:: https://img.shields.io/badge/original-data--files-a000a0.png
:target: http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html
=================================
AT&T Database Interface for Bob
=================================
This package contains an interface for the evaluation protocol of the `AT&T`_ database, formerly known as the ORL database of faces.
This package does not contain the original `AT&T`_ 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.atnt/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.db.atnt/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
.. _at&t: http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html
The ATNT/ORL database is a database of faces.
The actual raw data for the database should be downloaded from the original
URL. 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.atnt>`_. 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.atnt",
],
Proceed normally with your ``boostrap/buildout`` steps and you should be all
set. That means you can now import the namespace ``bob.db.atnt`` 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.atnt
[sources]
bob.db.atnt = git https://github.com/bioidiap/bob.db.atnt.git
...
......@@ -43,9 +43,9 @@ class Database(bob.db.verification.utils.Database):
bob.db.verification.utils.Database.__init__(self, original_directory=original_directory, original_extension=original_extension)
# initialize members
self.m_groups = ('world', 'dev')
self.m_purposes = ('enrol', 'probe')
self.m_purposes = ('enroll', 'probe')
self.m_training_clients = set([1,2,5,6,10,11,12,14,16,17,20,21,24,26,27,29,33,34,36,39])
self.m_enrol_files = set([2,4,5,7,9])
self.m_enroll_files = set([2,4,5,7,9])
def groups(self, protocol = None):
"""Returns the names of all registered groups
......@@ -179,7 +179,7 @@ class Database(bob.db.verification.utils.Database):
One of the groups 'world' or 'dev' or a list with both of them (which is the default).
purposes : str or [str]
One of the purposes 'enrol' or 'probe' or a list with both of them (which is the default).
One of the purposes 'enroll' or 'probe' or a list with both of them (which is the default).
This field is ignored when the group 'world' is selected.
protocol
......@@ -211,13 +211,13 @@ class Database(bob.db.verification.utils.Database):
# go through the dataset and collect all desired files
retval = []
if 'enrol' in purposes:
if 'enroll' in purposes:
for client_id in ids:
for file_id in self.m_enrol_files:
for file_id in self.m_enroll_files:
retval.append(File(client_id, file_id))
if 'probe' in purposes:
file_ids = File.m_valid_file_ids - self.m_enrol_files
file_ids = File.m_valid_file_ids - self.m_enroll_files
# for probe, we use all clients of the given groups
for client_id in self.client_ids(groups):
for file_id in file_ids:
......
......@@ -41,8 +41,8 @@ class ATNTDatabaseTest(unittest.TestCase):
f = db.objects(groups='dev')
self.assertEqual(len(f), 200) # number of all test files
f = db.objects(groups='dev', purposes = 'enrol')
self.assertEqual(len(f), 100) # number of enrol files
f = db.objects(groups='dev', purposes = 'enroll')
self.assertEqual(len(f), 100) # number of enroll files
f = db.objects(groups='dev', purposes = 'probe')
self.assertEqual(len(f), 100) # number of probe files
......@@ -56,11 +56,11 @@ class ATNTDatabaseTest(unittest.TestCase):
f = db.clients(groups = 'dev')
self.assertEqual(len(f), 20) # number of test clients
f = db.objects(groups = 'dev', purposes = 'enrol', model_ids = [3])
f = db.objects(groups = 'dev', purposes = 'enroll', model_ids = [3])
self.assertEqual(len(f), 5)
files = sorted(f, key=lambda x: x.id)
values = sorted(list(db.m_enrol_files))
values = sorted(list(db.m_enroll_files))
for i in range(5):
self.assertEqual(files[i].path, os.path.join("s3", str(values[i])))
self.assertEqual(db.get_client_id_from_file_id(files[i].id), 3)
......@@ -71,7 +71,7 @@ class ATNTDatabaseTest(unittest.TestCase):
self.assertEqual(set([x.id for x in f]),set([x.id for x in f2]))
# test the path function
f = db.objects(groups='dev', purposes = 'enrol', model_ids = [7])
f = db.objects(groups='dev', purposes = 'enroll', model_ids = [7])
ids = [x.id for x in f]
paths = db.paths(ids, 'test', '.tmp')
self.assertEqual(len(f), len(paths))
......
......@@ -3,20 +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
#
# 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 +64,17 @@ project = u'AT&T/ORL Database (Bob API)'
import time
copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
# Grab the setup entry
distribution = pkg_resources.require('bob.db.atnt')[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.atnt.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 +135,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 +189,7 @@ html_favicon = ''
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'bobdbdoc'
htmlhelp_basename = 'bob_db_atnt_doc'
# -- Options for LaTeX output --------------------------------------------------
......@@ -208,7 +203,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_atnt.tex', u'Bob',
u'Biometrics Group, Idiap Research Institute', 'manual'),
]
......@@ -246,40 +241,15 @@ man_pages = [
('index', 'bob', u'AT&T/ORL 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
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,21 @@
User's Guide
==============
This package contains the access API and descriptions for the `AT&T`_ database of faces, which is formerly known as the ORL database.
The actual raw data for the database should be downloaded from the original URL.
If you don't download the data yourself, it will automatically be downloaded to a temporary directory each time you create a :py:class:`bob.db.atnt.Database` object.
This package only contains the Bob_ accessor methods to use the DB directly from python, using a single self-designed evaluation protocol.
The Database Interface
----------------------
The `AT&T`_ database complies with the standard biometric verification database as described in :ref:`commons`, implementing the interface :py:class:`bob.db.verification.utils.Database`.
.. todo::
Write users guide.
Explain the particularities of the :py:class:`bob.db.atnt.Database`.
.. _at&t: http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html
.. _bob: https://www.idiap.ch/software/bob
......@@ -10,10 +10,6 @@
This module contains the interface to query the face verification protocol for the AT&T database of faces (formerly known as the ORL face database).
.. note::
This protocol interface does not include the original image data.
Please download the data yourself from http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html
.. warning::
The AT&T Database of Faces is a small, old and outdated facial image database.
According to [LiJain2005]_, the *algorithm performance over this database has been saturated*.
......
......@@ -34,20 +34,14 @@ setup(
],
entry_points={
# declare database to bob
'bob.db': [
'atnt = bob.db.atnt.driver:Interface',
],
# declare tests to bob
'bob.test': [
'atnt = bob.db.atnt.test:ATNTDatabaseTest',
],
},
classifiers = [
'Framework :: Bob',
'Development Status :: 4 - Beta',
'Intended Audience :: Developers',
'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',
......
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