Commit 094837a8 authored by André Anjos's avatar André Anjos 💬

Overall database refactoring; Improved docs and tests

parent 385fecec
Pipeline #15657 canceled with stages
in 2 minutes and 27 seconds
...@@ -18,3 +18,4 @@ build ...@@ -18,3 +18,4 @@ build
*.egg *.egg
src/ src/
db.sql3 db.sql3
bob/db/utfvp/data/
include LICENSE README.rst buildout.cfg develop.cfg requirements.txt version.txt include LICENSE README.rst buildout.cfg develop.cfg requirements.txt version.txt
recursive-include doc *.py *.rst recursive-include doc *.py *.rst
recursive-include bob *.sql3 recursive-include bob *.sql3 *.csv *.txt
...@@ -5,7 +5,7 @@ ...@@ -5,7 +5,7 @@
""" """
from .query import Database from .query import Database
from .models import Client, File, Protocol, Model from .models import Client, Finger, File, Protocol, Subset
def get_config(): def get_config():
...@@ -15,28 +15,5 @@ def get_config(): ...@@ -15,28 +15,5 @@ def get_config():
return bob.extension.get_config(__name__) return bob.extension.get_config(__name__)
# gets sphinx autodoc done right - don't remove it
def __appropriate__(*args):
"""Says object was actually declared here, an not on the import module.
Parameters:
*args: An iterable of objects to modify
Resolves `Sphinx referencing issues
<https://github.com/sphinx-doc/sphinx/issues/3048>`
"""
for obj in args: obj.__module__ = __name__
__appropriate__(
Database,
Client,
File,
Protocol,
Model,
)
# gets sphinx autodoc done right - don't remove it # gets sphinx autodoc done right - don't remove it
__all__ = [_ for _ in dir() if not _.startswith('_')] __all__ = [_ for _ in dir() if not _.startswith('_')]
This diff is collapsed.
#!/usr/bin/env python #!/usr/bin/env python
# vim: set fileencoding=utf-8 : # vim: set fileencoding=utf-8 :
"""Bob Database Driver entry-point for the UTFVP """Bob Database Driver entry-point for the UTFVP Fingervein database
""" """
import os import os
import sys import sys
import pkg_resources
from bob.db.base.driver import Interface as BaseInterface from bob.db.base.driver import Interface as BaseInterface
...@@ -15,16 +16,11 @@ def dumplist(args): ...@@ -15,16 +16,11 @@ def dumplist(args):
from .query import Database from .query import Database
db = Database() db = Database()
model_ids = None
if args.models is not None:
if isinstance(args.models, (list, tuple)): model_ids = args.models
else: model_ids = (args.models,)
r = db.objects( r = db.objects(
protocol=args.protocol, protocol=args.protocol,
purposes=args.purpose,
model_ids=model_ids,
groups=args.group, groups=args.group,
classes=args.sclass purposes=args.purpose,
model_ids=args.models,
) )
output = sys.stdout output = sys.stdout
...@@ -72,28 +68,33 @@ def checkfiles(args): ...@@ -72,28 +68,33 @@ def checkfiles(args):
class Interface(BaseInterface): class Interface(BaseInterface):
def name(self): def name(self):
return 'utfvp' return 'utfvp'
def version(self): def version(self):
import pkg_resources # part of setuptools
return pkg_resources.require('bob.db.%s' % self.name())[0].version return pkg_resources.require('bob.db.%s' % self.name())[0].version
def files(self): def files(self):
basedir = pkg_resources.resource_filename(__name__, '')
filelist = os.path.join(basedir, 'files.txt')
with open(filelist, 'rt') as f:
return [os.path.join(basedir, k.strip()) for k in \
f.readlines() if k.strip()]
from pkg_resources import resource_filename
raw_files = ('db.sql3',)
return [resource_filename(__name__, k) for k in raw_files]
def type(self): def type(self):
return 'sqlite' return 'sqlite'
def add_commands(self, parser): def add_commands(self, parser):
from . import __doc__ as docs from . import __doc__ as docs
subparsers = self.setup_parser(parser, subparsers = self.setup_parser(parser,
"UTFVP database", docs) "UTFVP Fingervein database", docs)
# example: get the "create" action from a submodule # example: get the "create" action from a submodule
from .create import add_command as create_command from .create import add_command as create_command
...@@ -109,7 +110,7 @@ class Interface(BaseInterface): ...@@ -109,7 +110,7 @@ class Interface(BaseInterface):
parser.add_argument('-e', '--extension', default='', help="if given, this extension will be appended to every entry returned.") parser.add_argument('-e', '--extension', default='', help="if given, this extension will be appended to every entry returned.")
parser.add_argument('-p', '--protocol', help="if given, limits the dump to a particular subset of the data that corresponds to the given protocol.", choices=db.protocol_names() if db.is_valid() else ()) parser.add_argument('-p', '--protocol', help="if given, limits the dump to a particular subset of the data that corresponds to the given protocol.", choices=db.protocol_names() if db.is_valid() else ())
parser.add_argument('-u', '--purpose', help="if given, this value will limit the output files to those designed for the given purposes.", choices=db.purposes() if db.is_valid() else ()) parser.add_argument('-u', '--purpose', help="if given, this value will limit the output files to those designed for the given purposes.", choices=db.purposes() if db.is_valid() else ())
parser.add_argument('-m', '--models', type=str, help="if given, limits the dump to a particular model", choices=db.model_ids() if db.is_valid() else ()) parser.add_argument('-m', '--models', type=str, help="if given, limits the dump to a particular model")
parser.add_argument('-g', '--group', help="if given, this value will limit the output files to those belonging to a particular protocolar group.", choices=db.groups() if db.is_valid() else ()) parser.add_argument('-g', '--group', help="if given, this value will limit the output files to those belonging to a particular protocolar group.", choices=db.groups() if db.is_valid() else ())
parser.add_argument('-c', '--class', dest='sclass', help="if given, this value will limit the output files to those belonging to the given classes.", choices=('client', 'impostor')) parser.add_argument('-c', '--class', dest='sclass', help="if given, this value will limit the output files to those belonging to the given classes.", choices=('client', 'impostor'))
parser.add_argument('--self-test', dest="selftest", action='store_true', help=argparse.SUPPRESS) parser.add_argument('--self-test', dest="selftest", action='store_true', help=argparse.SUPPRESS)
...@@ -118,6 +119,6 @@ class Interface(BaseInterface): ...@@ -118,6 +119,6 @@ class Interface(BaseInterface):
# the "checkfiles" action # the "checkfiles" action
parser = subparsers.add_parser('checkfiles', help=checkfiles.__doc__) parser = subparsers.add_parser('checkfiles', help=checkfiles.__doc__)
parser.add_argument('-d', '--directory', default='', help="if given, this path will be prepended to every entry returned.") parser.add_argument('-d', '--directory', default='', help="if given, this path will be prepended to every entry returned.")
parser.add_argument('-e', '--extension', default='', help="if given, this extension will be appended to every entry returned.") parser.add_argument('-e', '--extension', default='.png', help="if given, this extension will be appended to every entry returned.")
parser.add_argument('--self-test', dest="selftest", action='store_true', help=argparse.SUPPRESS) parser.add_argument('--self-test', dest="selftest", action='store_true', help=argparse.SUPPRESS)
parser.set_defaults(func=checkfiles) #action parser.set_defaults(func=checkfiles) #action
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
.. vim: set fileencoding=utf-8 : .. vim: set fileencoding=utf-8 :
.. Thu 18 Aug 2016 18:03:09 CEST
============== ==============
User's Guide User's Guide
============== ==============
This package contains the access API and descriptions for the `UTFVP Fingervein This package contains the access API and descriptions for the `UTFVP Fingervein
database`_. It only contains the Bob_ accessor methods to use the DB directly Database`_. It only contains the Bob_ accessor methods to use the DB directly
from python, with our certified protocols. The actual raw data for the `UTFVP from python, with our certified protocols. The actual raw data for the dataset
Fingervein database`_ should be downloaded from the original URL. should be downloaded from the original URL.
The Database Interface Data
---------------------- ----
The :py:class:`bob.db.utfvp.Database` complies with the standard Bob database The fingervein image database consists of 1440 images taken in 2 distinct
itnerface. session in two days (May 9th, 2012 and May 23rd, 2012) using a custom built
fingervein sensor. In each session, each of the 60 subjects in the dataset were
asked to present 6 fingers to the sensor twice, making up separate tries. The
six fingers are the left and right ring, middle and index fingers. Therefore,
the database contains 60x6 = 360 unique fingers.
.. todo:: Files in the database have a strict naming convention and are organized in
Explain the particularities of the :py:class:`bob.db.utfvp.Database`. directories following their subject identifier like so:
``0003/0003_5_2_120509-141536``. The fields can be interpreted as
``<subject-id>/<subject-id>_<finger-name>_<trial>_<date>-<hour>``. The subject
identifier is written as a 4-digit number with leading zeroes, varying from 1
to 60. The finger name is one of the following:
* **1**: Left ring
* **2**: Left middle
* **3**: Left index
* **4**: Right index
* **5**: Right middle
* **6**: Right ring
The trial identifiers can vary between 1 and 4. The first two tries were
captured during the first session while the last two, on the second session.
Given the difference in the images between trials on the same day, we assume
users were asked to remove the finger from the device and re-position it
afterwards.
Protocols
---------
There are 15 protocols implemented in this package:
* 1vsall
* nom
* nomLeftRing
* nomLeftMiddle
* nomLeftIndex
* nomRightIndex
* nomRightMiddle
* nomRightRing
* full
* fullLeftRing
* fullLeftMiddle
* fullLeftIndex
* fullRightIndex
* fullRightMiddle
* fullRightRing
They are described next.
"nom" Protocols
===============
"nom" means "normal operation mode". In this set of protocols, images from
different clients are separated in different sets that can be used for system
training, validation and evaluation:
* Fingers from clients in the range [1, 10] are used on the training set
* Fingers from clients in the range [11, 28] are used on the development
(or validation) set
* Fingers from clients in the range [29, 60] are used in the evaluation
(or test) set
Data from the first session (both trials) can be used for enrolling the finger
while data on the last session (both trials) shold be used exclusively for
probing the finger. In the way setup by this database interface, each of the
samples is returned as a separate enrollment model. If a single score per
finger is required, the user must manipulate the final score listings and fuse
results themselves.
Matching happens exhaustively between all probes and models. The variants named
"nomLeftRing", for example, contain the data filtered by finger name as per the
listings above. For example, "Left Ring" means all files named
``*/*_1_*_*-*.png``. Therefore, the equivalent protocol contains only 1/6 of
the files of its complete ``nom`` version.
The following table specifies the number of samples in each set, together with
the counts of samples, models and probes in each ``nom`` protocol.
.. table:: Counts for the ``nom`` protocols
:widths: auto
================== =============== ======== ======== ============== ======== ======== ==============
Training Development Evaluation
------------------ --------------- -------------------------------- --------------------------------
Protocol Samples Models Probes Probes/Model Models Probes Probes/Model
================== =============== ======== ======== ============== ======== ======== ==============
nom 240 216 216 216 384 384 384
nomLeftRing 40 36 36 36 64 64 64
nomLeftMiddle 40 36 36 36 64 64 64
nomLeftIndex 40 36 36 36 64 64 64
nomRightIndex 40 36 36 36 64 64 64
nomRightMiddle 40 36 36 36 64 64 64
nomRightRing 40 36 36 36 64 64 64
================== =============== ======== ======== ============== ======== ======== ==============
"full" Protocols
================
"full" protocols are meant to match current practices in fingervein reporting
in which most published material don't use a separate evaluation set. All data
is placed on the development (or validation) set. In these protocols, all
images are used both for enrolling and probing for fingers. It is, of course,
a biased setup. Matching happens exhaustively between all samples in the
development set.
The variants named "fullLeftRing", for example, contain the data filtered by
finger name as per the listings above. For example, "Left Ring" means all files
named ``*/*_1_*_*-*.png``. Therefore, the equivalent protocol contains only 1/6
of the files of its complete ``full`` version.
The following table specifies the number of samples in each set, together with
the counts of samples, models and probes in each ``full`` protocol.
.. table:: Counts for the ``full`` protocols
:widths: auto
================== =============== ======== ======== ============== ======== ======== ==============
Training Development Evaluation
------------------ --------------- -------------------------------- --------------------------------
Protocol Samples Models Probes Probes/Model Models Probes Probes/Model
================== =============== ======== ======== ============== ======== ======== ==============
full 0 1440 1440 1440 0 0 0
fullLeftRing 0 240 240 240 0 0 0
fullLeftMiddle 0 240 240 240 0 0 0
fullLeftIndex 0 240 240 240 0 0 0
fullRightIndex 0 240 240 240 0 0 0
fullRightMiddle 0 240 240 240 0 0 0
fullRightRing 0 240 240 240 0 0 0
================== =============== ======== ======== ============== ======== ======== ==============
"1vsall" Protocol
=================
The "1vsall" protocol is meant as a cross-validation protocol. All data from
the dataset is split into training and development (or validation). No samples
are allocated for a separate evaluation (or test) set. The training set is
composed of all samples of fingers ``0001_1`` (left ring finger of subject 1),
``0002_2`` (left middle finger of subjec 2), ``0003_3`` (left index finger of
subject 3), ``0004_4`` (right index finger of subject 4), ``0005_5`` (right
middle finger of subject 5), ``0006_6`` (right ring finger of subject 6),
``0007_1`` (left ring finger of subject 7), ``0008_2`` (left middle finger of
subject 8) and so on, until subject 35 (inclusive). There are 140 images in
total on this set.
All other 1300 samples from the dataset are used as a development (or
validation) set. Each sample generates a single model and is used as a probe
for all other models. Matching happens exhaustively, but with the same image
that generated the model being matched. So, there are 1299 probes per model.
The following table specifies the number of samples in each set, together with
the counts of samples, models and probes this protocol.
.. table:: Counts for the ``1vsall`` protocol
:widths: auto
================== =============== ======== ======== ============== ======== ======== ==============
Training Development Evaluation
------------------ --------------- -------------------------------- --------------------------------
Protocol Samples Models Probes Probes/Model Models Probes Probes/Model
================== =============== ======== ======== ============== ======== ======== ==============
1vsall 140 1300 1300 1299 0 0 0
================== =============== ======== ======== ============== ======== ======== ==============
.. Place your references here
.. _bob: https://www.idiap.ch/software/bob .. _bob: https://www.idiap.ch/software/bob
.. _utfvp fingervein database: http://www.sas.el.utwente.nl/home/datasets .. _utfvp fingervein database: http://www.sas.el.utwente.nl/home/datasets
...@@ -7,10 +7,13 @@ ...@@ -7,10 +7,13 @@
UTFVP Fingervein Database UTFVP Fingervein Database
========================== ==========================
The `UTFVP Fingervein Database <http://www.sas.ewi.utwente.nl>`_ for finger vein recognition consists of 1300 images from 60 clients. The `UTFVP Fingervein Database <http://www.sas.ewi.utwente.nl>`_ for finger
This database was produced at the `University of Twente <http://www.utwente.nl/en/>`_, in Nederlands. vein recognition consists of 1440 images from 60 clients. This database was
produced at the `University of Twente <http://www.utwente.nl/en/>`_, in
Nederlands.
If you use this database in your publication, please cite the following paper on your references: If you use this database in your publication, please cite the following paper
on your references:
.. code-block:: latex .. code-block:: latex
...@@ -35,6 +38,7 @@ If you use this database in your publication, please cite the following paper on ...@@ -35,6 +38,7 @@ If you use this database in your publication, please cite the following paper on
id_number = {10.1109/ICB.2013.6612966} id_number = {10.1109/ICB.2013.6612966}
} }
Documentation Documentation
------------- -------------
......
.. vim: set fileencoding=utf-8 : .. vim: set fileencoding=utf-8 :
.. Thu 18 Aug 2016 18:03:33 CEST .. Thu 25 Jan 2018 10:56:14 CET
============ ============
Python API Python API
......
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