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}