Embedding RF Parameters

How to embed Random Forest parameters directly in the NFIQ2 library

NFIQ2 supports two modes for loading Random Forest model parameters: runtime loading from a file, or embedding directly into the compiled library. This guide covers how to embed models for simplified deployment.

Overview

By default, NFIQ2 requires you to load Random Forest model parameters from an external file (e.g., nist_plain_tir-ink.txt) at runtime. However, you can embed these parameters directly into the library at build time using the EMBED_RANDOM_FOREST_PARAMETERS CMake option.

Benefits of Embedding

Simplified Deployment

No need to distribute separate model files alongside your application

Reduced Errors

Eliminates runtime errors from missing or incorrect model files

Faster Initialization

Skip file I/O during model loading

Single Binary

Everything needed is contained in one executable or library

Trade-offs

Embedding increases binary size and requires recompilation to update the model. Only embed if you need a fixed model version.

Building with Embedded Parameters

CMake Configuration

The embedding is controlled by CMake options in CMakeLists.txt:

# Option to enable embedding
option(EMBED_RANDOM_FOREST_PARAMETERS "Embed random forest parameters in library" OFF)

# Specify which model to embed (FRCT code)
set(EMBEDDED_RANDOM_FOREST_PARAMETER_FCT "0" CACHE STRING
    "ANSI/NIST-ITL 1-2011: Update 2015 friction ridge capture technology (FRCT) code for parameters to embed")

set(EMBEDDING_CMAKE_ARGS -DEMBEDDED_RANDOM_FOREST_PARAMETER_FCT=${EMBEDDED_RANDOM_FOREST_PARAMETER_FCT})
if(EMBED_RANDOM_FOREST_PARAMETERS)
    message(STATUS "Embedding random forest parameters")
    list(APPEND EMBEDDING_CMAKE_ARGS -DEMBED_RANDOM_FOREST_PARAMETERS=${EMBED_RANDOM_FOREST_PARAMETERS})
endif()

Build Steps

1. Configure CMake with Embedding Enabled

   Enable the embedding option when configuring your build:

   mkdir build && cd build
   cmake .. -DEMBED_RANDOM_FOREST_PARAMETERS=ON
   

   Optionally specify a different FRCT code:

   cmake .. \
     -DEMBED_RANDOM_FOREST_PARAMETERS=ON \
     -DEMBEDDED_RANDOM_FOREST_PARAMETER_FCT=0
   

   The default FRCT code is “0”, which corresponds to the standard NIST model for plain impressions.

2. Build the Project

   Compile NFIQ2 with the embedded parameters:

   cmake --build . --config Release
   

   During compilation, the model parameters will be embedded into the library.

3. Install (Optional)

   Install the compiled library and headers:

   cmake --build . --target install
   

Using Embedded Models

When the model is embedded, your application code becomes simpler:

With Embedded Model

#include <nfiq2.hpp>

int main() {
    // Simply instantiate the algorithm
    // No need to specify a model file!
    NFIQ2::Algorithm model {};
    
    // Verify the model is embedded
    if (!model.isEmbedded()) {
        std::cerr << "Model is not embedded.\n";
        return EXIT_FAILURE;
    }
    
    // Use the model normally
    NFIQ2::FingerprintImageData rawImage = /* ... */;
    
    std::vector<std::shared_ptr<NFIQ2::QualityMeasures::Algorithm>> algorithms =
        NFIQ2::QualityMeasures::computeNativeQualityMeasureAlgorithms(rawImage);
    
    unsigned int nfiq2 = model.computeUnifiedQualityScore(algorithms);
    std::cout << "Score: " << nfiq2 << '\n';
    
    return EXIT_SUCCESS;
}

Conditional Compilation

Write code that works with both embedded and runtime-loaded models:

#include <nfiq2.hpp>

int main(int argc, char **argv) {
    NFIQ2::Algorithm model {};
    
#if defined(NFIQ2_EMBEDDED_MODEL)
    // Embedded model path
    if (!model.isEmbedded()) {
        std::cerr << "Model is not embedded.\n";
        return EXIT_FAILURE;
    }
    std::cout << "Using embedded model\n";
#else
    // Runtime loading path
    if (argc != 2) {
        std::cerr << "Usage: program <model_file>\n";
        return EXIT_FAILURE;
    }
    
    NFIQ2::ModelInfo modelInfoObj {};
    try {
        modelInfoObj = NFIQ2::ModelInfo(argv[1]);
        model = NFIQ2::Algorithm(modelInfoObj);
    } catch (...) {
        std::cerr << "Could not load model\n";
        return EXIT_FAILURE;
    }
    std::cout << "Loaded model from: " << argv[1] << '\n';
#endif
    
    // Rest of your code...
    return EXIT_SUCCESS;
}

The NFIQ2_EMBEDDED_MODEL preprocessor macro is defined automatically when embedding is enabled.

Checking if Model is Embedded

At runtime, check if a model is embedded:

NFIQ2::Algorithm model {};

if (model.isEmbedded()) {
    std::cout << "Using embedded model\n";
} else {
    std::cout << "Model must be loaded from file\n";
}

FRCT Codes

The EMBEDDED_RANDOM_FOREST_PARAMETER_FCT option specifies which friction ridge capture technology model to embed:

FRCT Code	Description	Model File
0	Plain impression (default)	nist_plain_tir-ink.txt
2	Rolled impression	Contact NIST for model

Most applications should use FRCT code 0 (plain impressions). Other codes are for specialized capture scenarios.

Build Examples

Standard Embedded Build

mkdir build && cd build
cmake .. -DEMBED_RANDOM_FOREST_PARAMETERS=ON
cmake --build . --config Release

Cross-Platform Build Script

Linux/macOS

#!/bin/bash
set -e

BUILD_DIR="build-embedded"

rm -rf "${BUILD_DIR}"
mkdir -p "${BUILD_DIR}"
cd "${BUILD_DIR}"

cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DEMBED_RANDOM_FOREST_PARAMETERS=ON \
  -DBUILD_NFIQ2_CLI=ON

cmake --build . --config Release -j$(nproc)

echo "Build complete! Binary at: ${BUILD_DIR}/bin/nfiq2"

Example Application Makefile

If you’re building an application against an installed NFIQ2 library:

CXX = g++
CXXFLAGS = -std=c++11 -Wall -O2
INCLUDES = -I/usr/local/nfiq2/include
LDFLAGS = -L/usr/local/nfiq2/lib
LIBS = -lNfiq2Api -lNFIQ2Algorithm

myapp: myapp.cpp
	$(CXX) $(CXXFLAGS) $(INCLUDES) -o $@ $< $(LDFLAGS) $(LIBS)

clean:
	rm -f myapp

Distribution Considerations

With Embedded Model

✅ Advantages:

• Single executable/library to distribute
• No external files required
• Guaranteed model version

❌ Disadvantages:

• Larger binary size (~500KB increase)
• Model updates require recompilation
• Cannot switch models at runtime

Without Embedded Model

✅ Advantages:

• Smaller binaries
• Model updates without recompilation
• Runtime model selection

❌ Disadvantages:

• Must distribute model files separately
• Potential for missing/wrong model files
• More complex deployment

Best Practices

For End-User Applications

Embed the model for simplified distribution and reduced user error. End users shouldn’t need to manage model files.

For Development

Use runtime loading during development for flexibility. Switch between different models without rebuilding.

For Research

Use runtime loading to easily test and compare different model versions.

For Libraries

Provide both options: embedded for convenience, runtime loading for flexibility. Use conditional compilation to support both.

Troubleshooting

Model Not Embedded

NFIQ2::Algorithm model {};
if (!model.isEmbedded()) {
    std::cerr << "Model is not embedded.\n";
    return EXIT_FAILURE;
}

Solution: Verify CMake was configured with -DEMBED_RANDOM_FOREST_PARAMETERS=ON and rebuild completely.

Binary Size Concerns

If binary size is critical, use runtime loading:

cmake .. -DEMBED_RANDOM_FOREST_PARAMETERS=OFF

The embedded model adds approximately 500KB to the binary.

Next Steps

Computing Scores

Learn how to use your compiled library to compute quality scores

Building from Source

Detailed build instructions for all platforms