Skip to main content

fprint_pipeline/
lib.rs

1// SPDX-FileCopyrightText: 2026 fprintd (pure-Rust) contributors
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5//! # fprint-pipeline
6//!
7//! The host-image fingerprint pipeline. It joins the three published leaves —
8//! [`fprint_mindtct`] (minutiae detection), [`fprint_bozorth3`] (minutiae matching) and
9//! [`fprint_core`] (the domain [`Print`](fprint_core::Print) / [`Template`](fprint_core::Template) /
10//! [`Minutia`](fprint_core::Minutia)) — into the one path a host-image sensor walks:
11//! **image → minutiae → template → match**.
12//!
13//! The two kernels are dependency-free and each defines its own `Minutia` (the `xyt` triple is an
14//! interoperability fact, not a shared type). This crate owns the small conversions between them
15//! and the domain model:
16//!
17//! - [`extract_minutiae`] / [`template_from_images`] — the front half, over [`fprint_mindtct`].
18//! - [`nbis_match_score`] (→ [`MatchScore`]) / [`nbis_verify`] / [`nbis_identify`] — the back half,
19//!   over [`fprint_bozorth3`].
20//! - [`minutia_to_core`] / [`minutiae_to_bozorth`] — the boundary conversions, exposed for callers
21//!   that assemble their own pipeline.
22//!
23//! Add just this crate: it re-exports [`fprint_core`], [`fprint_mindtct`] and [`fprint_bozorth3`], so
24//! the domain types and the kernels are reachable without naming them as separate dependencies.
25//!
26//! ## Image → template → match
27//!
28//! ```
29//! use fprint_pipeline::{
30//!     nbis_identify, nbis_match_score, nbis_verify, template_from_images, GrayImage,
31//! };
32//!
33//! // A procedural fingerprint-like frame: dark horizontal ridges with a gap cut into every other
34//! // ridge. A gap ends a ridge, and a ridge ending is a minutia (plain stripes would have none).
35//! fn synthetic_frame() -> Vec<u8> {
36//!     let (w, h) = (128usize, 128usize);
37//!     (0..w * h)
38//!         .map(|i| {
39//!             let (x, y) = (i % w, i / w);
40//!             let on_ridge = (y % 8) < 4;
41//!             let gap = (48..80).contains(&x) && (y / 8) % 2 == 0;
42//!             if on_ridge && !gap { 32 } else { 224 }
43//!         })
44//!         .collect()
45//! }
46//!
47//! // Enroll one capture, then take a second capture of the same finger as the probe.
48//! let frame = synthetic_frame();
49//! let img = GrayImage::new(&frame, 128, 128, 500).expect("buffer holds the image");
50//! let enrolled = template_from_images(&[img]);
51//!
52//! let frame2 = synthetic_frame();
53//! let scan = GrayImage::new(&frame2, 128, 128, 500).expect("buffer holds the image");
54//! let scanned = template_from_images(&[scan]);
55//!
56//! // Verify (1:1): a bool decision against a driver threshold, or read the raw score.
57//! let threshold = 40;
58//! let _accepted: bool = nbis_verify(&enrolled, &scanned, threshold);
59//! let score: Option<u32> = nbis_match_score(&enrolled, &scanned).score();
60//!
61//! // A same-finger recapture out-scores an unrelated print; the caller picks the accept threshold.
62//! let stranger = template_from_images(&[]);
63//! assert!(score >= nbis_match_score(&enrolled, &stranger).score());
64//!
65//! // Identify (1:N): the gallery index whose enrolled template best matches the probe.
66//! let gallery = vec![enrolled, stranger];
67//! assert_eq!(nbis_identify(&scanned, &gallery, 0), Some(0));
68//! ```
69//!
70//! ## Persistence
71//!
72//! This crate stops at the in-memory [`Template`](fprint_core::Template). To write an enrolled print
73//! to disk in the format libfprint reads and writes, add `fprint-fp3` and call its `to_bytes` /
74//! `from_bytes` on a [`Print`](fprint_core::Print) carrying the template — persistence is a
75//! separate, single-purpose crate.
76
77#![forbid(unsafe_code)]
78#![deny(missing_docs)]
79
80mod detector;
81mod matcher;
82
83pub use detector::{extract_minutiae, minutia_to_core, template_from_images};
84pub use matcher::{minutiae_to_bozorth, nbis_identify, nbis_match_score, nbis_verify, MatchScore};
85
86// The input type a caller builds a frame with, its constructor error, and the detection floor that
87// error names — pulled to the top so the common path needs to name only this crate.
88pub use fprint_mindtct::{GrayImage, ImageError, MIN_DETECTABLE_DIM};
89
90// The layers this crate joins, re-exported so `fprint_pipeline::fprint_core::Print` (and the two
91// kernels) resolve without adding them as separate dependencies. The glue produces and consumes
92// `fprint_core` types, so a caller reaches for them constantly.
93pub use fprint_bozorth3;
94pub use fprint_core;
95pub use fprint_mindtct;
96
97/// The handful of names the common path uses: the pipeline functions, the [`GrayImage`] input, and
98/// the domain [`Print`](fprint_core::Print) / [`Template`](fprint_core::Template) /
99/// [`Minutia`](fprint_core::Minutia) the functions produce and consume.
100///
101/// `use fprint_pipeline::prelude::*;` brings in enough to go from a frame to a match without naming
102/// the leaf crates.
103pub mod prelude {
104    pub use crate::{
105        extract_minutiae, nbis_identify, nbis_match_score, nbis_verify, template_from_images,
106        GrayImage, MatchScore,
107    };
108    pub use fprint_core::{Finger, Minutia, Print, Template};
109}