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.

​
What is the NFIQ2 CLI?

The NFIQ2 command-line interface (nfiq2) is a standalone executable tool for computing ISO/IEC 29794-4:2024 unified quality scores for 500 PPI ink and live scan plain impression fingerprint images. It serves as a reference implementation of the international standard and provides a fast, efficient way to assess fingerprint image quality from the terminal.

​
Key Features

  • Batch Processing: Process multiple images, directories, or RecordStores in a single command
  • Multi-threading: Utilize multiple CPU cores for faster processing of large datasets
  • Multiple Input Formats: Support for common image formats (BMP, JPEG, PNG, TIFF, WSQ, etc.) and biometric standards
  • CSV Output: Machine-readable output format for easy integration with data pipelines
  • Quality Feedback: Optional actionable feedback and detailed quality metrics
  • Flexible Configuration: Custom model parameters and output options
The CLI tool outputs scores in CSV format by default, making it ideal for batch processing and automated workflows.

​
When to Use the CLI vs. Library

​
Use the CLI Tool When:

  • Batch processing multiple fingerprint images
  • Processing entire directories or RecordStores
  • Running quality checks from scripts or automation pipelines
  • Performing one-time quality assessments
  • Testing or evaluating NFIQ2 capabilities
  • You need CSV output for downstream analysis

​
Use the Library When:

  • Integrating NFIQ2 into your own application
  • Building real-time quality assessment systems
  • You need programmatic access to quality features
  • Custom integration with your existing codebase
  • Mobile or embedded platform deployment
  • You require fine-grained control over the quality assessment process
For development and testing, the CLI tool is faster to get started with. For production systems that need to integrate quality assessment into an application workflow, use the library API.

​
Supported Input Formats

The NFIQ2 CLI supports a wide range of input formats:

Image Formats

  • BMP
  • JPEG / JPEG-LS
  • JPEG 2000
  • PBM/PGM/PPM
  • PNG
  • TIFF
  • WSQ

Biometric Standards

  • ANSI/NIST-ITL 1-2007+ (Type 14)
  • ISO/IEC 19794-4
  • Biometric Evaluation Framework RecordStores

​
Image Requirements

NFIQ2 has specific requirements for input images. Images that don’t meet these requirements can be automatically processed with the -F (Force) flag.

​
Required Specifications

RequirementValueNotes
Resolution500 PPICan be resampled automatically with -F
Color Depth8-bit grayscaleMaximum 255 shades of gray
Width196-800 pixelsAfter whitespace cropping
Height196-1000 pixelsAfter whitespace cropping

​
Automatic Processing

When using the -F (Force) flag, NFIQ2 will automatically:
  • Quantize images with incorrect bit depth to 8-bit grayscale
  • Resample images to 500 PPI when source resolution is known
  • Assume 500 PPI if resolution cannot be determined

​
Building the CLI Tool

Unless you are actively developing NFIQ2, we highly recommend downloading pre-built binaries from GitHub Releases instead of building from source.

​
Prerequisites

Building the CLI requires additional dependencies beyond the library:
1

Core Dependencies

  • CMake 3.3 or higher
  • C++11 compatible compiler
  • Git (for submodule cloning)
2

Library Dependencies

  • OpenCV 4 (bundled as submodule)
  • FingerJetFX OSE (bundled as submodule)
  • digestpp (bundled as submodule)
3

CLI-Specific Dependencies

​
Build Instructions

You must recursively clone the repository to retrieve all git submodules. Do not use the GitHub ZIP file download.
# Clone repository with submodules
git clone --recursive https://github.com/usnistgov/NFIQ2.git
cd NFIQ2

# Install libbiomeval dependencies (Ubuntu/Debian example)
sudo apt-get install libdb++-dev libsqlite3-dev \
  libjpeg-dev libpng-dev libtiff-dev libopenjp2-7-dev \
  zlib1g-dev libssl-dev

# Create build directory
mkdir build && cd build

# Configure with CLI enabled (default)
cmake ..

# Build
cmake --build .

​
Build Options

Control the build with these CMake options:
OptionDefaultDescription
BUILD_NFIQ2_CLIONBuild the command-line interface
EMBED_RANDOM_FOREST_PARAMETERSOFFEmbed model parameters into the library
EMBEDDED_RANDOM_FOREST_PARAMETER_FCT0Friction ridge capture technology code for embedded parameters
cmake .. -DBUILD_NFIQ2_CLI=OFF
cmake --build .

​
Installation

After building, the nfiq2 executable will be located in the build directory:
  • Linux/macOS: build/bin/nfiq2
  • Windows: build\bin\Release\nfiq2.exe
You can install it system-wide using: 
# Linux/macOS
sudo cmake --install .

# This installs to /usr/local/nfiq2/bin/nfiq2
# A symlink is created at /usr/local/bin/nfiq2
On Linux/macOS, the installer creates a symlink at /usr/local/bin/nfiq2 for easy access from anywhere.

​
Quick Start

Once installed or built, test the CLI tool: 
# Process a single image
./nfiq2 fingerprint.png

# Process multiple images with verbose output
./nfiq2 -v image1.png image2.wsq image3.tif

# Process a directory with multi-threading
./nfiq2 -j 4 /path/to/fingerprints/

​
Next Steps

Usage Guide

Learn about command-line options and syntax

Examples

See real-world usage examples with output

Build docs developers (and LLMs) love

Get started for freeTalk to us