Command-Line Usage

Synopsis

The nfiq2 command-line tool has two main usage patterns:

nfiq2 [OPTIONS] path [path ...]

Basic Usage

Single Image

Process a single fingerprint image:

nfiq2 fingerprint.png

Output:

When processing a single image without -v or -q flags, only the quality score is printed (no CSV headers).

Multiple Images

Process multiple images with CSV output:

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

Command-Line Options

Output Options

-v

flag

Verbose output - Includes individual native quality measures computed during score calculation. These are the raw feature values before mapping to 0-100.

nfiq2 -v fingerprint.png

-b

flag

ISO/IEC 29794-1:2024 quality blocks - Provides quality component values mapped to [0-100] range. Required for inclusion in ISO/IEC 29794-1:2024 quality blocks.

nfiq2 -b fingerprint.png

-a

flag

Actionable quality feedback - Provides additional actionable feedback about each fingerprint image (e.g., contrast too low, insufficient foreground).

nfiq2 -a fingerprint.png

-q

flag

Speed/timing information - Displays elapsed time for computation of each native quality measure.

nfiq2 -q fingerprint.png

-o

string

Output file - Write all output to the specified file instead of stdout. Overwrites file if it exists.

nfiq2 -o results.csv image1.png image2.png

Input Options

-i

string

Explicit input argument - Allows explicit specification of input paths. Equivalent to providing paths directly.

nfiq2 -i image1.png -i /path/to/images/ image2.png

-f

string

Batch file - Plain text file where each line is a path to process. Multiple batch files can be specified.

nfiq2 -f batch1.txt -f batch2.txt

batch1.txt example:

/path/to/image1.png
/path/to/image2.wsq
/path/to/image3.jpg

-r

flag

Recursive directory scanning - Recursively search directories for images. Uses depth-first traversal.

nfiq2 -r /path/to/fingerprints/

Processing Options

-F

flag

Force processing - Automatically quantize and/or resample images that don’t meet requirements. Does not prompt for user input.

nfiq2 -F mixed_quality_images/

If resolution cannot be determined, -F assumes 500 PPI. This may produce incorrect scores for images with different resolutions.

-j

integer

Thread count - Number of worker threads for batch operations. One additional thread is spawned for coordinating output.

nfiq2 -j 8 -f large_batch.txt

If thread count exceeds physical cores, a warning prompts to confirm or adjust to match core count.

-m

string

Model information file - Path to alternative random forest parameters. Allows using custom trained models.

nfiq2 -m custom_model.txt fingerprint.png

Model file format:

Name = Custom Model Name
Description = Model trained on specific dataset
Trainer = Organization Name
Version = 1.0
Path = ./random_forest_params.xml
Hash = abc123def456...

If Path is relative, it must be relative to the directory containing the model file, not the current working directory.

Debug Options

-d

flag

Debug mode - Provides detailed information about program execution and computation steps.

nfiq2 -d fingerprint.png

Input Formats

Image Files

Supported image formats:

Standard Formats

BMP (.bmp)
JPEG (.jpg, .jpeg)
JPEG-LS (.jls)
PNG (.png)
TIFF (.tif, .tiff)
PBM/PGM/PPM (.pbm, .pgm, .ppm)

Forensic Formats

WSQ (.wsq) - FBI Wavelet Scalar Quantization
JPEG 2000 (.jp2, .j2k)

Biometric Records

ANSI/NIST-ITL
ISO/IEC 19794-4
RecordStores

ANSI/NIST-ITL 1-2007 and later (binary encoding)

Type 14 records (fingerprint images)
File extension typically .an2

nfiq2 record.an2

All Type 14 records within the file are processed separately.

ISO/IEC 19794-4 fingerprint image records

International fingerprint image standard
Binary format

nfiq2 fingerprint.iso

Biometric Evaluation Framework RecordStores

Directory-based storage format
Contains multiple fingerprint records

nfiq2 recordstore_directory

Can be processed with multi-threading:

nfiq2 -j 8 recordstore_directory

Directories

Process all supported files in a directory:

# Non-recursive (current directory only)
nfiq2 /path/to/fingerprints/

# Recursive (all subdirectories)
nfiq2 -r /path/to/fingerprints/

Batch Files

Batch files are plain text files with one path per line:

# batch.txt
/path/to/image1.png
/path/to/image2.wsq
/path/to/directory/
/path/to/recordstore/
image3.jpg

Process the batch file:

nfiq2 -f batch.txt

Paths in batch files can be absolute or relative to the current working directory.

Output Format

Standard CSV Output

Default output includes:

Column	Description
`Filename`	Path to the input image
`FingerCode`	Finger position code (if available)
`QualityScore`	Unified quality score (0-100)
`OptionalError`	Error message if processing failed
`Quantized`	`1` if image was quantized, `0` otherwise
`Resampled`	`1` if image was resampled, `0` otherwise

Example:

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

Verbose Output (-v)

Adds columns for each native quality measure:

Filename,FingerCode,QualityScore,...,FDA_Bin10_0,FDA_Bin10_1,...,RVUP_Bin10_StdDev
print1.wsq,0,45,...,0.234,0.156,...,12.34

Native quality measures are the raw feature values computed by individual quality assessment algorithms.

Quality Block Output (-b)

Adds columns for ISO/IEC 29794-1:2024 compliant quality component values (mapped to 0-100):

Filename,FingerCode,QualityScore,...,FDA_Bin10_0_Mapped,FDA_Bin10_1_Mapped,...
print1.wsq,0,45,...,23,15,...

Actionable Feedback (-a)

Adds columns with actionable quality feedback:

Filename,FingerCode,QualityScore,...,EmptyImageOrContrastTooLow,SufficientFingerprintForeground
print1.wsq,0,45,...,0,1

Actionable feedback flags:

EmptyImageOrContrastTooLow
UniformImage
SufficientFingerprintForeground
And more…

Timing Information (-q)

Adds columns showing elapsed time (in seconds) for each quality measure:

Filename,QualityScore,...,FDA_Time,FJFXPos_Time,RVUP_Time
print1.wsq,45,...,0.012,0.034,0.008

Combining Options

Options can be combined for powerful workflows:

# Get everything: verbose output, actionable feedback, timing, with multi-threading
nfiq2 -v -a -q -j 8 -f large_batch.txt -o results.csv

Exit Codes

The nfiq2 command returns standard exit codes:

Code	Meaning
`0`	Success - all images processed
`1`	Error - invalid arguments or processing failure

Individual image processing errors are reported in the OptionalError column and do not cause the program to exit with error code.

Performance Tips

Use Multi-threading

For batch operations, use -j with a thread count matching your CPU cores:

nfiq2 -j $(nproc) -f batch.txt  # Linux
nfiq2 -j %NUMBER_OF_PROCESSORS% -f batch.txt  # Windows

Optimize Output

Only request data you need. Avoid -v and -q unless necessary:

# Fast: only quality scores
nfiq2 large_batch.txt

# Slower: includes verbose metrics
nfiq2 -v -q large_batch.txt

Batch Similar Images

Group images by type and resolution in batch files for better cache performance.

Use RecordStores

For very large datasets, use BiometricEvaluation RecordStores instead of individual files for better I/O performance.

Troubleshooting

Images not meeting requirements

Problem: Warning about image not meeting 8-bit, 500 PPI requirementsSolution: Use the -F flag to automatically process:

nfiq2 -F image.png

Or manually convert images to 8-bit grayscale at 500 PPI before processing.

Thread count warning

Problem: Warning about thread count exceeding physical coresSolution: Reduce thread count to match CPU cores:

# Check CPU core count first
nproc  # Linux
sysctl -n hw.ncpu  # macOS

# Use appropriate thread count
nfiq2 -j 4 batch.txt

Resolution unknown warning

Problem: Image resolution cannot be determinedSolution: The -F flag will assume 500 PPI. Verify your images actually are 500 PPI, or convert them first:

# Using ImageMagick to set resolution
convert input.png -density 500 -units PixelsPerInch output.png

Out of memory errors

Problem: System runs out of memory during batch processingSolution: Reduce thread count or process in smaller batches:

# Reduce threads
nfiq2 -j 2 batch.txt

# Or split batch file
split -l 1000 large_batch.txt batch_part_
nfiq2 -f batch_part_aa -o results_aa.csv
nfiq2 -f batch_part_ab -o results_ab.csv

Next Steps

View Examples

See real-world usage examples with actual terminal output and results

Get Started

Core Concepts

Guides

CLI Tool

Building from Source

Command-Line Usage

Synopsis

Basic Usage

Single Image

Multiple Images

Command-Line Options

Output Options

Input Options

Processing Options

Debug Options

Input Formats

Image Files

Standard Formats

Forensic Formats

Biometric Records

Directories

Batch Files

Output Format

Standard CSV Output

Verbose Output (-v)

Quality Block Output (-b)

Actionable Feedback (-a)

Timing Information (-q)

Combining Options

Exit Codes

Performance Tips

Troubleshooting

Next Steps

View Examples

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

CLI Tool

Building from Source

Documentation Index

​Synopsis

​Basic Usage

​Single Image

​Multiple Images

​Command-Line Options

​Output Options

​Input Options

​Processing Options

​Debug Options

​Input Formats

​Image Files

Standard Formats

Forensic Formats

​Biometric Records

​Directories

​Batch Files

​Output Format

​Standard CSV Output

​Verbose Output (-v)

​Quality Block Output (-b)

​Actionable Feedback (-a)

​Timing Information (-q)

​Combining Options

​Exit Codes

​Performance Tips

​Troubleshooting

​Next Steps

View Examples

Build docs developers (and LLMs) love

Synopsis

Basic Usage

Single Image

Multiple Images

Command-Line Options

Output Options

Input Options

Processing Options

Debug Options

Input Formats

Image Files

Biometric Records

Directories

Batch Files

Output Format

Standard CSV Output

Verbose Output (-v)

Quality Block Output (-b)

Actionable Feedback (-a)

Timing Information (-q)

Combining Options

Exit Codes

Performance Tips

Troubleshooting

Next Steps