fprint_mindtct/consts.rs
1// SPDX-FileCopyrightText: 2026 fprintd (pure-Rust) contributors
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5//! Fixed algorithm constants copied verbatim from stock NBIS `lfs.h` (block/window sizes,
6//! `NUM_DIRECTIONS`, DFT wave count, grid dimensions, `PAD_VALUE`, `MAX_MINUTIAE`, `TRUNC_SCALE`).
7//! Each value is an interoperability fact; comments cite the reference macro.
8//!
9//! These are the `#define`s from `mindtct/include/lfs.h` (and the `dft_coefs` array from
10//! `globals.c`) that feed the **VERSION 2** parameter block `lfsparms_V2` — the only configuration
11//! MINDTCT ships with — plus the handful of fixed geometry/scale constants the pipeline reads
12//! directly. The V2 struct leaves the whole *minutiae-link* group and `isobin_grid_dim` as
13//! `UNUSED_INT`/`UNUSED_DBL`, so those link-stage macros are deliberately **absent** here.
14//!
15//! Types follow the C `LFSPARMS` struct: `int` fields → `i32`, `double` fields → `f64`. The one
16//! capacity value (`MAX_MINUTIAE`) is a `usize`, matching its role as an allocation cap. See
17//! `docs/mindtct-algorithm.md`.
18
19// ---------------------------------------------------------------------------
20// Image controls
21// ---------------------------------------------------------------------------
22
23/// `PAD_VALUE` — medium-gray (`128` @ 8 bits) used to pad the image border before block analysis.
24pub(crate) const PAD_VALUE: i32 = 128;
25
26/// `JOIN_LINE_RADIUS` — half-width of the line drawn when joining two minutiae.
27pub(crate) const JOIN_LINE_RADIUS: i32 = 1;
28
29// ---------------------------------------------------------------------------
30// Map controls (VERSION 2)
31// ---------------------------------------------------------------------------
32
33/// `MAP_BLOCKSIZE_V2` — pixel dimension of an image block (`8`).
34pub(crate) const MAP_BLOCKSIZE_V2: i32 = 8;
35
36/// `MAP_WINDOWSIZE_V2` — pixel dimension of the window surrounding a block (`24`).
37///
38/// Note the V2 geometry invariant `windowsize == blocksize + 2 * windowoffset`; see the tests.
39pub(crate) const MAP_WINDOWSIZE_V2: i32 = 24;
40
41/// `MAP_WINDOWOFFSET_V2` — offset in X & Y from a block to its window origin (`8`).
42pub(crate) const MAP_WINDOWOFFSET_V2: i32 = 8;
43
44/// `NUM_DIRECTIONS` — number of discrete ridge-flow orientations sampled (`16`).
45pub(crate) const NUM_DIRECTIONS: i32 = 16;
46
47/// `START_DIR_ANGLE` — orientation of direction index `0`, `M_PI/2` radians (90°).
48///
49/// Stock defines this as `(double)(M_PI/2.0)`; `std::f64::consts::PI` is the exact `f64` nearest to
50/// the same `M_PI` literal, so the bit pattern matches.
51pub(crate) const START_DIR_ANGLE: f64 = std::f64::consts::PI / 2.0;
52
53/// `RMV_VALID_NBR_MIN` — min valid neighbors before an isolated block direction is removed.
54pub(crate) const RMV_VALID_NBR_MIN: i32 = 3;
55
56/// `DIR_STRENGTH_MIN` — minimum direction strength for a block direction to be valid.
57pub(crate) const DIR_STRENGTH_MIN: f64 = 0.2;
58
59/// `DIR_DISTANCE_MAX` — max block distance over which directions are interpolated.
60pub(crate) const DIR_DISTANCE_MAX: i32 = 3;
61
62/// `SMTH_VALID_NBR_MIN` — min valid neighbors required to smooth a block direction.
63pub(crate) const SMTH_VALID_NBR_MIN: i32 = 7;
64
65/// `VORT_VALID_NBR_MIN` — min valid neighbors required for a vorticity measure.
66pub(crate) const VORT_VALID_NBR_MIN: i32 = 7;
67
68/// `HIGHCURV_VORTICITY_MIN` — min vorticity marking a block high-curvature.
69pub(crate) const HIGHCURV_VORTICITY_MIN: i32 = 5;
70
71/// `HIGHCURV_CURVATURE_MIN` — min curvature marking a block high-curvature.
72pub(crate) const HIGHCURV_CURVATURE_MIN: i32 = 5;
73
74/// `MIN_INTERPOLATE_NBRS` — min valid neighbors required to interpolate a direction.
75pub(crate) const MIN_INTERPOLATE_NBRS: i32 = 2;
76
77/// `PERCENTILE_MIN_MAX` — percentile used to derive the min/max block intensities.
78pub(crate) const PERCENTILE_MIN_MAX: i32 = 10;
79
80/// `MIN_CONTRAST_DELTA` — min intensity delta before a block is considered non-low-contrast.
81pub(crate) const MIN_CONTRAST_DELTA: i32 = 5;
82
83// ---------------------------------------------------------------------------
84// DFT controls
85// ---------------------------------------------------------------------------
86
87/// `NUM_DFT_WAVES` — number of DFT frequencies analyzed per block window (`4`).
88pub(crate) const NUM_DFT_WAVES: i32 = 4;
89
90/// `dft_coefs` — the `NUM_DFT_WAVES` frequency coefficients `C`, each a multiple of `PI_FACTOR`
91/// (`globals.c`). Stored as `double`; one/two/three/four periods across the window range.
92pub(crate) const DFT_COEFS: [f64; NUM_DFT_WAVES as usize] = [1.0, 2.0, 3.0, 4.0];
93
94/// `POWMAX_MIN` — min DFT power maximum for a block to carry a dominant direction.
95pub(crate) const POWMAX_MIN: f64 = 100_000.0;
96
97/// `POWNORM_MIN` — min normalized DFT power for a dominant direction.
98pub(crate) const POWNORM_MIN: f64 = 3.8;
99
100/// `POWMAX_MAX` — DFT power maximum above which a block is treated as high-flow.
101pub(crate) const POWMAX_MAX: f64 = 50_000_000.0;
102
103/// `FORK_INTERVAL` — direction interval used when testing for a fork.
104pub(crate) const FORK_INTERVAL: i32 = 2;
105
106/// `FORK_PCT_POWMAX` — fraction of powmax a fork's neighbor must reach.
107pub(crate) const FORK_PCT_POWMAX: f64 = 0.7;
108
109/// `FORK_PCT_POWNORM` — fraction of pownorm a fork's neighbor must reach.
110pub(crate) const FORK_PCT_POWNORM: f64 = 0.75;
111
112// ---------------------------------------------------------------------------
113// Binarization controls
114// ---------------------------------------------------------------------------
115
116/// `DIRBIN_GRID_W` — width of the directional-binarization grid (`7`).
117pub(crate) const DIRBIN_GRID_W: i32 = 7;
118
119/// `DIRBIN_GRID_H` — height of the directional-binarization grid (`9`).
120pub(crate) const DIRBIN_GRID_H: i32 = 9;
121
122/// `NUM_FILL_HOLES` — number of hole-filling passes over the binarized image.
123pub(crate) const NUM_FILL_HOLES: i32 = 3;
124
125// ---------------------------------------------------------------------------
126// Minutiae detection controls
127// ---------------------------------------------------------------------------
128
129/// `MAX_MINUTIA_DELTA` — max pixel delta permitted between adjacent contour points.
130pub(crate) const MAX_MINUTIA_DELTA: i32 = 10;
131
132/// `MAX_HIGH_CURVE_THETA` — max angle (`M_PI/3` rad) still counted as one high-curvature turn.
133///
134/// Stock defines this as `(double)(M_PI/3.0)`.
135pub(crate) const MAX_HIGH_CURVE_THETA: f64 = std::f64::consts::PI / 3.0;
136
137/// `HIGH_CURVE_HALF_CONTOUR` — half-length of the contour walked to test high curvature.
138pub(crate) const HIGH_CURVE_HALF_CONTOUR: i32 = 14;
139
140/// `MIN_LOOP_LEN` — min contour length for a loop to be considered.
141pub(crate) const MIN_LOOP_LEN: i32 = 20;
142
143/// `MIN_LOOP_ASPECT_DIST` — min half-way distance across a loop before its aspect is tested.
144pub(crate) const MIN_LOOP_ASPECT_DIST: f64 = 1.0;
145
146/// `MIN_LOOP_ASPECT_RATIO` — min max/min half-way distance ratio to reject a loop.
147pub(crate) const MIN_LOOP_ASPECT_RATIO: f64 = 2.25;
148
149// ---------------------------------------------------------------------------
150// Minutiae link controls
151// ---------------------------------------------------------------------------
152//
153// The V2 block wires the whole link group to UNUSED_INT/UNUSED_DBL except `maxtrans`, which is
154// reused for overlap removal. Only that one survives here.
155
156/// `MAXTRANS` — max direction transitions tolerated (reused for removing overlaps in V2).
157pub(crate) const MAXTRANS: i32 = 2;
158
159// ---------------------------------------------------------------------------
160// False-minutiae removal controls (VERSION 2)
161// ---------------------------------------------------------------------------
162
163/// `MAX_RMTEST_DIST_V2` — max distance between two minutiae still tested for removal (`16`).
164pub(crate) const MAX_RMTEST_DIST_V2: i32 = 16;
165
166/// `MAX_HOOK_LEN_V2` — max contour length of a hook artifact to remove (`30`).
167pub(crate) const MAX_HOOK_LEN_V2: i32 = 30;
168
169/// `MAX_HALF_LOOP_V2` — max half-loop contour length treated as an artifact (`30`).
170pub(crate) const MAX_HALF_LOOP_V2: i32 = 30;
171
172/// `TRANS_DIR_PIX_V2` — pixel step used when tracing minutia direction transitions (`4`).
173pub(crate) const TRANS_DIR_PIX_V2: i32 = 4;
174
175/// `SMALL_LOOP_LEN` — max contour length of a small loop removed outright.
176pub(crate) const SMALL_LOOP_LEN: i32 = 15;
177
178/// `SIDE_HALF_CONTOUR` — half-contour length used to locate a loop's side points.
179pub(crate) const SIDE_HALF_CONTOUR: i32 = 7;
180
181/// `INV_BLOCK_MARGIN_V2` — margin (in pixels) from an invalid block within which minutiae are
182/// dropped (`4`).
183pub(crate) const INV_BLOCK_MARGIN_V2: i32 = 4;
184
185/// `RM_VALID_NBR_MIN` — min valid neighbor blocks a minutia must have to survive.
186pub(crate) const RM_VALID_NBR_MIN: i32 = 7;
187
188/// `MAX_OVERLAP_DIST` — max distance between two minutiae tested as an overlap.
189pub(crate) const MAX_OVERLAP_DIST: i32 = 8;
190
191/// `MAX_OVERLAP_JOIN_DIST` — max distance over which an overlap pair may be joined.
192pub(crate) const MAX_OVERLAP_JOIN_DIST: i32 = 6;
193
194/// `MALFORMATION_STEPS_1` — first contour step count used in malformation testing.
195pub(crate) const MALFORMATION_STEPS_1: i32 = 10;
196
197/// `MALFORMATION_STEPS_2` — second contour step count used in malformation testing.
198pub(crate) const MALFORMATION_STEPS_2: i32 = 20;
199
200/// `MIN_MALFORMATION_RATIO` — min ratio of the two malformation-step distances.
201pub(crate) const MIN_MALFORMATION_RATIO: f64 = 2.0;
202
203/// `MAX_MALFORMATION_DIST` — max distance over which malformation is tested.
204pub(crate) const MAX_MALFORMATION_DIST: i32 = 20;
205
206/// `PORES_TRANS_R` — translation radius used when testing for pores.
207pub(crate) const PORES_TRANS_R: i32 = 3;
208
209/// `PORES_PERP_STEPS` — perpendicular step count used when testing for pores.
210pub(crate) const PORES_PERP_STEPS: i32 = 12;
211
212/// `PORES_STEPS_FWD` — forward contour steps walked when testing for pores.
213pub(crate) const PORES_STEPS_FWD: i32 = 10;
214
215/// `PORES_STEPS_BWD` — backward contour steps walked when testing for pores.
216pub(crate) const PORES_STEPS_BWD: i32 = 8;
217
218/// `PORES_MIN_DIST2` — min squared distance separating a valid pore pair.
219pub(crate) const PORES_MIN_DIST2: f64 = 0.5;
220
221/// `PORES_MAX_RATIO` — max ratio of forward/backward pore distances.
222pub(crate) const PORES_MAX_RATIO: f64 = 2.25;
223
224// ---------------------------------------------------------------------------
225// Ridge-counting controls
226// ---------------------------------------------------------------------------
227
228/// `MAX_NBRS` — max nearest-neighbor minutiae considered for ridge counting.
229pub(crate) const MAX_NBRS: i32 = 5;
230
231/// `MAX_RIDGE_STEPS` — max steps walked between two minutiae when counting ridges.
232pub(crate) const MAX_RIDGE_STEPS: i32 = 10;
233
234// ---------------------------------------------------------------------------
235// Fixed geometry / scale constants (read directly, outside lfsparms)
236// ---------------------------------------------------------------------------
237
238/// `TRUNC_SCALE` — the `1/16384` quantization scale for `trunc_dbl_precision`, matching the FORTRAN
239/// reference implementation's fixed precision (see `num::trunc_dbl_precision`).
240pub(crate) const TRUNC_SCALE: f64 = 16384.0;
241
242/// `MAX_MINUTIAE` — hard cap on the number of minutiae detected (allocation bound), so kept as a
243/// `usize`.
244// `#[cfg(test)]`: the stock allocation bound. The port grows minutiae in a `Vec` rather than a
245// fixed-size array, so nothing in the pipeline reads this cap; it is transcribed for fidelity to
246// `lfs.h` and compiled only for the test below that pins it.
247#[cfg(test)]
248pub(crate) const MAX_MINUTIAE: usize = 1000;
249
250#[cfg(test)]
251mod tests {
252 use super::*;
253
254 /// Spot-check the interoperability facts that name the task: a typo here silently desyncs the
255 /// whole detector from stock NBIS `xyt` output.
256 #[test]
257 fn named_fixed_values() {
258 assert_eq!(PAD_VALUE, 128);
259 assert_eq!(NUM_DIRECTIONS, 16);
260 assert_eq!(NUM_DFT_WAVES, 4);
261 assert_eq!(MAX_MINUTIAE, 1000);
262 assert_eq!(TRUNC_SCALE, 16384.0);
263 assert_eq!(MAP_BLOCKSIZE_V2, 8);
264 assert_eq!(MAP_WINDOWSIZE_V2, 24);
265 assert_eq!(MAP_WINDOWOFFSET_V2, 8);
266 }
267
268 /// The `dft_coefs` array is `{1,2,3,4}` and exactly `NUM_DFT_WAVES` long.
269 #[test]
270 fn dft_coefs_match_globals() {
271 assert_eq!(DFT_COEFS, [1.0, 2.0, 3.0, 4.0]);
272 assert_eq!(DFT_COEFS.len(), NUM_DFT_WAVES as usize);
273 }
274
275 /// Stock derives both angles from `M_PI`; confirm the `std::f64::consts::PI` substitution is the
276 /// same `f64` and the arithmetic (`/2`, `/3`) lands on the expected radians.
277 #[test]
278 fn angles_from_pi() {
279 assert_eq!(START_DIR_ANGLE, std::f64::consts::FRAC_PI_2);
280 assert_eq!(MAX_HIGH_CURVE_THETA, std::f64::consts::PI / 3.0);
281 // 90 degrees / 60 degrees, to a tight tolerance.
282 assert!((START_DIR_ANGLE.to_degrees() - 90.0).abs() < 1e-9);
283 assert!((MAX_HIGH_CURVE_THETA.to_degrees() - 60.0).abs() < 1e-9);
284 }
285
286 /// The V2 map window is centered on its block: `windowsize == blocksize + 2 * windowoffset`
287 /// (`8 + 2*8 == 24`). This relationship is load-bearing for block/window addressing.
288 #[test]
289 fn v2_window_geometry_invariant() {
290 assert_eq!(
291 MAP_WINDOWSIZE_V2,
292 MAP_BLOCKSIZE_V2 + 2 * MAP_WINDOWOFFSET_V2
293 );
294 }
295}