NFIQ 2 (NIST Fingerprint Image Quality)

NFIQ 2 has specific requirements for fingerprint images:

• Dimensions: After whitespace cropping, width must be between 197 and 799 pixels, and height must be between 197 and 999 pixels.
• Bit Depth: Must be 8-bit (max 255 shades of gray).
• Resolution: Must be 500 PPI.

If an image does not meet these requirements, nfiq2 normally requires user input. Using the -F (Force) flag allows the tool to automatically apply quantization and/or resampling to meet these qualifications without prompting the user. If the source resolution cannot be determined, -F assumes 500 PPI.

# Automatically quantize/resample images that don't meet 8-bit or 500 PPI requirements
nfiq2 -F mixedFingerprintDir

The diff.py script compares a user-generated NFIQ 2 CSV output against the expected output for version 2.3.0.

Command Syntax

python3 diff.py conformance_expected_output-v2.3.0.csv YOUR_NFIQ2_OUTPUT.csv [-o {differences.csv}] [-s]

Arguments

• conformance_expected_output-v2.3.0.csv: The reference CSV file provided in the repository.
• YOUR_NFIQ2_OUTPUT.csv: The CSV file generated by your NFIQ 2 implementation using the conformance dataset.

Options

• -o differences.csv: (Optional) Specifies a system path where any detected differences will be written to a CSV file.
• -s: (Optional) Instructs the script to print only True (if the files are identical) or False (if they differ).

When performing batch operations or processing RecordStores, you can speed up execution by spawning worker threads using the -j flag.

• -j <threads>: Specifies the number of worker threads.
• Note: This number can exceed the number of physical cores. If it does, a warning will appear asking if you want to proceed or revert to the number of physical cores. One additional thread is always spawned for coordinating output.

# Multi-threaded batch operation using 4 threads
nfiq2 -v -q -f batchFile1.txt -j 4

# Multi-threaded RecordStore processing using 8 threads
nfiq2 -j 8 recordStore1

You can process large sets of images using batch files or directory scanning:

• Batch Files: Use the -f flag to provide a plain text file where each line is a path to an image. nfiq2 will process these sequentially.
• Directory Recursion: Use the -r flag to perform a depth-first recursive scan of a directory to find all identifiable fingerprints.
• Explicit Arguments: Use the -i flag to pass explicit image, record, directory, or RecordStore arguments, which is equivalent to providing them directly as positional arguments.

# Recursively scan a directory and save output to a CSV
nfiq2 -r fingerprintDir

# Process a batch file
nfiq2 -f batchFile1.txt

# Combine multiple argument types (files, directories, and explicit paths) and save to file
nfiq2 -r -i print1.tif -i fingerprintDir -o output.csv print2.jpg print3.bmp

To ensure that the scores generated by your example_api run are consistent with expected results, compare your output against the reference files located in the output directory using the diff command. If the diff command returns no output, the scores are identical.

$ diff SFinGe_Test_0X_output.txt Your_SFinGe_Test_0X_output.txt

To build both the library and the standalone command-line executable, follow these steps.

Important: You must use --recursive when cloning to ensure all git submodules are retrieved. Do not use the GitHub ZIP download.

# Clone the repository with submodules
git clone --recursive https://github.com/usnistgov/NFIQ2.git
cd NFIQ2

# Create build directory and configure
mkdir build
cd build
cmake ..

# Build
cmake --build .

To build only the NFIQ 2 library (without the command-line interface), follow these steps.

Important: You must use --recursive when cloning to ensure all git submodules are retrieved. Do not use the GitHub ZIP download.

# Clone the repository with submodules
git clone --recursive https://github.com/usnistgov/NFIQ2.git
cd NFIQ2

# Create build directory and configure with CLI disabled
mkdir build
cd build
cmake .. -DBUILD_NFIQ2_CLI=OFF

# Build
cmake --build .

To verify that your NFIQ 2 implementation conforms to the ISO/IEC 29794-4 standard, use the tools provided in the conformance/ directory.

Important: The images required for the conformance dataset are not included in this repository due to licensing. You must download the conformance dataset from the NIST website before testing.

Prerequisites

• Python 3
• Pandas v1.1.0 or greater
• An NFIQ 2 output CSV file generated from the conformance dataset.

For processing large volumes of data, nfiq2 supports batch files and multi-threading.

Batch Files

Use the -f <batchfile> flag to process a list of paths. A batch file is a plain text file where each line contains the path to a file to be processed.

Multi-threading

Use the -j <threads> flag to specify the number of worker threads for batch or RecordStore operations. Note that one additional thread is used for coordinating output.

Example: Multi-threaded Batch Processing

To process a batch file using 4 threads with detailed quality measures and timing:

nfiq2 -v -q -f batchFile1.txt -j 4