Embedding RF Parameters

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

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.

Build the Project

Compile NFIQ2 with the embedded parameters:

cmake --build . --config Release

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

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:

#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

#!/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

Get Started

Core Concepts

Guides

CLI Tool

Building from Source

Embedding RF Parameters

Overview

Benefits of Embedding

Simplified Deployment

Reduced Errors

Faster Initialization

Single Binary

Trade-offs

Building with Embedded Parameters

CMake Configuration

Build Steps

Using Embedded Models

Conditional Compilation

Checking if Model is Embedded

FRCT Codes

Build Examples

Standard Embedded Build

Cross-Platform Build Script

Example Application Makefile

Distribution Considerations

With Embedded Model

Without Embedded Model

Best Practices

Troubleshooting

Model Not Embedded

Binary Size Concerns

Next Steps

Computing Scores

Building from Source

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

CLI Tool

Building from Source

Documentation Index

​Overview

​Benefits of Embedding

Simplified Deployment

Reduced Errors

Faster Initialization

Single Binary

​Trade-offs

​Building with Embedded Parameters

​CMake Configuration

​Build Steps

​Using Embedded Models

​Conditional Compilation

​Checking if Model is Embedded

​FRCT Codes

​Build Examples

​Standard Embedded Build

​Cross-Platform Build Script

​Example Application Makefile

​Distribution Considerations

​With Embedded Model

​Without Embedded Model

​Best Practices

​Troubleshooting

​Model Not Embedded

​Binary Size Concerns

​Next Steps

Computing Scores

Building from Source

Build docs developers (and LLMs) love

Overview

Benefits of Embedding

Trade-offs

Building with Embedded Parameters

CMake Configuration

Build Steps

Using Embedded Models

Conditional Compilation

Checking if Model is Embedded

FRCT Codes

Build Examples

Standard Embedded Build

Cross-Platform Build Script

Example Application Makefile

Distribution Considerations

With Embedded Model

Without Embedded Model

Best Practices

Troubleshooting

Model Not Embedded

Binary Size Concerns

Next Steps