Commit f833fb0d authored by Philip ABBET's avatar Philip ABBET
Browse files

Merge branch 'vein-update' into 'master'

Database update - putvein/2, biowave/1

See merge request !12
parents 09fd306f 0c79a7a5
This diff is collapsed.
This diff is collapsed.
.. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/ ..
.. Contact: beat.support@idiap.ch ..
.. ..
.. This file is part of the beat.examples module of the BEAT platform. ..
.. ..
.. Commercial License Usage ..
.. Licensees holding valid commercial BEAT licenses may use this file in ..
.. accordance with the terms contained in a written agreement between you ..
.. and Idiap. For further information contact tto@idiap.ch ..
.. ..
.. Alternatively, this file may be used under the terms of the GNU Affero ..
.. Public License version 3 as published by the Free Software and appearing ..
.. in the file LICENSE.AGPL included in the packaging of this file. ..
.. The BEAT platform 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. ..
.. ..
.. You should have received a copy of the GNU Affero Public License along ..
.. with the BEAT platform. If not, see http://www.gnu.org/licenses/. ..
BIOWAVE Vein Database
---------------------
Changelog
=========
* **Version 1**, 10/Feb/2017:
- Initial release
Description
===========
The ``BIOWAVE`` database contains wrist vein images that are acquired using
BIOWATCH biometric sensor. For each subject of the database there are 3 session
images (sessions were held at least 24 hours apart). Each session consists of 5
attempts, in each attempt 5 images were acquired, meaning, that there are
``3 sessions x 5 attempts x 5 images = 75`` images per each person's hand,
``75 x 2 images`` per person.
Images were previously manually evaluated, and if any of the 75 one hand's
images were unusable (too blurred, veins couldn't be seen, etc), than all hand
data were discarded. That is way some persons has only 1 hand's images in the
database.
Statistics of the data - in total 111 hands:
1) Users with both hands images - 53
2) Users with only R hand images - 4
3) Users with only L hand images - 1
Data division in ``groups`` and ``purposes``
############################################
In the BIOWAVE database there are following groups and purposes:
+-------------+-----------+-----------------------+------------------------+
| **groups** | ``world`` | ``dev`` | ``eval`` |
+-------------+-----------+-----------------------+------------------------+
|**purposes** | ``train`` |``enroll`` / ``probe`` | ``enroll`` / ``probe`` |
+-------------+-----------+-----------------------+------------------------+
Data are divided into training, development and evolution data sets:
1) ``dev`` data set -- ``20`` persons with both hand images;
2) ``eval`` data set -- ``20`` persons with both hand images;
3) ``world`` data set -- the rest of ``13`` persons with both hand images + ``4`` persons with only ``right`` hand and the ``1`` person with only ``left`` hand images.
Data are divided as follows (the number means original persons ``ID`` (as in
data collection)):
1) ``dev`` data - [1, 3, 5, 6, 12, 15, 22, 23, 25, 45, 69, 71, 74, 76, 77, 78, 84, 129, 132, 134]
2) ``eval`` data - [4, 7, 21, 42, 43, 48, 54, 57, 58, 72, 73, 75, 83, 90, 99, 130, 131, 138, 141, 143]
3) ``world`` data - [13, 14, 17, 20, 24, 28, 31, 39, 51, 60, 68, 128, 133] + [37] + [2, 11, 46, 70]
In the ``enroll`` data sets are images only from session ``1`` whereas in
``probe`` data sets -- session's ``2`` and ``3`` data.
Protocols
#########
There currently are 6 *standard* protocols:
- ``Idiap_1_1_R``
- ``Idiap_1_5_R``
- ``Idiap_5_5_R``
- ``Idiap_1_1_L``
- ``Idiap_1_5_L``
- ``Idiap_5_5_L``
The general form::
Idiap_<a>_<b>_<c>
* a -- number of attempts used to construct model;
* b -- number of attempt images used to construct model;
* c -- hand (``L`` or ``R``). Always all images are used, the opposite hand's images are mirrored.
E.g. in protocol ``Idiap_5_5_R`` per one hand only one enroll model is
constructed using all session ``1`` images (``5 attempt x 5 images``). In this
protocol ``right`` hands are included unchanged, but ``left`` hands are
mirrored.
After data alignment were annotated, that included common point finding between
each person images, we noted that some of the person data were almost impossible
to annotate. Hands were:
- Person_002/Right
- Person_005/Left
- Person_015/Right
- Person_046/Right
- Person_068/Right
- Person_068/Left
- Person_129/Right
- Person_138/Left
For protocols:
- ``Idiap_1_1_R_less``
- ``Idiap_1_5_R_less``
- ``Idiap_5_5_R_less``
also listed hand data were removed.
Protocol ``Idiap_3_5_R`` is not *standard* - in this protocol enroll model is
constructed using all 3 session 1st attempt images (thus each model consists of
``3x5=15`` images). This protocol is made to understand the enroll image
variabilities impact on the recognition rate.
Finally, the protocols:
- ``Idiap_1_1_R_BEAT_test``
- ``Idiap_1_5_R_BEAT_test``
- ``Idiap_5_5_R_BEAT_test``
are made as test protocols mainly for the BEAT platform. Again, the numbers in
the name indicates number of images per attempt and attempt count per each
enroll model. Each of the protocol groups consists of only 2 person data:
- train -- [128, 133],
- dev -- [132, 134],
- eval -- [141, 143].
All these protocols uses the ``advanced_vein_recognition_2`` template.
Annotations
###########
8% of database files have annotations (2 images per session, 6 images per hand,
altogether 666 images). There are:
- vein pattern binary annotations;
- ROI binary annotations;
- alignment point annotations (for each hand 3-5 points marked).
Annotations to replace extractors
#################################
Special protocols that consists only the files that have annotations are made.
Meaning, these protocols can be used to run !!!!! TBD
The organisation of the database is the same as before, only now, because there
are only 2 annotated images per session, protocols are renamed accordingly (also
note, that now protocols ``Idiap_1_5_R`` and ``Idiap_1_5_L`` doesn't make any
sense and are removed, because there are only 1 image per attempt that is
annotated):
- ``Idiap_1_1_R`` -> renamed as ``Idiap_1_1_R_annotations``;
- ``Idiap_5_5_R`` -> renamed as ``Idiap_2_1_R_annotations``;
- ``Idiap_1_1_L`` -> renamed as ``Idiap_1_1_L_annotations``;
- ``Idiap_5_5_L`` -> renamed as ``Idiap_2_1_L_annotations``;
Also, the same as ``Idiap_<a>_<b>_<c>_BEAT_test`` protocols were created to
speedy test BEAT implementation and compare results with ``bob.bio.vein``, also
test protocols for annotations are implemented:
- ``Idiap_1_1_R_annotations_BEAT_test``;
- ``Idiap_2_1_R_annotations_BEAT_test``;
- ``Idiap_1_1_L_annotations_BEAT_test``;
- ``Idiap_2_1_L_annotations_BEAT_test``;
These protocols uses the ``advanced_vein_annotations`` template.
Also, to benchmark different algorithms against **all** image annotations, there
are implemented protocol ``annotations_benchmark`` that is implemented using
``advanced_annotation_benchmark`` template.
This diff is collapsed.
###############################################################################
# #
# Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/ #
# Contact: beat.support@idiap.ch #
# #
# This file is part of the beat.examples module of the BEAT platform. #
# #
# Commercial License Usage #
# Licensees holding valid commercial BEAT licenses may use this file in #
# accordance with the terms contained in a written agreement between you #
# and Idiap. For further information contact tto@idiap.ch #
# #
# Alternatively, this file may be used under the terms of the GNU Affero #
# Public License version 3 as published by the Free Software and appearing #
# in the file LICENSE.AGPL included in the packaging of this file. #
# The BEAT platform 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. #
# #
# You should have received a copy of the GNU Affero Public License along #
# with the BEAT platform. If not, see http://www.gnu.org/licenses/. #
# #
###############################################################################
import numpy as np
import bob.io.base
import bob.io.image
import bob.db.putvein
import bob.ip.color
import os
class View:
def setup(self,
root_folder,
outputs,
parameters,
force_start_index=None,
force_end_index=None):
self.root_folder = os.path.join(root_folder, '')
self.outputs = outputs
self.parameters = parameters
self.db = bob.db.putvein.Database()
self.objs = sorted(self.db.objects(protocol=self.parameters['protocol'],
purposes=self.parameters.get('purpose', None),
groups=[self.parameters['group']],
kinds=[self.parameters['kind']]
),
key=lambda x: x.client_id)
self.next_index = 0
self.force_start_index = force_start_index
self.force_end_index = force_end_index
# Retrieve only 'useful' data
# End index
if self.force_end_index is not None:
self.objs = self.objs[:self.force_end_index+1]
# Start index
if self.force_start_index is not None:
self.objs = self.objs[self.force_start_index:]
self.next_index = self.force_start_index
else:
self.force_start_index = 0
return True
def done(self):
return (self.next_index-self.force_start_index >= len(self.objs))
def next(self):
obj = self.objs[self.next_index-self.force_start_index]
# Please pay attention - we can use CLIENT ID as long as we don't use
# same client both hand data in the same protocol. Currently this
# doesn't happen.
if self.outputs['client_id'].isConnected():
client_id = obj.get_client_id()
self.outputs['client_id'].write({'value':
np.uint64(client_id)},
self.next_index)
if "enroll" in self.parameters.get('purpose', ""):
if self.outputs['model_id'].isConnected():
model_id = \
self.db.file_model_id(file=obj,
protocol=self.parameters['protocol'])
model_id = model_id.encode('utf-8')
self.outputs['model_id'].write({'text':
model_id},
self.next_index)
if self.outputs['image'].isConnected():
"""
The image returned by the ``bob.db.putvein`` is RGB (with shape
(3, 768, 1024)). This method converts image to a greyscale
(shape (768, 1024)) and then rotates image by 270 deg so that
images can be used with ``bob.bio.vein`` algorythms designed for
the ``bob.db.biowave_v1`` database.
Output images dimentions - (1024, 768).
"""
color_image = obj.load(self.root_folder)
grayscale_image = bob.ip.color.rgb_to_gray(color_image)
grayscale_image = np.rot90(grayscale_image, k=3)
data = {
'value': grayscale_image
}
self.outputs['image'].write(data, self.next_index)
self.next_index += 1
return True
class TemplateView:
# Reasoning: Each client may have a number of models in certain databases.
# So, each model receives an unique identifier. Those identifiers are
# linked to the client identifier and contain a number of images to
# generated the model from.
def setup(self,
root_folder,
outputs,
parameters,
force_start_index=None,
force_end_index=None):
self.root_folder = os.path.join(root_folder, '')
self.outputs = outputs
self.parameters = parameters
self.db = bob.db.putvein.Database()
self.template_ids = \
sorted(self.db.model_ids(protocol=self.parameters['protocol'],
groups=[self.parameters['group']],
kinds=[self.parameters['kind']]
))
self.objs = None
self.current_template_index = 0
self.current_obj_index = 0
self.next_index = 0
self.force_start_index = force_start_index
self.force_end_index = force_end_index
# We don't know how many objects we will have, so we can't operate with
# self.force_end_index.
if self.force_start_index is None:
self.force_start_index = 0
# Example taxen from atnt/3 - idea to iterate through ``next`` method
# to get indexes right
while self.next_index < self.force_start_index:
self.next()
return True
def done(self):
# return (self.next_index-self.force_start_index >= len(self.objs))
return ((self.current_template_index >= len(self.template_ids)) or
(self.force_end_index is not None and
self.force_end_index < self.next_index))
def next(self):
if self.objs is None:
# probe for the specific objects concerning a given client
self.objs = \
sorted(self.db.objects(protocol=self.parameters['protocol'],
purposes=self.parameters.get('purpose',
None),
groups=[self.parameters['group']],
kinds=[self.parameters['kind']],
model_ids=[self.template_ids[self.current_template_index]]),
key=lambda x: x.id)
if (self.force_start_index <= self.next_index and
(self.force_end_index is None or
self.force_end_index >= self.next_index)):
if self.outputs['model_id'].isConnected():
# for this database the
# ``self.template_ids[self.current_template_index]`` is the
# ``model_id``:
model_id = self.template_ids[self.current_template_index]
model_id = model_id.encode('utf-8')
self.outputs['model_id'].write({'text':
model_id},
self.next_index+len(self.objs)-1)
if self.outputs['client_id'].isConnected():
client_id = self.objs[0].get_client_id()
self.outputs['client_id'].write({'value':
np.uint64(client_id)},
self.next_index+len(self.objs)-1)
obj = self.objs[self.current_obj_index]
if self.outputs['image'].isConnected():
# This line is taken from the "atnt/3" database's view. It seams
# that this could cause problems, if model has N images, but
# ``self.force_end_index`` /= N*M, where M -- Natural number:
if (self.force_start_index <= self.next_index and
(self.force_end_index is None or
self.force_end_index >= self.next_index)):
# No need to test if output is connected:
# if self.outputs['image'].isConnected():
"""
The image returned by the ``bob.db.putvein`` is RGB (with shape
(3, 768, 1024)). This method converts image to a greyscale
(shape (768, 1024)) and then rotates image by 270 deg so that
images can be used with ``bob.bio.vein`` algorythms designed
for the ``bob.db.biowave_v1`` database.
Output images dimentions - (1024, 768).
"""
color_image = obj.load(self.root_folder)
grayscale_image = bob.ip.color.rgb_to_gray(color_image)
grayscale_image = np.rot90(grayscale_image, k=3)
data = {
'value': grayscale_image
}
self.outputs['image'].write(data, self.next_index)
self.next_index += 1
self.current_obj_index += 1
else:
self.next_index += len(self.objs)
self.current_obj_index = len(self.objs)
if self.current_obj_index == len(self.objs):
self.objs = None
self.current_obj_index = 0
self.current_template_index += 1
return True
"""
# test bob.db.putvein object compatibility with BEAT
import bob.db.putvein
db = bob.db.putvein.Database()
files = db.objects(protocol="RL_4", kinds="wrist", groups="dev", purposes="probe")
objects = sorted(files, key=lambda x: x.client_id)
for nr in range(len(files)):
print("{}-{}, sorted - {}-{}".format(files[nr].client_id, files[nr].nr, objects[nr].client_id, objects[nr].nr))
print(files == objects)
"""
.. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/ ..
.. Contact: beat.support@idiap.ch ..
.. ..
.. This file is part of the beat.examples module of the BEAT platform. ..
.. ..
.. Commercial License Usage ..
.. Licensees holding valid commercial BEAT licenses may use this file in ..
.. accordance with the terms contained in a written agreement between you ..
.. and Idiap. For further information contact tto@idiap.ch ..
.. ..
.. Alternatively, this file may be used under the terms of the GNU Affero ..
.. Public License version 3 as published by the Free Software and appearing ..
.. in the file LICENSE.AGPL included in the packaging of this file. ..
.. The BEAT platform 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. ..
.. ..
.. You should have received a copy of the GNU Affero Public License along ..
.. with the BEAT platform. If not, see http://www.gnu.org/licenses/. ..
The PUT Vein Database
---------------------
Changelog
=========
* **Version 1**, 10/Feb/2016:
- Initial release
* **Version 2**, 10/Feb/2017:
- Major update to make database compatible with BIOWAVE database toolchains
Description
===========
PUT Vein pattern database consists of 2400 images presenting human vein
patterns. Half of images contains a palmar vein pattern (1200 images) and
another half contains a wrist vein pattern (another 1200 images). Data was
acquired from both hands of 50 students, with means it has a 100 different
patterns for palm and wrist region. Pictures ware taken in 3 series, 4 pictures
each, with at least one week interval between each series. In case of palm
region volunteers were asked to put his/her hand on the device to cover
acquisition window, in way that line below their fingers coincident with its
edge. No additional positioning systems ware used. In case of wrist region only
construction allowing to place palm and wrist in comfortable way was used to
help position a hand.
Original images have **768 x 1024** resolution and are saved as 24-bit bitmap.
Database consist of 2 main sections: hand and wrist, with are further divided
in persons. Each person folder has sub-sections for left and right hand, which
are separated into series.
More information about the original database - `PUT Vein database
<http://biometrics.put.poznan.pl/vein-dataset/>`_.
In order to enable to use the database with BIOWAVE toolchains, this database
implementation converts image to a grey-scale (shape (768, 1024)) and then
rotates images by 270 deg so that vein pattern in wrist images would appear
vertical (wrist's part closer to the palm would appear at the top of the image)
In this implementation we use both - original 50 client x 2 hand data - in the
database clients with IDs between ``1`` and ``50`` - and also - mirrored
file representations (left hand / palm data mirrored to look like right hand
data and vice versa) - clients with IDs between ``51`` and ``100``.
Protocols
=========
Currently (as on 10.02.2017) there are 10x2 protocols, they also match the
protocols in ``bob.bio.vein``:
- ``palm-L_4``,
- ``palm-R_4``,
- ``palm-RL_4``,
- ``palm-LR_4``,
- ``palm-R_BEAT_4``,
- ``palm-L_1``,
- ``palm-R_1``,
- ``palm-RL_1``,
- ``palm-LR_1``,
- ``palm-R_BEAT_1``,
- ``wrist-L_4``,
- ``wrist-R_4``,
- ``wrist-RL_4``,
- ``wrist-LR_4``,
- ``wrist-R_BEAT_4``,
- ``wrist-L_1``,
- ``wrist-R_1``,
- ``wrist-RL_1``,
- ``wrist-LR_1``,
- ``wrist-R_BEAT_1``.
Protocols (except the ``BEAT`` protocols) still contains the original protocol
(``L``, ``R``, ``RL``, ``LR``) data, the difference is, whether each enroll
model is constructed using all 4 hand's images (protocol name ends with ``4``),
or each enroll image is used as a model (corresponding protocol names ends with
``1``).
The original protocols consists of following data, ``world`` purpose dataset
consists of the **same** data, as ``dev`` purpose dataset, so won't be
separately described:
+-------------+-----------------------------------------+-------------------------------------------+
|**protocol** | ``dev`` | ``eval`` |
+-------------+-----------------------------------------+-------------------------------------------+
| L | IDs 1-25, un-mirrored left hand images | IDs 26-50, un-mirrored left hand images |
+-------------+-----------------------------------------+-------------------------------------------+
| R | IDs 1-25, un-mirrored right hand images | IDs 26-50, un-mirrored right hand images |
+-------------+-----------------------------------------+-------------------------------------------+
| RL | IDs 1-50, un-mirrored right hand images |IDs 51-100, mirrored left hand images |
| | |(to represent right hand) |
+-------------+-----------------------------------------+-------------------------------------------+
| LR | IDs 1-50, un-mirrored left hand images |IDs 51-100, mirrored right hand images |
| | |(to represent left hand) |
+-------------+-----------------------------------------+-------------------------------------------+
The new test protocols (ends with ``R_BEAT_1`` and ``R_BEAT_4``) are intended
for use with ``bob.bio.vein`` and ``BEAT`` platform for quick tests, if
necessary. Both protocols consist of such data:
+-------------+---------------------------------------------------------+------------------------------------------------------------+
|**protocol** | ``dev`` | ``eval`` |
+-------------+---------------------------------------------------------+------------------------------------------------------------+
| R_BEAT | IDs ``1``, ``2``, un-mirrored right hand / wrist images | IDs ``26``, ``27``, un-mirrored right hand / wrist images |
+-------------+---------------------------------------------------------+------------------------------------------------------------+
Supports Markdown
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