Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/usnistgov/NFIQ2/llms.txt

Use this file to discover all available pages before exploring further.

​
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

time nfiq2 -f large_batch.txt -o results.csv
Output:
real    15m32.123s
user    15m28.456s
sys     0m3.234s

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us