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}