readme.md

NFIQ2 on docker
===============

This docker image provide a compilation environement for the NIST Finger Image Quality 2 (NFIQ2) software developped by the NIST (for more information regarding the NFIQ2, see the [offical website](https://www.nist.gov/services-resources/software/development-nfiq-20) or the [github repo](https://github.com/usnistgov/NFIQ2)).

## How to build
The building process is very simple. First, install [docker](https://get.docker.com/).
The second step is to run this docker image as follow:

    docker build -t nfiq2 .

This command will produce a docker image with the compiled binaris in the `/NFIQ2/NFIQ2/bin/NFIQ2` folder.

## How to use

Since the docker image is separate of the host system, to run the NFIQ2 script on data present on the host, we have to share a volume while starting the docker image:

    docker run -it -v <host folder>:/data nfiq2 bash

It also possible to run directly the `NFIQ2` script from the host without having to type the commands in the docker-image bash:
    
    mdedonno@dockerdev:/mnt/hgfs/D/Library/docker-NFIQ2/src$ docker run -it -v $(pwd):/data nfiq2 /NFIQ2/NFIQ2/bin/NFIQ2
    USAGE:
      NFIQ2 <runMode> [specific run mode arguments]
      <runMode>: run mode of NFIQ2 tool, possible values
                  SINGLE, BATCH
    
      run mode SINGLE:
      ----------------
      NFIQ2 SINGLE <fingerprintImage> <imageFormat> <outputFeatureData> <outputSpeed>
    
        <fingerprintImage>: path and filename to a fingerprint image
        <imageFormat>: one of following values describing the fingerprint image format
                  BMP, WSQ
        <outputFeatureData>: if to print computed quality feature values
                 true, false
        <outputSpeed>: if to print speed of quality feature computation
                 true, false
    
      run mode BATCH:
      ---------------
      NFIQ2 BATCH <fingerprintImageList> <imageFormat> <resultList> <outputFeatureData> <outputSpeed> [<speedResultList>]
    
        <fingerprintImageList>: path and filename to a list of fingerprint images
        <imageFormat>: one of following values describing the fingerprint image format of all images in the input list
                  BMP, WSQ
        <resultList>: path and filename of the CSV output file that will contain NFIQ2 values and (optional) feature values
        <outputFeatureData>: if to add computed quality feature values to the resulting CSV output file
                 true, false
        <outputSpeed>: if to compute the speed of NFIQ2 computation
                 true, false
        <speedResultList>: path and filename of another CSV output file that will contain the NFIQ2 speed values (optional argument, only applied if outputSpeed = true)

## Export the executable to an other docker image

To use only the compiled binaries into an other docker-image, it is possible to use a two-stage docker image (as this one), changing the `Running environnement` as needed, or export a tar version with only the compiled binaries:

    docker run -it -v $(pwd):/data nfiq2 tar -zcvf /data/NFIQ2-linux-x84_64.tgz /NFIQ2

The tar file can the be used with the following `Dockerfile` image:

    FROM centos
    ADD NFIQ2-linux-x84_64.tgz /
    ENV LD_LIBRARY_PATH=/NFIQ2/libOpenCV/lib:/NFIQ2/biomdi/common/lib:/NFIQ2/biomdi/fingerminutia/lib