Add biowave/2 (api change: beat.backend.python v1.4.2)

advanced/databases/biowave/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/.          ..
+
+BIOWAVE Vein Database
+---------------------
+
+Changelog
+=========
+
+* **Version 2**, 30/Oct/2017:
+
+  - Port to beat.backend.python v1.4.2
+
+* **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.
+