Skip to main content

NBIS-rs

This is a Rust/Python binding to the NIST Biometric Image Software (NBIS) library, which is used for processing biometric images, particularly in the context of fingerprint recognition.

For convenience, this library also binds to the NIST Fingerprint Image Quality (NFIQ) version 2.

Features

  • Bindings to NBIS functions for minutia extraction, matching
  • Exports minutiae templates in ISO/IEC 19794-2:2011 format (loads 2005 templates too)
  • Matches minutiae templates against each other using the NBIS Bozorth3 algorithm
  • Provides support for NFIQ2 quality assessment

Building from source

Native dependencies (OpenCV 4.13, Rust 1.95 / edition 2024, CMake, C++ toolchain) are required. See DEPENDENCIES.md.

# macOS
./scripts/install-deps-macos.sh

# Linux (Debian/Ubuntu)
./scripts/install-deps-linux.sh

cargo build --release
cargo test
make python   # optional Python wheel

Python package (nbis-python on PyPI)

pip install "nbis-python>=0.1.17"

Maintainers: build macOS + Linux wheels and upload — see docs/PUBLISHING.md.

make wheels-all
make publish-check
make publish

Installation (Rust)

To use NBIS-rs, add the following to your Cargo.toml:

[dependencies]
nbis-rs = { git = "https://github.com/Seventh-Sense-Artificial-Intelligence/nbis-rs", branch = "main", version = "0.1.3" }

Or you can run the following command on the terminal of your new rust project:

cargo add nbis-rs --git https://github.com/Seventh-Sense-Artificial-Intelligence/nbis-rs --branch main

Running the above command will add the above dependency in your Cargo.toml

Now you can use the nbis-rs rust library in your project as mentioned in next section.

Usage (Rust)

Here's a simple example of how to use NBIS-rs in your project:

fn main() -> Result<(), Box<dyn std::error::Error>> {
    use nbis;
    use nbis::Minutiae;
    use nbis::NbisExtractorSettings;
    // Configuration for the NbisExtractor
    let settings = NbisExtractorSettings {
        // No filtering on minutiae quality (all minutiae will be included)
        min_quality: 0.0,
        // Do not compute ROI or center to save computing resources
        get_center: false,
        // Do not check if the image is a fingerprint using SIVV
        check_fingerprint: false,
        // compute the NFIQ score
        compute_nfiq2: true,
        // No specific PPI, use the default
        ppi: None,
    };

    let extractor = nbis::NbisExtractor::new(settings)?;

    // Read the bytes from a file (you could also use nbis::extract_minutiae_from_image_file)
    // but here we just load the image bytes as image paths on mobile platforms can be tricky.
    let image_bytes = std::fs::read("test_data/p1/p1_1.png")?;

    let minutiae_1 = extractor.extract_minutiae(&image_bytes)?;

    let image_bytes = std::fs::read("test_data/p1/p1_2.png")?;
    let minutiae_2 = extractor.extract_minutiae(&image_bytes)?;

    let image_bytes = std::fs::read("test_data/p1/p1_3.png")?;
    let minutiae_3 = extractor.extract_minutiae(&image_bytes)?;

    // Compare the two sets of minutiae
    let score = minutiae_1.compare(&minutiae_2);
    assert!(score > 35, "Expected a high similarity score between p1_1 and p1_2");
    let score = minutiae_1.compare(&minutiae_3);
    assert!(score > 35, "Expected a high similarity score between p1_1 and p1_3");
    let score = minutiae_2.compare(&minutiae_3);
    assert!(score > 35, "Expected a high similarity score between p1_2 and p1_3");

    // Next we will demonstrate conversion to ISO/IEC 19794-2:2011 format
    // and back to a `Minutiae` object.
    // First, convert the minutiae to ISO template bytes
    let iso_template: Vec<u8> = minutiae_1.to_iso_19794_2_2011()?;
    // And load it back
    let minutiae_from_iso = extractor.load_iso_19794_2_2011(&iso_template)?;
    // Compare the original minutiae with the one loaded from ISO template
    for (a, b) in minutiae_from_iso.get().iter().zip(minutiae_1.get().iter()) {
        assert_eq!(a.x(), b.x());
        assert_eq!(a.y(), b.y());
        assert_eq!(a.angle(), b.angle());
        assert_eq!(a.kind(), b.kind());
        // Reliability is quantized in the round-trip conversion,
        // so we allow a small margin of error.
        assert!((a.reliability() - b.reliability()).abs() < 1e-1);
    }

    // Finally we demonstrate loading from a file and comparing a negative match
    let minutiae_4 = extractor.extract_minutiae_from_image_file("test_data/p2/p2_1.png")?;
    let score = minutiae_1.compare(&minutiae_4);
    assert!(score < 35, "Expected a low similarity score between p1_1 and p2_1");

    // We can access the NFIQ2 quality via:
    let nfiq2_quality = minutiae_1.quality();
    assert!(nfiq2_quality.score > 50, "Expected a positive NFIQ2 quality score");

    Ok(())
}

Installation (Python)

pip install "nbis-python>=0.1.15"

See docs/PUBLISHING.md for PyPI release steps.

Usage (Python)

Here's a simple example of how to use the NBIS Python bindings:

import nbis
from nbis import NbisExtractor, NbisExtractorSettings

 #Configuration for the NbisExtractor
settings = NbisExtractorSettings(
    # Do not filter on minutiae quality (get all minutiae)
    min_quality=0.0,
    # Do not get the fingerprint center or ROI
    get_center=False,
    # Do not use SIVV to check if the image is a fingerprint
    check_fingerprint=False,
    # Compute the NFIQ2 quality score
    compute_nfiq2=True,
    # No specific PPI, use the default
    ppi=None,
)

extractor = nbis.new_nbis_extractor(settings)

# Read the bytes from a file
image_bytes = open("test_data/p1/p1_1.png", "rb").read()
minutiae_1 = extractor.extract_minutiae(image_bytes)
image_bytes = open("test_data/p1/p1_2.png", "rb").read()
minutiae_2 = extractor.extract_minutiae(image_bytes)
image_bytes = open("test_data/p1/p1_3.png", "rb").read()
minutiae_3 = extractor.extract_minutiae(image_bytes)

# Compare the two sets of minutiae
score = minutiae_1.compare(minutiae_2)
assert score > 50, "Expected a high similarity score between p1_1 and p1_2"
score = minutiae_1.compare(minutiae_3)
assert score > 50, "Expected a high similarity score between p1_1 and p1_3"
score = minutiae_2.compare(minutiae_3)
assert score > 50, "Expected a high similarity score between p1_2 and p1_3"

# Convert minutiae to ISO/IEC 19794-2:2011 format
iso_template = minutiae_1.to_iso_19794_2_2011()?
# Load it back
minutiae_from_iso = extractor.load_iso_19794_2_2011(iso_template)
# Compare the original minutiae with the one loaded from ISO template
for a, b in zip(minutiae_from_iso.get(), minutiae_1.get()):
    assert a.x() == b.x()
    assert a.y() == b.y()
    assert a.angle() == b.angle()
    assert a.kind() == b.kind()
    # Reliability is quantized in the round-trip conversion,
    # so we allow a small margin of error.
    assert abs(a.reliability() - b.reliability()) < 0.1

# Finally we demonstrate loading from a file and comparing a negative match
minutiae_4 = extractor.extract_minutiae_from_image_file("test_data/p2/p2_1.png")
score = minutiae_1.compare(minutiae_4)
assert score < 50, "Expected a low similarity score between p1_1 and p2_1"

# We can access the NFIQ2 quality via:
nfiq2_quality = minutiae_1.quality()
assert nfiq2_quality.score > 50, "Expected a positive NFIQ2 quality score"

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Metadata

Release files for nbis-python 0.1.21

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for nbis-python 0.1.21
File Interpreter ABI Platform Actions
nbis_python-0.1.21-py3-none-manylinux_2_28_x86_64.whl Python 3 none Linux glibc 2.28+ x86-64 Details for nbis_python-0.1.21-py3-none-manylinux_2_28_x86_64.whl
nbis_python-0.1.21-py3-none-manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64 Details for nbis_python-0.1.21-py3-none-manylinux_2_28_aarch64.whl
nbis_python-0.1.21-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for nbis_python-0.1.21-py3-none-macosx_11_0_arm64.whl

Total release size: 35.5 MB

Release files / nbis_python-0.1.21-py3-none-manylinux_2_28_x86_64.whl

Download URL nbis_python-0.1.21-py3-none-manylinux_2_28_x86_64.whl
Size 23.9 MB
Tags Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
e0b87b1c353ddeab873209e264363e548b586673dbcf820e68ded944a57a668b
BLAKE2b-256 checksum
How to use checksums
33c6b8628325a240b0fc437be7eee71cab03b3abf0aeaf94a2b9f44b56cb635c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Release files / nbis_python-0.1.21-py3-none-manylinux_2_28_aarch64.whl

Download URL nbis_python-0.1.21-py3-none-manylinux_2_28_aarch64.whl
Size 8.1 MB
Tags Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
7ce446584b574dedf5a29ae85424caab87e56310a3b33e648d7e7604ea4d41e5
BLAKE2b-256 checksum
How to use checksums
759d86853a953cd939f4c2e084e7e5b8798c15fdaaa88a96889bb4d122aec1d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Release files / nbis_python-0.1.21-py3-none-macosx_11_0_arm64.whl

Download URL nbis_python-0.1.21-py3-none-macosx_11_0_arm64.whl
Size 3.5 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
ad4ab46fbee709a5d1cea3c86455b7c4e17910295b9ebc182a1c74a7dc98551f
BLAKE2b-256 checksum
How to use checksums
d4de737c99226323ea361a9dec31f84fc10fd7e42ace25bf22634aa2a6301013
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Security for nbis-python 0.1.21

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page