OpenPhysical.Biometrics.NFIQ1 1.0.1

dotnet add package OpenPhysical.Biometrics.NFIQ1 --version 1.0.1
                    
NuGet\Install-Package OpenPhysical.Biometrics.NFIQ1 -Version 1.0.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OpenPhysical.Biometrics.NFIQ1" Version="1.0.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="OpenPhysical.Biometrics.NFIQ1" Version="1.0.1" />
                    
Directory.Packages.props
<PackageReference Include="OpenPhysical.Biometrics.NFIQ1" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add OpenPhysical.Biometrics.NFIQ1 --version 1.0.1
                    
#r "nuget: OpenPhysical.Biometrics.NFIQ1, 1.0.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package OpenPhysical.Biometrics.NFIQ1@1.0.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=OpenPhysical.Biometrics.NFIQ1&version=1.0.1
                    
Install as a Cake Addin
#tool nuget:?package=OpenPhysical.Biometrics.NFIQ1&version=1.0.1
                    
Install as a Cake Tool

OpenPhysical.Biometrics.NFIQ

Assess fingerprint image quality from .NET 10, using NIST's original NFIQ algorithm and NFIQ 2.3.0.

A fingerprint reader can produce several impressions of the same finger. This library helps an enrollment application assess those captures, choose an image to retain, and explain when another impression would help. Each assessment keeps the algorithm's original quality scale and outcome.

The shared package version is 1.0.1, a stable maintenance release. Packages are published under the OpenPhysical NuGet organization. The links below show the current publication status; a release becomes installable only after the publishing workflow and NuGet validation finish.

NFIQ1 on NuGet NFIQ2 on NuGet

Choose the package that fits your workflow:

  • OpenPhysical.Biometrics.NFIQ1 returns a class from 1 to 5, with 1 best, together with the original classifier confidence and capture status.
  • OpenPhysical.Biometrics.NFIQ2 returns a score from 0 to 100, with higher values indicating better predicted recognition performance. Each engine loads and reuses the NFIQ 2.3.0 optical/ink random-forest model.

Built from NIST's reference code

We started with NIST's original NBIS 5.0.0 NFIQ source and the NFIQ 2.3.0 release, then adapted them for .NET applications. The algorithms still run in native C and C++. A C# API accepts grayscale pixels directly and returns typed results in the same process.

Our additions handle input validation, memory cleanup, concurrent calls, native library loading, and .NET integration. The original NIST files are preserved unmodified in the first Git commit. Build-time adaptations stay separate, so their purpose and effect can be reviewed against that starting point.

The provenance record identifies the source checksums, dependency versions and adaptations. The changelog records changes to the .NET library.

Where it fits in PIV

Personal Identity Verification (PIV) enrollment starts with fingerprint captures. An enrollment application assesses each impression, selects the captures to use, and carries their quality information into the biometric record.

The PIV minutiae profile uses original NFIQ classes. Its image-quality value is 20 * (6 - qualityClass), so NFIQ class 1 becomes 100 and class 5 becomes 20. NFIQ2 provides its own quality measurement for acquisition and capture-selection workflows. Keep both measurements with their algorithm versions when storing assessment results.

Using the libraries

Install either or both packages once version 1.0.1 is available on NuGet:

dotnet add package OpenPhysical.Biometrics.NFIQ1 --version 1.0.1
dotnet add package OpenPhysical.Biometrics.NFIQ2 --version 1.0.1

Both packages accept tightly packed, top-left-origin, 8-bit grayscale pixels. Black is 0 and white is 255. Supply dimensions and 500 ppi explicitly; each dimension must be from 64 through 2048 pixels for bounded buffer handling. NFIQ2 trims white margins before assessing the fingerprint content. That trimmed content must fit within 800 pixels wide and 1000 pixels high. Upstream InvalidImageSize code 14 describes invalid usable content geometry, including blank or degenerate trimmed content and content exceeding those limits. Use the capture facts to choose recapture for missing fingerprint content or correctly sized preparation for oversized content. White padding around a supported fingerprint remains valid. Small captures may have too little fingerprint area to assess. Decode reader output to grayscale pixels before calling the engines.

using OpenPhysical.Biometrics.NFIQ1;
using OpenPhysical.Biometrics.NFIQ2;

var original = new Nfiq1Engine();
Nfiq1Assessment first = original.Assess(pixels, width, height, dotsPerInch: 500);

using var unified = new Nfiq2Engine();
Nfiq2Assessment second = unified.Assess(pixels, width, height, dotsPerInch: 500);

Reuse the engines across captures. Materialize a LINQ sequence when the results will be filtered or reviewed more than once:

var assessments = captures
    .Select(capture => original.Assess(capture.Pixels, capture.Width, capture.Height, 500))
    .ToArray();

Nfiq1Assessment.Status distinguishes a normal assessment from the original algorithm's empty-image and too-few-minutiae outcomes. Those defined outcomes retain quality class 5 and confidence 1. When NFIQ2 cannot assess a capture, Nfiq2Exception.NativeStatus and UpstreamErrorCode preserve the outcome. An application can request recapture for insufficient fingerprint detail, handle code 14 according to the usable content geometry, and handle memory, model or unexpected native failures as operational problems. Upstream UnknownError code 0 is an unexpected failure, including exceptions that NFIQ2 wraps before they reach the binding. HasUpstreamErrorCode distinguishes that real code from -1, the binding's unavailable-code sentinel.

The runnable workflows show a single capture, paired SD04 impressions, LINQ-based candidate selection, typed JSON records, and poor-capture/malformed-input handling. Comments explain how each step fits an enrollment application. Example selection limits are supplied by application policy. Console output reports workflow status while assessment values stay in memory.

dotnet run --project examples/OpenPhysical.Biometrics.NFIQ.Examples -c Release -- capture.gray8 512 512
dotnet run --project examples/OpenPhysical.Biometrics.NFIQ.Examples -c Release -- --sd04 tests/fixtures

For dependency injection, call services.AddNfiq1() or services.AddNfiq2() from the corresponding namespace. NFIQ2 engines are disposable; the service provider manages their lifetime. Calls serialize within each NFIQ2 context and across the NFIQ1 native library. Logging uses Microsoft.Extensions.Logging and reports operational status. Public APIs include XML documentation for IntelliSense.

Build and test

Install .NET 10, Python 3, CMake 3.20+ and a C/C++ compiler with C++20 support for FingerJet. Windows uses the MSYS2 UCRT64 GCC toolchain. Clone with git clone --recurse-submodules to retrieve the pinned NFIQ2 dependencies.

python scripts/build-native.py --algorithm nfiq1
python scripts/build-native.py --algorithm nfiq2
python scripts/build-native.py --algorithm nfiq1 --tests
python scripts/build-native.py --algorithm nfiq2 --tests
dotnet tool restore
dotnet csharpier check src tests/OpenPhysical.Biometrics.NFIQ.Tests examples
dotnet test OpenPhysical.Biometrics.NFIQ.slnx -c Release

Pass --sanitizer asan or --sanitizer ubsan for separate instrumented native test builds. Package native assets are unsanitized release builds. The runtime identifiers and CI runners are defined in runtimes.props. Asset selection uses the operating system and process architecture, including .NET installations supplied by Linux distributions. Linux builds use Ubuntu 22.04 (glibc 2.35). Native macOS deployment target is 12; .NET 10's host support requires macOS 14 or later. Run managed builds and tests serially.

Complete release packing requires every algorithm runtime directory listed in runtimes.props. Local package checks can use -p:AllowPartialQualityRuntimes=true. Each package contains only its own native algorithm and runtime dependencies. NFIQ2's replaceable FingerJet and OpenCV shared libraries travel alongside the wrapper.

Testing and contributing

Publishing a GitHub release automatically validates and publishes both packages through NuGet trusted publishing, without stored API keys. See the release guide and changelog. Feature branches run checks on pull requests only; master also runs checks after pushes.

The validation record explains how we compare the adapted library with NIST's reference code. Our fixtures include twenty SD04 impressions, eight published NBIS NFIQ1 release captures and five published NFIQ2 examples. µnit owns exact native algorithm results and memory-safety checks; NUnit checks the .NET binding, typed outcomes and reuse workflows. CI retains native and managed coverage reports. CSharpier formatting and complete public XML documentation are required build gates.

See contributing for development and contributor terms, the Bounded Contribution Policy for participation, and security reporting for privately reporting a vulnerability.

Source and licensing

Source provenance records the official upstream releases, source checksums, dependency pins and adaptations. The first commit imports the original source. First-party code is GPL-2.0-or-later with commercial licensing available under the project terms. NFIQ2 dependencies retain their LGPLv3, Apache 2.0 and public-domain terms; see third-party notices and the corresponding-source and replacement instructions there. Fixtures credit Craig I. Watson and NIST.

Bundled native licenses

NFIQ2 includes OpenCV (Apache-2.0), FingerJetFX OSE (LGPL-3.0-or-later), and digestpp (Unlicense), alongside NIST's own notices and the first-party GPL-2.0-or-later binding. Its NuGet license metadata points to the component license inventory. Full license texts ship in licenses/; Windows runtime notices also ship under runtimes/win-x64/native/licenses/. See third-party notices for corresponding-source and replacement instructions.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.1 148 11/2/2026
1.0.0 133 11/1/2026