Readme

License

BSD 3-Clause

Cite

If this software is used to prepare for an article / a publication please include the following reference:

Text

M. Linortner and A. Uhl, “VeinPLUS+: A Publicly Available and Free Software Framework for Vein Recognition,” 2021 International Conference of the Biometrics Special Interest Group (BIOSIG), 2021.

BibTeX

@INPROCEEDINGS{vpp2021,
  author={Linortner, Michael and Uhl, Andreas},
  booktitle={2021 International Conference of the Biometrics Special Interest Group (BIOSIG)}, 
  title={VeinPLUS+: A Publicly Available and Free Software Framework for Vein Recognition}, 
  year={2021},
  volume={},
  number={},
  pages={1-5},
  doi={10.1109/BIOSIG52210.2021.9548286}}

Requirements / ext. Dependencies

• OpenCV version 3.4.2
• CMake 3.4 or higher
• CLI11 (is included in the source code of the vpp project)

Install

• Install the OpenCV library. The project has been developed and tested with the version 3.4.2

• Download and prepare the VPP software:
  After downloading and extracting the software there is a file projectsettings_example.cmake located in the project’s root folder. Make a copy in the same location (e.g. my_projectsettings.cmake) and edit the containing path variable to your installed opencv library.

• Compile on Linux:

  • Edit the script build_vpp_on_linux.sh located in the project’s root directory:
    • Set your project settings: -DMY_PROJECT_CONFIG=my_projectsettings.cmake
    • Specify whether to compile as relaese or debug: -DCMAKE_BUILD_TYPE=Release or -DCMAKE_BUILD_TYPE=Debug
  • Run the script

• Compile on Windows
  using Visual Studio 2017 or higher (tested with VS2017).

  • Open Visual Studio

  • Under File - Open - Folder navigate to the vpp root folder and open it.

  • Customize CMake build settings:
    Select the configuration drop-down in the toolbar and choose Manage Configurations. Choose your target (e.g. x64-Debug). The first time you select a configuration, Visual Studio creates a CMakeSettings.json file in your project’s root folder. To add additional configurations for example x64-Release right-click CMakeSettings.json and choose Add Configuration.
    Add in CMakeSettings.json under cmakeCommandArgs

     "cmakeCommandArgs": "", 

    the build configuration for vpp:

     "cmakeCommandArgs": "-DMY_PROJECT_CONFIG=my_projectsettings.cmake -DWITH_MATIO=OFF -DENABLE_UNIT_TESTS=OFF -DWITH_EXTENDED_DEBUG_OUTPUT=OFF", 

  • Run CMake - Build All.

Usage

Example experiments from the VeinPLUS+ paper

To run the experiments published in the VeinPLUS+ paper, follow the steps:

• Download the PLUSVein-FV3 Finger Vein Data Set.
• Locate the folder example/biosig21/ under the vpp root directory. There is a script biosig21_experiment_vpp.sh. Edit the file to set the absolute path to the PLUS-FV3-Laser/DORSAL and PLUS-FV3-Laser/PALMAR data sets of the ROI images you downloaded in the previous step. Run the script. The results will be written to example/biosig21/results.
• To run the experiments with the PLUS OpenVein-Toolkit (OVTK) download the software from here. Edit the script biosig21_experiment_ovtk.sh to set the correct paths and run it. The results are written into the same folder where the input data are stored (see the OVTK documentation for details). Only the log files are written to biosig21/results.

Software usage

This section gives a brief overview of the main features of the sofware and how to use them. For further details have a look into the documentation.

Prepare a settings file

First, prepare a settings file (e.g. my_experiment_settings.xml) to configure the feature extraction pipeline and comparison project to fit your experiment. See settings files under examples/biosig21/settings as example. Those have been used to run the experiments for the VeinPLUS+ paper. Under settings in the project’s root folder there are settings files for each implemented method located.

Run an experiment on a single database

  vpp -p path/to/data -s my_experiment_settings.xml -o outputdirectory 

To run the software this way, the used database has to be supported by the software. Otherwise it can’t be loaded.

Run an experiment with two databases (probe-gallery comparison mode)

  vpp -p path/to/probe_db -g path/to/gallery_db -s my_experiment_settings.xml -o outputdirectory 

Features will be extracted with the same feature extraction pipeline specified in the settings file and in the comparison stage the samples from the probe database are compared to the samples from the gallery database. Again only the implemented database formats and comparison protocols are supported.

Run experiments on an individual database

Canonical sample representation

The software works internally with a ID representation which we call canonical id. Each biometric sample identified by an ID which consists of <SubjectID>, <SourceID>, <SampleID> and <SessionID>. Each individual ID is represented as integer value. The combination of the four ID values needs to be unique!

• <SubjectID> The ID of a biometric subject (Person).
• <SourceID> The ID of a subject’s biometric trait (e.g. finger ID).
• <SampleID> The ID of a biometric sample (e.g. the vein image of a subject’s finger).
• <SessionID> The ID of the session at which the biometric sample has been captures.

Note: The <SessionID> is ignored when generating the comparison list using the implemented comparison protocols!

The string representation of the canoncial id looks as follows: <SubjectID>_<SourceID>_<SampleID>_<SessionID>

Database structure file

To use and load an individual database into the software generate a database structure file, an ASCII text file where each line represents a single sample in your database in the following format:
<SubjectID>_<SourceID>_<SampleID>_<SessionID> absolute/path/to/sample.png

Example:

    1_1_1_1 /home/joe/database/PersonA_IndexFinger_Sample1.png
    1_1_2_1 /home/joe/database/PersonA_IndexFinger_Sample2.png
    1_2_1_1 /home/joe/database/PersonA_RingFinger_Sample1.png
    1_2_2_1 /home/joe/database/PersonA_RingFinger_Sample2.png
    2_1_1_1 /home/joe/database/PersonB_IndexFinger_Sample1.png
    2_1_2_1 /home/joe/database/PersonB_IndexFinger_Sample2.png
    .
    .
    .

If there are any gaps in the ID numbers it’s fine.

Using the database structure file

To use the database structure file call the software with the flag --useDataStructureFile for a single database

  vpp --useDataStructureFile -p my_database_structure_file.txt -s my_experiment_settings.xml -o outputdirectory 

or in probe-gallery comparison mode:

  vpp --useDataStructureFile -p my_probe_db_structure_file.txt -g my_gallery_db_structure_file.txt -s my_experiment_settings.xml -o outputdirectory 

The implemented comparison protocols are available.

Using an individual comparison protocol

To use an individual comparison protocol create your own comparison list file, an ASCII text file where each line represents a single comparsion in the following format:
<probeID> <galleryID> <comparisonType>. The file also needs to contain a header: probe gallery type.

• <probeID>: The string representation of the probe sample’s canoncial id.
• <galleryID>: The string representation of the gallery sample’s canoncial id.
• <comparisontType>: g for genuine, i for impostor comparison.

Example:

    probe gallery type
    1_1_1_1 1_1_2_1 g
    1_2_1_1 1_2_2_1 g
    2_1_1_1 1_1_1_1 i
    2_1_1_1 1_2_2_1 i
     .
     .
     .

To use the comparison list file call the software with the -C my_comparison_list.txt,
for single database

  vpp -p path/to/data -s my_experiment_settings.xml -C my_comparison_list.txt -o outputdirectory 

or

  vpp --useDataStructureFile -p my_database_structure_file.txt -s my_experiment_settings.xml -C my_comparison_list.txt -o outputdirectory 

and in probe-gallery comparison mode with

  vpp -p path/to/data -s my_experiment_settings.xml -C my_comparison_list.txt -o outputdirectory 

or

  vpp --useDataStructureFile -p my_probe_db_structure_file.txt -g my_gallery_db_structure_file.txt -s my_experiment_settings.xml -C my_comparison_list.txt -o outputdirectory 

Test data and examples

Test databases

In the project’s root folder under testdata/dummy_databases there can be found two dummy databases (dummy_db_A and dummy_db_B) consisting of blank images representing some biometric sample images.
The script crate_database_structure_file.sh creates the database structure files for the dummy databases on your system.
There is also a comparison_list_dummy_db_A.txt as an example for a comparison list file for the dummy_db_A.

Dry-run

In the project’s root folder unter examples/dryrun you can find a settings file SettingDryRun.xml which basically creates a feature extraction pipeline with no operation (NOP), which passes the biometric samples through without processing them and creates a comparison module which only simulates the comparison process by assigning each comparison a score randomly drawn from two normal distributions (one representing the genuine the other the impostor score distribution). You can use these settings to test your configurations/databases/individual comparison list/etc. on a quick dry-run. The script vpp_dryrun.sh shows how to use it.

Further features:

• automatically generating settings files for executing a parameter grid search
• evaluating existing score files

See the documentation for mor information

Documentation

A more detailed documentation (in gitlab markdown format) is delivered with the software. The documentation is still under construction…

Contact

• Michael Linortner (Maintainer)