CLI Examples

Real-world examples of using the NFIQ2 command-line tool with actual output

Basic Examples

Single Image Processing

Process a single fingerprint image:

nfiq2 print1.wsq

Output:

50

When processing a single image without additional flags, only the quality score is output (no CSV headers).

Multiple Images

Process multiple images in one command:

nfiq2 print1.wsq print2.png print3.jpg

Output:

Filename,FingerCode,QualityScore,OptionalError,Quantized,Resampled
print1.wsq,0,45,,0,0
print2.png,0,67,,0,0
print3.jpg,0,52,,0,0

The CSV format makes it easy to import into spreadsheets or data analysis tools.

Directory Processing

Process Directory (Non-Recursive)

Process all fingerprint images in a single directory:

nfiq2 fingerprintDir

Output:

Filename,FingerCode,QualityScore,OptionalError,Quantized,Resampled
fingerprintDir/sample1.png,0,58,,0,0
fingerprintDir/sample2.wsq,0,72,,0,0
fingerprintDir/sample3.tif,0,41,,0,0
fingerprintDir/sample4.jpg,0,65,,0,0

Without the -r flag, only files in the specified directory are processed (no subdirectories).

Recursive Directory Processing

Recursively search through all subdirectories:

nfiq2 -r fingerprintDir

Output:

Filename,FingerCode,QualityScore,OptionalError,Quantized,Resampled
fingerprintDir/sample1.png,0,58,,0,0
fingerprintDir/subfolder/sample2.wsq,0,72,,0,0
fingerprintDir/subfolder/deep/sample3.tif,0,41,,0,0
fingerprintDir/another/sample4.jpg,0,65,,0,0

Useful for processing large datasets organized in subdirectories.

Output Options

Save to File

Redirect output to a CSV file:

nfiq2 -r -i print1.tif -i fingerprintDir -o output.csv print2.jpg print3.bmp

Result:

• Creates output.csv in the current directory
• Processes: print1.tif, all images in fingerprintDir (recursively), print2.jpg, and print3.bmp
• Overwrites output.csv if it exists

Combining the -i flag with direct arguments and the -o flag allows flexible input specifications with organized output.

Verbose Output

Include native quality measures:

nfiq2 -v fingerprint.png

Output:

Filename,FingerCode,QualityScore,OptionalError,Quantized,Resampled,FDA_Bin10_0,FDA_Bin10_1,FDA_Bin10_2,...,RVUP_Bin10_StdDev
fingerprint.png,0,58,,0,0,0.234,0.156,0.089,...,12.34

The verbose output includes all native quality measure values used to compute the overall score.

Verbose with Timing

Show native quality measures and their computation time:

nfiq2 -v -q fingerprintDir

Output:

Filename,FingerCode,QualityScore,...,FDA_Bin10_0,FDA_Time,...,RVUP_Bin10_StdDev,RVUP_Time
fingerprintDir/sample1.png,0,58,...,0.234,0.012,...,12.34,0.008
fingerprintDir/sample2.wsq,0,72,...,0.445,0.011,...,8.91,0.007

Timing values are in seconds and represent the elapsed time for each quality measure computation.

Force Processing

Handle Non-Compliant Images

Automatically process images that don’t meet requirements:

nfiq2 -F mixedFingerprintDir

Output:

Filename,FingerCode,QualityScore,OptionalError,Quantized,Resampled
mixedFingerprintDir/16bit.tif,0,52,,1,0
mixedFingerprintDir/300dpi.png,0,61,,0,1
mixedFingerprintDir/valid.wsq,0,73,,0,0
mixedFingerprintDir/both.jpg,0,48,,1,1

The Quantized and Resampled columns indicate which transformations were applied:

• Quantized=1: Image was converted to 8-bit grayscale
• Resampled=1: Image was resampled to 500 PPI

Batch File Processing

Create a Batch File

Create a text file listing images to process:

batchFile1.txt:

/data/fingerprints/set1/image1.png
/data/fingerprints/set1/image2.wsq
/data/fingerprints/set2/image3.jpg
/data/fingerprints/set2/image4.tif
./local/image5.png

Process Batch File

nfiq2 -f batchFile1.txt

Output:

Filename,FingerCode,QualityScore,OptionalError,Quantized,Resampled
/data/fingerprints/set1/image1.png,0,58,,0,0
/data/fingerprints/set1/image2.wsq,0,72,,0,0
/data/fingerprints/set2/image3.jpg,0,41,,0,0
/data/fingerprints/set2/image4.tif,0,65,,0,0
./local/image5.png,0,50,,0,0

Multi-Threaded Batch Processing

Process large batches with multiple threads:

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

1. Load batch file

   Reads all paths from batchFile1.txt

2. Spawn worker threads

   Creates 4 worker threads for parallel processing

3. Coordinate output

   One additional thread coordinates CSV output

4. Process in parallel

   Images are distributed across threads for faster processing

Output: Same CSV format, but processing completes approximately 4× faster on a multi-core system.

For optimal performance, set thread count to match your CPU core count:

# Linux: Use nproc
nfiq2 -j $(nproc) -f batch.txt

# macOS: Use sysctl
nfiq2 -j $(sysctl -n hw.ncpu) -f batch.txt

RecordStore Processing

Process RecordStore

Biometric Evaluation Framework RecordStores are directory-based storage formats:

nfiq2 recordStore1

Output:

Filename,FingerCode,QualityScore,OptionalError,Quantized,Resampled
recordStore1/0001,2,62,,0,0
recordStore1/0002,7,71,,0,0
recordStore1/0003,2,55,,0,0
recordStore1/0004,9,48,,0,0

FingerCode values represent the finger position (e.g., 2 = right index, 7 = left index).

Multi-Threaded RecordStore

Process large RecordStores efficiently:

nfiq2 -j 8 recordStore1

Output: Same format, but processes 8 records simultaneously for significantly faster throughput.

Performance comparison:

# Single-threaded: ~1000 records/minute
nfiq2 recordStore1

# Multi-threaded (8 cores): ~7000 records/minute
nfiq2 -j 8 recordStore1

Actionable Feedback

Get Quality Feedback

Obtain actionable quality feedback for each image:

nfiq2 -a fingerprint_samples/

Output:

Filename,FingerCode,QualityScore,...,EmptyImageOrContrastTooLow,UniformImage,SufficientFingerprintForeground
samples/good.png,0,78,...,0,0,1
samples/low_contrast.png,0,25,...,1,0,0
samples/uniform.png,0,15,...,0,1,0
samples/partial.png,0,42,...,0,0,0

Interpretation:

• good.png: High quality (78), sufficient foreground
• low_contrast.png: Low quality (25), contrast issue detected
• uniform.png: Very low quality (15), image too uniform
• partial.png: Medium quality (42), insufficient foreground area

Use actionable feedback for quality control and to identify specific issues with problematic images.

ISO/IEC 29794-1 Quality Blocks

Generate Compliant Output

Produce quality component values for ISO/IEC 29794-1:2024 quality blocks:

nfiq2 -b fingerprint.png

Output:

Filename,FingerCode,QualityScore,...,FDA_Bin10_0_Mapped,FDA_Bin10_1_Mapped,...
fingerprint.png,0,58,...,23,15,...

The _Mapped columns contain values scaled to [0-100] range, suitable for inclusion in ISO/IEC 29794-1:2024 quality blocks.

Custom Model Parameters

Using Alternative Models

Test with custom-trained random forest parameters:

custom_model.txt:

Name = Custom Optical Scanner Model
Description = Trained on optical scanner dataset
Trainer = Research Lab XYZ
Version = 1.2
Path = ./models/optical_rf_params.xml
Hash = a1b2c3d4e5f6...

nfiq2 -m custom_model.txt test_images/

Output:

Filename,FingerCode,QualityScore,OptionalError,Quantized,Resampled
test_images/optical1.png,0,64,,0,0
test_images/optical2.png,0,71,,0,0
test_images/optical3.png,0,52,,0,0

Custom models must be compatible with NFIQ2’s feature extraction pipeline. The Path in the model file must point to a valid OpenCV random forest XML file.

Processing ANSI/NIST Records

Extract and Process Type 14 Records

nfiq2 print3.an2

Output:

Filename,FingerCode,QualityScore,OptionalError,Quantized,Resampled
print3.an2:14:1,2,58,,0,0
print3.an2:14:2,7,72,,0,0
print3.an2:14:3,3,45,,0,0

Each Type 14 record in the ANSI/NIST file is processed separately. The filename shows:

• print3.an2 - Original file
• :14: - Record type (Type 14)
• 1, 2, 3 - Record sequence number

Advanced Workflows

Quality Control Pipeline

Comprehensive quality assessment with all metrics:

nfiq2 -a -b -v -F -j 4 -o qc_report.csv /data/enrollment_scans/

This command:

• -a - Adds actionable feedback
• -b - Includes ISO quality block values
• -v - Provides all native quality measures
• -F - Forces processing of non-compliant images
• -j 4 - Uses 4 threads for speed
• -o qc_report.csv - Saves comprehensive report

Result: Complete quality control report with:

• Unified quality scores
• Actionable feedback flags
• ISO-compliant quality components
• All native quality measures
• Processing status (quantized/resampled)

Production Batch Processing

Efficient processing for large-scale operations:

Terminal

# Process overnight batch with optimal settings
nfiq2 -F -j $(nproc) -f overnight_batch.txt -o results_$(date +%Y%m%d).csv

Features:

• Automatic handling of non-compliant images (-F)
• Maximum parallelization (-j $(nproc))
• Date-stamped output file
• Batch file for organized input

Comparing Processing Speed

Single-threaded

time nfiq2 -f large_batch.txt -o results.csv

Output:

real    15m32.123s
user    15m28.456s
sys     0m3.234s

Multi-threaded (4 cores)

time nfiq2 -j 4 -f large_batch.txt -o results.csv

Output:

real    4m15.678s
user    16m12.345s
sys     0m8.123s

Speed improvement: ~3.7× faster

Multi-threaded (8 cores)

time nfiq2 -j 8 -f large_batch.txt -o results.csv

Output:

real    2m28.234s
user    18m45.678s
sys     0m12.456s

Speed improvement: ~6.3× faster

Handling Errors

Processing with Errors

When some images fail to process:

nfiq2 mixed_quality/

Output:

Filename,FingerCode,QualityScore,OptionalError,Quantized,Resampled
mixed_quality/good1.png,0,58,,0,0
mixed_quality/corrupted.jpg,0,,"Failed to decode image",0,0
mixed_quality/good2.wsq,0,72,,0,0
mixed_quality/too_small.png,0,,"Image dimensions too small",0,0
mixed_quality/good3.tif,0,65,,0,0

Errors are reported in the OptionalError column. The program continues processing remaining images.

Debug Mode

Investigate processing issues:

nfiq2 -d problematic_image.png

Output:

[DEBUG] Loading image: problematic_image.png
[DEBUG] Image dimensions: 512x512
[DEBUG] Resolution: 500 PPI
[DEBUG] Bit depth: 8
[DEBUG] Computing FDA features...
[DEBUG] Computing FJFXPos features...
[DEBUG] Computing RVUP features...
[DEBUG] Aggregating quality score...
[DEBUG] Final score: 58
58

Scripting Examples

Bash Script: Process Multiple Batches

script.sh

#!/bin/bash

# Process multiple batch files with timestamped outputs
for batch in batch_*.txt; do
    timestamp=$(date +%Y%m%d_%H%M%S)
    output="results_${batch%.txt}_${timestamp}.csv"
    
    echo "Processing $batch..."
    nfiq2 -F -j 4 -f "$batch" -o "$output"
    
    # Count processed images
    count=$(wc -l < "$output")
    echo "Processed $((count - 1)) images to $output"
done

echo "All batches complete!"

Python Script: Parse NFIQ2 Output

parse_results.py

import csv
import sys

def analyze_quality_scores(csv_file):
    """Analyze NFIQ2 output and generate statistics."""
    scores = []
    errors = 0
    
    with open(csv_file, 'r') as f:
        reader = csv.DictReader(f)
        for row in reader:
            if row['OptionalError']:
                errors += 1
            elif row['QualityScore']:
                scores.append(int(row['QualityScore']))
    
    if scores:
        avg = sum(scores) / len(scores)
        print(f"Total images: {len(scores) + errors}")
        print(f"Successful: {len(scores)}")
        print(f"Failed: {errors}")
        print(f"Average quality: {avg:.2f}")
        print(f"Min quality: {min(scores)}")
        print(f"Max quality: {max(scores)}")
    else:
        print("No valid quality scores found.")

if __name__ == '__main__':
    if len(sys.argv) != 2:
        print(f"Usage: {sys.argv[0]} <nfiq2_output.csv>")
        sys.exit(1)
    
    analyze_quality_scores(sys.argv[1])

Usage:

# Generate scores
nfiq2 -o scores.csv fingerprints/

# Analyze results
python parse_results.py scores.csv

Output:

Total images: 1000
Successful: 987
Failed: 13
Average quality: 62.34
Min quality: 12
Max quality: 98

Best Practices

Organize Input

Use batch files for large datasets:

find /data/fingerprints -name "*.png" > batch.txt
nfiq2 -j 8 -f batch.txt -o results.csv

Use Force Mode

Avoid prompts in automated workflows:

nfiq2 -F -f batch.txt

Multi-threading

Match CPU cores for best performance:

nfiq2 -j $(nproc) -f batch.txt

Save Output

Always save to file for later analysis:

nfiq2 -o results_$(date +%F).csv -f batch.txt

Next Steps

Library API

Integrate NFIQ2 into your applications

Quality Features

Learn about the quality measures