Building with CLI

How to build the NFIQ 2 library and command-line interface

Building NFIQ 2 with the command-line interface provides a standalone executable for quality assessment, along with the library for integration.

The CLI build requires additional system dependencies from libbiomeval. Ensure you have installed all required system packages before proceeding.

Quick Build

1. Clone the repository

   Clone recursively to include all git submodules:

   git clone --recursive https://github.com/usnistgov/NFIQ2.git
   cd NFIQ2
   
2. Install system dependencies

   Install required packages for libbiomeval:

   Ubuntu/Debian

   sudo apt-get install build-essential cmake libdb++-dev \
     libhwloc-dev libjbig-dev libjpeg-dev libopenjp2-7-dev \
     liblzma-dev libpng-dev libsqlite3-dev libssl-dev \
     libtiff-dev libzstd-dev zlib1g-dev
   

   macOS

   sudo port install berkeley-db cmake hwloc jpeg openjpeg \
     libpng openssl sqlite3 tiff xz zlib zstd
   

   Windows

   vcpkg install berkeleydb:x64-windows-static \
     hwloc:x64-windows-static libjpeg-turbo:x64-windows-static \
     openjpeg:x64-windows-static libpng:x64-windows-static \
     openssl:x64-windows-static sqlite3:x64-windows-static \
     tiff:x64-windows-static zlib:x64-windows-static \
     zstd:x64-windows-static
   
3. Create build directory

   mkdir build
   cd build
   
4. Configure with CMake

   The CLI is built by default when BUILD_NFIQ2_CLI is not specified:

   Linux/macOS

   cmake ..
   
5. Build the library and CLI

   Linux/macOS

   cmake --build .
   

Build Configuration

Explicitly Enable CLI

While the CLI is built by default, you can explicitly enable it:

cmake .. -DBUILD_NFIQ2_CLI=ON

Build Type

Release

cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .

Platform-Specific Builds

Windows with Visual Studio

Windows builds require vcpkg to manage libbiomeval dependencies:

# 64-bit Release build
cmake .. ^
  -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake ^
  -DVCPKG_TARGET_TRIPLET=x64-windows-static ^
  -DCMAKE_CONFIGURATION_TYPES=Release ^
  -A x64

cmake --build . --config Release

# 32-bit Release build
cmake .. ^
  -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake ^
  -DVCPKG_TARGET_TRIPLET=x86-windows-static ^
  -DCMAKE_CONFIGURATION_TYPES=Release ^
  -A Win32

cmake --build . --config Release

Adjust the vcpkg path (C:\vcpkg\) to match your installation location.

macOS Universal Binary

To build a universal binary that runs on both Intel and Apple Silicon:

1. Install universal dependencies

   Ensure all MacPorts dependencies are universal:

   sudo port install berkeley-db +universal hwloc +universal \
     jpeg +universal openjpeg +universal libpng +universal \
     openssl +universal sqlite3 +universal tiff +universal \
     xz +universal zlib +universal zstd +universal
   
2. Configure for both architectures

   cmake .. -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"
   
3. Build

   cmake --build .
   

All dependencies must be built universally. Mixing architectures will cause linker errors.

Linux

Standard build on Linux:

cmake ..
cmake --build .

For distribution packages:

cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
cpack

Build Output

After a successful build, you’ll find:

Executables

• CLI: build/NFIQ2/NFIQ2Algorithm/nfiq2 (Linux/macOS) or build\NFIQ2\NFIQ2Algorithm\Release\nfiq2.exe (Windows)

Libraries

• NFIQ 2 API: libNfiq2Api.a / Nfiq2Api.lib
• NFIQ 2 Algorithm: libNfiq2Algorithm.a / Nfiq2Algorithm.lib
• OpenCV: OpenCV libraries in build/OpenCV-prefix/
• FingerJetFX: libFRFXLL.a / FRFXLL.lib
• libbiomeval: libbiomeval.a / biomeval.lib
• NFIR: libnfir.a / nfir.lib

Data Files

Random forest model parameters (if not embedded):

• build/NFIQ2/NFIQ2Algorithm/share/nfiq2/nist_plain_tir-ink.txt

Testing the Build

Verify the CLI executable works:

Linux/macOS

./NFIQ2/NFIQ2Algorithm/nfiq2 --version

Test with a sample fingerprint image:

./NFIQ2/NFIQ2Algorithm/nfiq2 -i path/to/fingerprint.png

Installation

Install the built binaries and libraries:

Linux/macOS

sudo cmake --install .

Default installation locations:

• Linux/macOS: /usr/local/nfiq2/
• Windows: C:\Program Files\NFIQ2\

Custom Installation Prefix

cmake .. -DCMAKE_INSTALL_PREFIX=/opt/nfiq2
cmake --build .
sudo cmake --install .

Creating Distribution Packages

CMake can generate platform-specific installers:

macOS (.pkg)

cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
cpack -G productbuild

Output: nfiq2-{version}-macos-{os_version}-{arch}.pkg

Windows (.msi)

Install WiX Toolset, then:

cmake .. -DCMAKE_CONFIGURATION_TYPES=Release -A x64
cmake --build . --config Release
cpack -G WIX -C Release

Output: nfiq2-{version}-win64.msi

Debian (.deb)

cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
cpack -G DEB

Output: nfiq2_{version}-1_{arch}.deb

Red Hat (.rpm)

cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
cpack -G RPM

Output: nfiq2-{version}-1.el{version}.{arch}.rpm

Troubleshooting

libbiomeval Dependencies Not Found

Ensure all system packages are installed. On Ubuntu:

sudo apt-get install libdb++-dev libssl-dev libsqlite3-dev

OpenSSL Not Found (macOS)

Specify the OpenSSL root directory:

cmake .. -DOPENSSL_ROOT_DIR=/opt/local

vcpkg Triplet Mismatch (Windows)

Ensure the triplet matches your target architecture:

# For 64-bit static linking
-DVCPKG_TARGET_TRIPLET=x64-windows-static

# For 32-bit static linking
-DVCPKG_TARGET_TRIPLET=x86-windows-static

Next Steps

CLI Usage

Learn how to use the NFIQ 2 command-line interface

Platform Notes

Platform-specific build details and limitations