Merge branch 'vein-update' into 'master'

Database update - putvein/2, biowave/1

See merge request !12

advanced/databases/biowave/1.rst

+.. 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.
+

advanced/databases/putvein/2.rst

+.. 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 |
++-------------+---------------------------------------------------------+------------------------------------------------------------+