Skip to main content

fprint_mindtct/
xyt.rs

1// SPDX-FileCopyrightText: 2026 fprintd (pure-Rust) contributors
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5//! Coordinate and angle conversion to NIST `xyt` output (`lfs2nist_minutia_XYT` and the M1 variant):
6//! `y = ih - y`, `theta = (270 - sround(dir * degrees_per_unit)) % 360`. This is the one place the
7//! port uses `f32` (`degrees_per_unit`), matching the stock reference exactly.
8//!
9//! Ports `xytreps.c` (`lfs2nist_minutia_XYT` L80, `lfs2m1_minutia_XYT` L122) and the output-side
10//! quality/order contract of `results.c` (`write_minutiae_XYTQ` L268, `q = sround(reliability*100)`,
11//! list order preserved). A [`DetMinutia`] carries LFS-native attributes — pixel coordinates with
12//! origin top-left, an integer `direction` on `0..2*num_directions`, and a `reliability` in
13//! `[0.0, 1.0]`; these routines convert one such point (or a whole list) into the crate's public
14//! [`Minutia`] in the requested representation. The seam consumes the NIST form.
15
16use crate::consts::NUM_DIRECTIONS;
17use crate::detect::DetMinutia;
18use crate::num::sround;
19use crate::Minutia;
20
21/// Degrees per quantized direction unit — stock `degrees_per_unit = 180 / (float)NUM_DIRECTIONS`
22/// (`xytreps.c` L98/L138), evaluated in **single precision** to match the reference bit-for-bit.
23///
24/// This is the sole `f32` in the port. With `NUM_DIRECTIONS == 16` the value is exactly `11.25`,
25/// which (like every `direction * 11.25` product over the valid `0..2*num_directions` range) is
26/// representable in both `f32` and `f64`, so the single-precision evaluation never diverges from a
27/// double-precision one here — the `f32` is kept purely for faithful transcription.
28#[inline]
29fn degrees_per_unit() -> f32 {
30    180.0 / NUM_DIRECTIONS as f32
31}
32
33/// `sround(direction * degrees_per_unit)` — the rounded integer degrees for a quantized direction.
34///
35/// Faithful to the C evaluation order: `direction * degrees_per_unit` is computed in `f32` (the int
36/// operand is promoted to the `float` `degrees_per_unit`), then the `sround` macro's `± 0.5` add and
37/// `(int)` truncation happen after promotion to `f64` — exactly `sround(f64::from(prod))`.
38#[inline]
39fn direction_degrees(direction: i32) -> i32 {
40    let prod: f32 = direction as f32 * degrees_per_unit();
41    sround(f64::from(prod))
42}
43
44/// `q = sround(reliability * 100.0)` — the integer minutia quality on `[0..100]`
45/// (`results.c` L321 / `xytreps.c` L174). `reliability` arithmetic is `f64`, as in stock.
46#[inline]
47fn quality(reliability: f64) -> i32 {
48    sround(reliability * 100.0)
49}
50
51/// Convert one minutia to the **NIST internal** `xyt` representation — port of `lfs2nist_minutia_XYT`
52/// (`xytreps.c` L80), with the quality added from `results.c` L321.
53///
54/// NIST internal rep: pixel origin **bottom-left** (`y = ih - y`), orientation in whole degrees on
55/// `[0..360)` with 0 east and increasing counter-clockwise, pointing out and away from the ridge
56/// ending / bifurcation valley. `iw` is unused by the stock routine (only `ih` flips the origin), so
57/// it is omitted from the signature.
58pub(crate) fn lfs2nist_minutia_xyt(minutia: &DetMinutia, ih: i32) -> Minutia {
59    // PORT L95-L96: x unchanged; y flipped to a bottom-left origin.
60    let x = minutia.x;
61    let y = ih - minutia.y;
62
63    // PORT L100-L103: (270 - degrees) mod 360, folded back onto [0..360).
64    let mut t = (270 - direction_degrees(minutia.direction)) % 360;
65    if t < 0 {
66        t += 360;
67    }
68
69    Minutia {
70        x,
71        y,
72        theta: t,
73        quality: quality(minutia.reliability),
74    }
75}
76
77/// Convert one minutia to the **M1 (ANSI INCITS 378-2004)** `xyt` representation — port of
78/// `lfs2m1_minutia_XYT` (`xytreps.c` L122), with the quality added from `results.c` L321.
79///
80/// M1 rep: pixel origin **top-left** (`x`, `y` unchanged), direction pointing *up* the ridge ending /
81/// bifurcation valley (opposite the NIST form), and orientation quantized in units of 2° so the final
82/// angle is halved onto `[0..179]`.
83///
84/// The NIST-internal form ([`lfs2nist_format`]) is the seam's only consumed representation. M1 (ANSI
85/// INCITS 378-2004) is an external-interchange format, and the crate exposes no public export API, so
86/// nothing outside the tests reaches these converters — they are compiled only for the suite that pins
87/// their arithmetic. Paired with the `#[cfg(test)]` on [`lfs2m1_format`].
88#[cfg(test)]
89pub(crate) fn lfs2m1_minutia_xyt(minutia: &DetMinutia) -> Minutia {
90    // PORT L135-L136: coordinates unchanged (top-left origin).
91    let x = minutia.x;
92    let y = minutia.y;
93
94    // PORT L139-L142: (90 - degrees) mod 360, folded back onto [0..360).
95    let mut t = (90 - direction_degrees(minutia.direction)) % 360;
96    if t < 0 {
97        t += 360;
98    }
99    // PORT L145: angles are in units of 2 degrees, so range is 0..179.
100    t /= 2;
101
102    Minutia {
103        x,
104        y,
105        theta: t,
106        quality: quality(minutia.reliability),
107    }
108}
109
110/// Convert a whole minutiae list to the NIST internal `xyt` representation, list order preserved —
111/// the `write_minutiae_XYTQ(NIST_INTERNAL_XYT_REP)` contract (`results.c` L268, L304-L324). This is
112/// the form the native seam consumes.
113pub(crate) fn lfs2nist_format(minutiae: &[DetMinutia], ih: i32) -> Vec<Minutia> {
114    minutiae
115        .iter()
116        .map(|m| lfs2nist_minutia_xyt(m, ih))
117        .collect()
118}
119
120/// Convert a whole minutiae list to the M1 `xyt` representation, list order preserved — the
121/// `write_minutiae_XYTQ(M1_XYT_REP)` contract (`results.c` L268, L304-L324).
122///
123/// See [`lfs2m1_minutia_xyt`] — the M1 batch converter has no lib caller; it is compiled only for the
124/// `#[cfg(test)]` suite that pins its arithmetic.
125#[cfg(test)]
126pub(crate) fn lfs2m1_format(minutiae: &[DetMinutia]) -> Vec<Minutia> {
127    minutiae.iter().map(lfs2m1_minutia_xyt).collect()
128}
129
130#[cfg(test)]
131mod tests {
132    use super::*;
133
134    /// Build a `DetMinutia` carrying only the fields the `xyt` stage reads; the rest are inert.
135    fn det(x: i32, y: i32, direction: i32, reliability: f64) -> DetMinutia {
136        DetMinutia {
137            x,
138            y,
139            ex: 0,
140            ey: 0,
141            direction,
142            reliability,
143            kind: 0,
144            appearing: true,
145            feature_id: 0,
146            nbrs: Vec::new(),
147            ridge_counts: Vec::new(),
148        }
149    }
150
151    /// `degrees_per_unit` is exactly `11.25` at `NUM_DIRECTIONS == 16`, in `f32`.
152    #[test]
153    fn degrees_per_unit_is_11_25_f32() {
154        assert_eq!(degrees_per_unit(), 11.25_f32);
155    }
156
157    /// `direction * 11.25` is exact for the whole valid `0..2*num_directions` range, so the `f32`
158    /// evaluation equals a straight `f64` computation — no rounding surprises before `sround`.
159    #[test]
160    fn direction_degrees_matches_exact_scaling() {
161        for direction in 0..2 * NUM_DIRECTIONS {
162            let expect = sround(f64::from(direction) * 11.25);
163            assert_eq!(direction_degrees(direction), expect, "dir={direction}");
164        }
165        // Spot values: 8 -> 90, 12 -> 135, 24 -> 270, 25 -> sround(281.25) == 281.
166        assert_eq!(direction_degrees(8), 90);
167        assert_eq!(direction_degrees(12), 135);
168        assert_eq!(direction_degrees(24), 270);
169        assert_eq!(direction_degrees(25), 281);
170    }
171
172    /// NIST form: `x` unchanged, `y` flipped by `ih`, `theta = (270 - degrees) mod 360`.
173    #[test]
174    fn nist_coordinate_and_angle() {
175        // direction 0 -> degrees 0 -> theta 270; y flips about ih=100.
176        let m = lfs2nist_minutia_xyt(&det(30, 40, 0, 1.0), 100);
177        assert_eq!((m.x, m.y, m.theta), (30, 60, 270));
178
179        // direction 8 -> degrees 90 -> theta 180.
180        assert_eq!(lfs2nist_minutia_xyt(&det(0, 0, 8, 1.0), 100).theta, 180);
181
182        // direction 12 -> degrees 135 -> theta 135.
183        assert_eq!(lfs2nist_minutia_xyt(&det(0, 0, 12, 1.0), 100).theta, 135);
184    }
185
186    /// NIST form: an angle whose raw `270 - degrees` goes negative must wrap by `+360`.
187    #[test]
188    fn nist_angle_wraps_positive() {
189        // direction 25 -> degrees 281 -> 270-281 = -11 -> +360 = 349.
190        assert_eq!(lfs2nist_minutia_xyt(&det(0, 0, 25, 1.0), 100).theta, 349);
191        // direction 24 -> degrees 270 -> theta 0 (boundary, no wrap).
192        assert_eq!(lfs2nist_minutia_xyt(&det(0, 0, 24, 1.0), 100).theta, 0);
193    }
194
195    /// M1 form: coordinates unchanged (top-left origin), `theta = ((90 - degrees) mod 360) / 2`.
196    #[test]
197    fn m1_coordinate_and_angle() {
198        // direction 0 -> degrees 0 -> (90) / 2 = 45; coordinates pass through.
199        let m = lfs2m1_minutia_xyt(&det(30, 40, 0, 1.0));
200        assert_eq!((m.x, m.y, m.theta), (30, 40, 45));
201
202        // direction 8 -> degrees 90 -> (0) / 2 = 0.
203        assert_eq!(lfs2m1_minutia_xyt(&det(0, 0, 8, 1.0)).theta, 0);
204
205        // direction 24 -> degrees 270 -> 90-270 = -180 -> +360 = 180 -> /2 = 90.
206        assert_eq!(lfs2m1_minutia_xyt(&det(0, 0, 24, 1.0)).theta, 90);
207    }
208
209    /// Quality is `sround(reliability * 100)` — half rounds away from zero.
210    #[test]
211    fn quality_rounds_reliability() {
212        assert_eq!(lfs2nist_minutia_xyt(&det(0, 0, 0, 0.99), 100).quality, 99);
213        assert_eq!(lfs2nist_minutia_xyt(&det(0, 0, 0, 0.995), 100).quality, 100);
214        assert_eq!(lfs2nist_minutia_xyt(&det(0, 0, 0, 0.0), 100).quality, 0);
215        assert_eq!(lfs2m1_minutia_xyt(&det(0, 0, 0, 1.0)).quality, 100);
216    }
217
218    /// Both batch converters preserve list order and match the per-minutia routines.
219    #[test]
220    fn format_preserves_order() {
221        let list = [det(1, 2, 0, 1.0), det(3, 4, 8, 0.5), det(5, 6, 12, 0.25)];
222
223        let nist = lfs2nist_format(&list, 100);
224        assert_eq!(nist.len(), 3);
225        for (i, m) in list.iter().enumerate() {
226            assert_eq!(nist[i], lfs2nist_minutia_xyt(m, 100));
227        }
228
229        let m1 = lfs2m1_format(&list);
230        assert_eq!(m1.len(), 3);
231        for (i, m) in list.iter().enumerate() {
232            assert_eq!(m1[i], lfs2m1_minutia_xyt(m));
233        }
234    }
235}