Skip to main content

fprint_mindtct/
params.rs

1// SPDX-FileCopyrightText: 2026 fprintd (pure-Rust) contributors
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5//! The `lfsparms_V2` parameter block: the thresholds and controls that drive `_V2` MINDTCT,
6//! assembled from the `*_V2` and shared `#define`s in stock NBIS `lfs.h` / `globals.c`.
7//!
8//! [`LfsParms`] mirrors the stock `LFSPARMS` struct field-for-field, in declaration order, and
9//! [`LFSPARMS_V2`] reproduces the `lfsparms_V2` initializer verbatim — including the fields that
10//! `_V2` deliberately leaves `UNUSED_INT`/`UNUSED_DBL` (isotropic binarization and the whole
11//! minutiae-linking group, which `_V2` replaces). Every value is an **interoperability fact**; the
12//! comments cite the reference macro. See `docs/mindtct-algorithm.md`.
13
14use crate::consts;
15
16/// Runtime parameter block for the LFS pipeline — the Rust analogue of stock NBIS `LFSPARMS`.
17///
18/// Fields appear in exactly the stock struct's declaration order (`lfs.h`), grouped by the same
19/// comment banners. `int` maps to [`i32`] and `double` to [`f64`]. Read-only configuration handed
20/// to the detection stages; see [`LFSPARMS_V2`] for the shipping `_V2` values.
21#[derive(Clone, Copy, Debug, PartialEq)]
22pub(crate) struct LfsParms {
23    /* Image Controls */
24    /// `pad_value` — intensity used to fill the padded image border.
25    pub(crate) pad_value: i32,
26    /// `join_line_radius` — radial width added to a minutia join line.
27    pub(crate) join_line_radius: i32,
28
29    /* Map Controls */
30    /// `blocksize` — pixel dimension of each (non-overlapping) image block.
31    pub(crate) blocksize: i32,
32    /// `windowsize` — pixel dimension of the window surrounding each block.
33    pub(crate) windowsize: i32,
34    /// `windowoffset` — X&Y offset from a block's origin to its window's origin.
35    pub(crate) windowoffset: i32,
36    /// `num_directions` — number of integer directions across the semicircle.
37    pub(crate) num_directions: i32,
38    /// `start_dir_angle` — theta (radians) at which the integer directions begin.
39    pub(crate) start_dir_angle: f64,
40    /// `rmv_valid_nbr_min` — min valid neighbors for a block value to survive removal.
41    pub(crate) rmv_valid_nbr_min: i32,
42    /// `dir_strength_min` — min strength for a direction to count as significant.
43    pub(crate) dir_strength_min: f64,
44    /// `dir_distance_max` — max distance between a block direction and its neighbors' average.
45    pub(crate) dir_distance_max: i32,
46    /// `smth_valid_nbr_min` — min valid neighbors to smooth an invalid direction.
47    pub(crate) smth_valid_nbr_min: i32,
48    /// `vort_valid_nbr_min` — min valid neighbors to measure an invalid block's vorticity.
49    pub(crate) vort_valid_nbr_min: i32,
50    /// `highcurv_vorticity_min` — min vorticity marking an invalid block high-curvature.
51    pub(crate) highcurv_vorticity_min: i32,
52    /// `highcurv_curvature_min` — min curvature marking a valid block high-curvature.
53    pub(crate) highcurv_curvature_min: i32,
54    /// `min_interpolate_nbrs` — min valid neighbors to interpolate an invalid direction.
55    pub(crate) min_interpolate_nbrs: i32,
56    /// `percentile_min_max` — percentile cutoff for a block's min/max intensities.
57    pub(crate) percentile_min_max: i32,
58    /// `min_contrast_delta` — min min/max delta (6-bit) for a block to be non-low-contrast.
59    pub(crate) min_contrast_delta: i32,
60
61    /* DFT Controls */
62    /// `num_dft_waves` — number of DFT waveforms applied.
63    pub(crate) num_dft_waves: i32,
64    /// `powmax_min` — min DFT power allowable in any one direction.
65    pub(crate) powmax_min: f64,
66    /// `pownorm_min` — min normalized power allowable in any one direction.
67    pub(crate) pownorm_min: f64,
68    /// `powmax_max` — max power allowable at the lowest-frequency DFT wave.
69    pub(crate) powmax_max: f64,
70    /// `fork_interval` — check for a fork at +/- this many units from the current direction.
71    pub(crate) fork_interval: i32,
72    /// `fork_pct_powmax` — fork power floor as a fraction of the block's max directional power.
73    pub(crate) fork_pct_powmax: f64,
74    /// `fork_pct_pownorm` — fork normalized-power floor as a fraction of `pownorm_min`.
75    pub(crate) fork_pct_pownorm: f64,
76
77    /* Binarization Controls */
78    /// `dirbin_grid_w` — directional-binarization grid width.
79    pub(crate) dirbin_grid_w: i32,
80    /// `dirbin_grid_h` — directional-binarization grid height.
81    pub(crate) dirbin_grid_h: i32,
82    /// `isobin_grid_dim` — isotropic-binarization grid dimension (unused in `_V2`).
83    pub(crate) isobin_grid_dim: i32,
84    /// `num_fill_holes` — passes filling length-1 holes in the binary image.
85    pub(crate) num_fill_holes: i32,
86
87    /* Minutiae Detection Controls */
88    /// `max_minutia_delta` — max X/Y pixel translation for two minutiae to be "similar".
89    pub(crate) max_minutia_delta: i32,
90    /// `max_high_curve_theta` — contour-angle ceiling (radians) for a contour to hold minutiae.
91    pub(crate) max_high_curve_theta: f64,
92    /// `high_curve_half_contour` — half the pixel length extracted for a high-curvature contour.
93    pub(crate) high_curve_half_contour: i32,
94    /// `min_loop_len` — loop must exceed this pixel length to be considered for minutiae.
95    pub(crate) min_loop_len: i32,
96    /// `min_loop_aspect_dist` — min half-way distance across a loop's contour to test it.
97    pub(crate) min_loop_aspect_dist: f64,
98    /// `min_loop_aspect_ratio` — min max/min half-way distance ratio to test a loop.
99    pub(crate) min_loop_aspect_ratio: f64,
100
101    /* Minutiae Link Controls */
102    /// `link_table_dim` — 2D link-table dimension (unused in `_V2`).
103    pub(crate) link_table_dim: i32,
104    /// `max_link_dist` — orthogonal link distance (unused in `_V2`).
105    pub(crate) max_link_dist: i32,
106    /// `min_theta_dist` — min distance for a reliable inter-point angle (unused in `_V2`).
107    pub(crate) min_theta_dist: i32,
108    /// `maxtrans` — max transitions along a trajectory for it to be "free" (also removes overlaps).
109    pub(crate) maxtrans: i32,
110    /// `score_theta_norm` — link-score theta normalizer (unused in `_V2`).
111    pub(crate) score_theta_norm: f64,
112    /// `score_dist_norm` — link-score distance normalizer (unused in `_V2`).
113    pub(crate) score_dist_norm: f64,
114    /// `score_dist_weight` — link-score distance weight (unused in `_V2`).
115    pub(crate) score_dist_weight: f64,
116    /// `score_numerator` — link-score numerator (unused in `_V2`).
117    pub(crate) score_numerator: f64,
118
119    /* False Minutiae Removal Controls */
120    /// `max_rmtest_dist` — orthogonal distance for two minutiae to be considered for removal.
121    pub(crate) max_rmtest_dist: i32,
122    /// `max_hook_len` — pixel-contour length traced when analyzing for hooks.
123    pub(crate) max_hook_len: i32,
124    /// `max_half_loop` — half the max pixel-contour length traced for islands/lakes.
125    pub(crate) max_half_loop: i32,
126    /// `trans_dir_pix` — pixels opposite the minutia used to reach an invalid block.
127    pub(crate) trans_dir_pix: i32,
128    /// `small_loop_len` — max circumference of a small island/lake loop to remove.
129    pub(crate) small_loop_len: i32,
130    /// `side_half_contour` — half the pixels traced to form a complete side contour.
131    pub(crate) side_half_contour: i32,
132    /// `inv_block_margin` — max orthogonal distance to an invalid block for removal.
133    pub(crate) inv_block_margin: i32,
134    /// `rm_valid_nbr_min` — invalid-block valid-neighbor floor below which a minutia is removed.
135    pub(crate) rm_valid_nbr_min: i32,
136    /// `max_overlap_dist` — max pixel distance between two points tested for overlap.
137    pub(crate) max_overlap_dist: i32,
138    /// `max_overlap_join_dist` — max distance across an overlap that will be joined.
139    pub(crate) max_overlap_join_dist: i32,
140    /// `malformation_steps_1` — contour steps to the first malformation measuring point.
141    pub(crate) malformation_steps_1: i32,
142    /// `malformation_steps_2` — contour steps to the second malformation measuring point.
143    pub(crate) malformation_steps_2: i32,
144    /// `min_malformation_ratio` — min across-feature distance ratio to be considered normal.
145    pub(crate) min_malformation_ratio: f64,
146    /// `max_malformation_dist` — max across-feature distance to be considered normal.
147    pub(crate) max_malformation_dist: i32,
148    /// `pores_trans_r` — translation off a valley edge into the neighboring ridge.
149    pub(crate) pores_trans_r: i32,
150    /// `pores_perp_steps` — steps searched for the current ridge's edge.
151    pub(crate) pores_perp_steps: i32,
152    /// `pores_steps_fwd` — pixels traced to find forward contour points.
153    pub(crate) pores_steps_fwd: i32,
154    /// `pores_steps_bwd` — pixels traced to find backward contour points.
155    pub(crate) pores_steps_bwd: i32,
156    /// `pores_min_dist2` — min squared distance before it is treated as zero.
157    pub(crate) pores_min_dist2: f64,
158    /// `pores_max_ratio` — max forward/backward distance ratio to be considered a pore.
159    pub(crate) pores_max_ratio: f64,
160
161    /* Ridge Counting Controls */
162    /// `max_nbrs` — max nearest neighbors per minutia.
163    pub(crate) max_nbrs: i32,
164    /// `max_ridge_steps` — max contour steps to validate a ridge crossing.
165    pub(crate) max_ridge_steps: i32,
166}
167
168/// The stock `lfsparms_V2` initializer — the shipping VERSION 2 parameter set.
169///
170/// Values are the `#define`s from `lfs.h` in the exact order `globals.c` supplies them: the map
171/// group uses the `MAP_*_V2` block geometry, false-removal uses the `*_V2` distances, and the
172/// fields `_V2` retired (`isobin_grid_dim`, the linking group, the `score_*` weights) hold their
173/// `UNUSED_INT`/`UNUSED_DBL` sentinels (`0` / `0.0`).
174//
175// Each field is sourced from `crate::consts` (the verbatim `lfs.h` `#define`s), in the exact order
176// `globals.c` lists them. The stock `UNUSED_INT`/`UNUSED_DBL` sentinels are inlined as `0` / `0.0`
177// because `_V2` retires those fields and `consts` deliberately omits the retired macros.
178pub(crate) const LFSPARMS_V2: LfsParms = LfsParms {
179    /* Image Controls */
180    pad_value: consts::PAD_VALUE,
181    join_line_radius: consts::JOIN_LINE_RADIUS,
182
183    /* Map Controls */
184    blocksize: consts::MAP_BLOCKSIZE_V2,
185    windowsize: consts::MAP_WINDOWSIZE_V2,
186    windowoffset: consts::MAP_WINDOWOFFSET_V2,
187    num_directions: consts::NUM_DIRECTIONS,
188    start_dir_angle: consts::START_DIR_ANGLE,
189    rmv_valid_nbr_min: consts::RMV_VALID_NBR_MIN,
190    dir_strength_min: consts::DIR_STRENGTH_MIN,
191    dir_distance_max: consts::DIR_DISTANCE_MAX,
192    smth_valid_nbr_min: consts::SMTH_VALID_NBR_MIN,
193    vort_valid_nbr_min: consts::VORT_VALID_NBR_MIN,
194    highcurv_vorticity_min: consts::HIGHCURV_VORTICITY_MIN,
195    highcurv_curvature_min: consts::HIGHCURV_CURVATURE_MIN,
196    min_interpolate_nbrs: consts::MIN_INTERPOLATE_NBRS,
197    percentile_min_max: consts::PERCENTILE_MIN_MAX,
198    min_contrast_delta: consts::MIN_CONTRAST_DELTA,
199
200    /* DFT Controls */
201    num_dft_waves: consts::NUM_DFT_WAVES,
202    powmax_min: consts::POWMAX_MIN,
203    pownorm_min: consts::POWNORM_MIN,
204    powmax_max: consts::POWMAX_MAX,
205    fork_interval: consts::FORK_INTERVAL,
206    fork_pct_powmax: consts::FORK_PCT_POWMAX,
207    fork_pct_pownorm: consts::FORK_PCT_POWNORM,
208
209    /* Binarization Controls */
210    dirbin_grid_w: consts::DIRBIN_GRID_W,
211    dirbin_grid_h: consts::DIRBIN_GRID_H,
212    isobin_grid_dim: 0, // UNUSED_INT (ISOBIN_GRID_DIM retired in _V2)
213    num_fill_holes: consts::NUM_FILL_HOLES,
214
215    /* Minutiae Detection Controls */
216    max_minutia_delta: consts::MAX_MINUTIA_DELTA,
217    max_high_curve_theta: consts::MAX_HIGH_CURVE_THETA,
218    high_curve_half_contour: consts::HIGH_CURVE_HALF_CONTOUR,
219    min_loop_len: consts::MIN_LOOP_LEN,
220    min_loop_aspect_dist: consts::MIN_LOOP_ASPECT_DIST,
221    min_loop_aspect_ratio: consts::MIN_LOOP_ASPECT_RATIO,
222
223    /* Minutiae Link Controls */
224    link_table_dim: 0,          // UNUSED_INT (LINK_TABLE_DIM)
225    max_link_dist: 0,           // UNUSED_INT (MAX_LINK_DIST)
226    min_theta_dist: 0,          // UNUSED_INT (MIN_THETA_DIST)
227    maxtrans: consts::MAXTRANS, // MAXTRANS (also used for removing overlaps)
228    score_theta_norm: 0.0,      // UNUSED_DBL (SCORE_THETA_NORM)
229    score_dist_norm: 0.0,       // UNUSED_DBL (SCORE_DIST_NORM)
230    score_dist_weight: 0.0,     // UNUSED_DBL (SCORE_DIST_WEIGHT)
231    score_numerator: 0.0,       // UNUSED_DBL (SCORE_NUMERATOR)
232
233    /* False Minutiae Removal Controls */
234    max_rmtest_dist: consts::MAX_RMTEST_DIST_V2,
235    max_hook_len: consts::MAX_HOOK_LEN_V2,
236    max_half_loop: consts::MAX_HALF_LOOP_V2,
237    trans_dir_pix: consts::TRANS_DIR_PIX_V2,
238    small_loop_len: consts::SMALL_LOOP_LEN,
239    side_half_contour: consts::SIDE_HALF_CONTOUR,
240    inv_block_margin: consts::INV_BLOCK_MARGIN_V2,
241    rm_valid_nbr_min: consts::RM_VALID_NBR_MIN,
242    max_overlap_dist: consts::MAX_OVERLAP_DIST,
243    max_overlap_join_dist: consts::MAX_OVERLAP_JOIN_DIST,
244    malformation_steps_1: consts::MALFORMATION_STEPS_1,
245    malformation_steps_2: consts::MALFORMATION_STEPS_2,
246    min_malformation_ratio: consts::MIN_MALFORMATION_RATIO,
247    max_malformation_dist: consts::MAX_MALFORMATION_DIST,
248    pores_trans_r: consts::PORES_TRANS_R,
249    pores_perp_steps: consts::PORES_PERP_STEPS,
250    pores_steps_fwd: consts::PORES_STEPS_FWD,
251    pores_steps_bwd: consts::PORES_STEPS_BWD,
252    pores_min_dist2: consts::PORES_MIN_DIST2,
253    pores_max_ratio: consts::PORES_MAX_RATIO,
254
255    /* Ridge Counting Controls */
256    max_nbrs: consts::MAX_NBRS,
257    max_ridge_steps: consts::MAX_RIDGE_STEPS,
258};
259
260#[cfg(test)]
261mod tests {
262    use super::LFSPARMS_V2;
263    use core::f64::consts::PI;
264
265    // Cross-checks against the stock `lfsparms_V2` initializer in
266    // `reference/nbis-stock/mindtct/src/lib/mindtct/globals.c` (values from `lfs.h`).
267
268    #[test]
269    fn image_and_map_controls_match_stock() {
270        let p = LFSPARMS_V2;
271        assert_eq!(p.pad_value, 128);
272        assert_eq!(p.join_line_radius, 1);
273
274        assert_eq!(p.blocksize, 8);
275        assert_eq!(p.windowsize, 24);
276        assert_eq!(p.windowoffset, 8);
277        assert_eq!(p.num_directions, 16);
278        assert_eq!(p.rmv_valid_nbr_min, 3);
279        assert_eq!(p.dir_distance_max, 3);
280        assert_eq!(p.smth_valid_nbr_min, 7);
281        assert_eq!(p.vort_valid_nbr_min, 7);
282        assert_eq!(p.highcurv_vorticity_min, 5);
283        assert_eq!(p.highcurv_curvature_min, 5);
284        assert_eq!(p.min_interpolate_nbrs, 2);
285        assert_eq!(p.percentile_min_max, 10);
286        assert_eq!(p.min_contrast_delta, 5);
287    }
288
289    #[test]
290    fn dft_and_binarization_controls_match_stock() {
291        let p = LFSPARMS_V2;
292        assert_eq!(p.num_dft_waves, 4);
293        assert_eq!(p.powmax_min, 100_000.0);
294        assert_eq!(p.pownorm_min, 3.8);
295        assert_eq!(p.powmax_max, 50_000_000.0);
296        assert_eq!(p.fork_interval, 2);
297        assert_eq!(p.fork_pct_powmax, 0.7);
298        assert_eq!(p.fork_pct_pownorm, 0.75);
299
300        assert_eq!(p.dirbin_grid_w, 7);
301        assert_eq!(p.dirbin_grid_h, 9);
302        assert_eq!(p.num_fill_holes, 3);
303    }
304
305    #[test]
306    fn detection_and_removal_controls_match_stock() {
307        let p = LFSPARMS_V2;
308        assert_eq!(p.max_minutia_delta, 10);
309        assert_eq!(p.high_curve_half_contour, 14);
310        assert_eq!(p.min_loop_len, 20);
311        assert_eq!(p.min_loop_aspect_dist, 1.0);
312        assert_eq!(p.min_loop_aspect_ratio, 2.25);
313
314        // The `*_V2` false-removal distances, not the V1 defaults.
315        assert_eq!(p.max_rmtest_dist, 16);
316        assert_eq!(p.max_hook_len, 30);
317        assert_eq!(p.max_half_loop, 30);
318        assert_eq!(p.trans_dir_pix, 4);
319        assert_eq!(p.inv_block_margin, 4);
320        assert_eq!(p.maxtrans, 2);
321
322        assert_eq!(p.small_loop_len, 15);
323        assert_eq!(p.side_half_contour, 7);
324        assert_eq!(p.rm_valid_nbr_min, 7);
325        assert_eq!(p.max_overlap_dist, 8);
326        assert_eq!(p.max_overlap_join_dist, 6);
327        assert_eq!(p.malformation_steps_1, 10);
328        assert_eq!(p.malformation_steps_2, 20);
329        assert_eq!(p.min_malformation_ratio, 2.0);
330        assert_eq!(p.max_malformation_dist, 20);
331        assert_eq!(p.pores_trans_r, 3);
332        assert_eq!(p.pores_perp_steps, 12);
333        assert_eq!(p.pores_steps_fwd, 10);
334        assert_eq!(p.pores_steps_bwd, 8);
335        assert_eq!(p.pores_min_dist2, 0.5);
336        assert_eq!(p.pores_max_ratio, 2.25);
337
338        assert_eq!(p.max_nbrs, 5);
339        assert_eq!(p.max_ridge_steps, 10);
340    }
341
342    #[test]
343    fn angles_are_bit_exact_fractions_of_pi() {
344        let p = LFSPARMS_V2;
345        // Reproduce the stock derivation exactly (M_PI is the same f64 as `core`'s PI).
346        assert_eq!(p.start_dir_angle, PI / 2.0);
347        assert_eq!(p.max_high_curve_theta, PI / 3.0);
348        assert_eq!(p.dir_strength_min, 0.2);
349    }
350
351    #[test]
352    fn v2_leaves_retired_fields_at_unused_sentinels() {
353        let p = LFSPARMS_V2;
354        // `_V2` retires isotropic binarization and the whole linking group.
355        assert_eq!(p.isobin_grid_dim, 0); // UNUSED_INT (V1 had ISOBIN_GRID_DIM = 11)
356        assert_eq!(p.link_table_dim, 0);
357        assert_eq!(p.max_link_dist, 0);
358        assert_eq!(p.min_theta_dist, 0);
359        assert_eq!(p.score_theta_norm, 0.0);
360        assert_eq!(p.score_dist_norm, 0.0);
361        assert_eq!(p.score_dist_weight, 0.0);
362        assert_eq!(p.score_numerator, 0.0);
363    }
364}