1use crate::{q_hash, NQuin};
6
7use super::Tensor10D;
8
9pub const PRED_GEO_VERTEX: u64 = q_hash("geo:hasVertex");
10pub const PRED_GEO_PACKED_CENTROID: u64 = q_hash("geo:hasPackedCentroid");
11pub const PRED_GEO_PACKED_BBOX_MIN: u64 = q_hash("geo:hasPackedBboxMin");
12pub const PRED_GEO_PACKED_BBOX_MAX: u64 = q_hash("geo:hasPackedBboxMax");
13
14pub const PRED_HAS_SPECTRAL_SHEET: u64 = q_hash("q42:hasSpectralSheet");
16
17#[repr(u8)]
19#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
20pub enum ScaleTier {
21 MillimeterDefault = 0,
23 Nanometer = 1,
25 Micrometer = 2,
27 Meter = 3,
29 Kilometer = 4,
31 Megameter = 5,
33 Astronomical = 6,
35 Parsec = 7,
37}
38
39impl Default for ScaleTier {
40 fn default() -> Self {
41 ScaleTier::MillimeterDefault
42 }
43}
44
45impl ScaleTier {
46 pub fn from_canonical_exponent_tier(s: u8) -> Self {
48 match s {
49 0 => ScaleTier::Nanometer,
50 1 => ScaleTier::Micrometer,
51 2 => ScaleTier::MillimeterDefault,
52 3 => ScaleTier::Meter,
53 4 => ScaleTier::Kilometer,
54 5 => ScaleTier::Megameter,
55 6 => ScaleTier::Astronomical,
56 7 => ScaleTier::Parsec,
57 _ => ScaleTier::MillimeterDefault,
58 }
59 }
60
61 pub fn from_u8(raw: u8) -> Self {
63 match raw & 0x7 {
64 0 => ScaleTier::MillimeterDefault,
65 1 => ScaleTier::Nanometer,
66 2 => ScaleTier::Micrometer,
67 3 => ScaleTier::Meter,
68 4 => ScaleTier::Kilometer,
69 5 => ScaleTier::Megameter,
70 6 => ScaleTier::Astronomical,
71 7 => ScaleTier::Parsec,
72 _ => ScaleTier::MillimeterDefault,
73 }
74 }
75
76 pub fn step_meters(self) -> f64 {
78 match self {
79 ScaleTier::MillimeterDefault => 1e-3,
80 ScaleTier::Nanometer => 1e-9,
81 ScaleTier::Micrometer => 1e-6,
82 ScaleTier::Meter => 1.0,
83 ScaleTier::Kilometer => 1e3,
84 ScaleTier::Megameter => 1e6,
85 ScaleTier::Astronomical => 1e9,
86 ScaleTier::Parsec => 1e12,
87 }
88 }
89}
90
91#[inline]
93pub fn encode_scaled_coord(x_m: f64, y_m: f64, z_m: f64, tier: ScaleTier) -> u64 {
94 let step = tier.step_meters();
95 let xi = (x_m / step).round().clamp(-524288.0, 524287.0) as i64 & 0xFFFFF;
96 let yi = (y_m / step).round().clamp(-524288.0, 524287.0) as i64 & 0xFFFFF;
97 let zi = (z_m / step).round().clamp(-524288.0, 524287.0) as i64 & 0xFFFFF;
98 let tier_bits = ((tier as u8 as u64) & 0x7) << 60;
99 tier_bits | ((xi as u64) << 40) | ((yi as u64) << 20) | (zi as u64)
100}
101
102#[inline]
104pub fn decode_scaled_coord(object: u64) -> (f64, f64, f64, ScaleTier) {
105 let tier_raw = ((object >> 60) & 0x7) as u8;
106 let tier = ScaleTier::from_u8(tier_raw);
107 let step = tier.step_meters();
108 let xi = sign_extend_20(((object >> 40) & 0xFFFFF) as u32);
109 let yi = sign_extend_20(((object >> 20) & 0xFFFFF) as u32);
110 let zi = sign_extend_20((object & 0xFFFFF) as u32);
111 (xi as f64 * step, yi as f64 * step, zi as f64 * step, tier)
112}
113
114pub fn migrate_unscaled_mm_quin(quin: &NQuin, target_tier: ScaleTier) -> NQuin {
116 let (x, y, z) = decode_packed_coord(quin.object);
117 let new_object = encode_scaled_coord(x as f64, y as f64, z as f64, target_tier);
118 let mut updated = *quin;
119 updated.object = new_object;
120 updated.parity = updated.subject ^ updated.predicate ^ updated.object ^ updated.context;
121 updated
122}
123
124pub fn audio_sidecar_relpath(digest: &[u8; 32], out: &mut [u8]) -> usize {
127 const PREFIX: &[u8] = b"spectral/audio/";
128 const SUFFIX: &[u8] = b".qac";
129 const HEX: &[u8; 16] = b"0123456789abcdef";
130 let need = PREFIX.len() + 64 + SUFFIX.len();
131 if out.len() < need {
132 return 0;
133 }
134 out[..PREFIX.len()].copy_from_slice(PREFIX);
135 for (i, byte) in digest.iter().enumerate() {
136 out[PREFIX.len() + i * 2] = HEX[usize::from(byte >> 4)];
137 out[PREFIX.len() + i * 2 + 1] = HEX[usize::from(byte & 15)];
138 }
139 out[PREFIX.len() + 64..need].copy_from_slice(SUFFIX);
140 need
141}
142
143#[inline]
145pub fn sigma_sheet_index_from_nquin(nquin: &NQuin) -> Option<u32> {
146 let pred = nquin.predicate & 0x0FFF_FFFF_FFFF_FFFF;
147 if pred != (PRED_HAS_SPECTRAL_SHEET & 0x0FFF_FFFF_FFFF_FFFF) {
148 return None;
149 }
150 let idx = (nquin.object & 0x0FFF_FFFF_FFFF_FFFF) as u32;
151 Some(idx)
152}
153
154#[inline]
159pub fn decode_packed_coord(object: u64) -> (f32, f32, f32) {
160 let xi = sign_extend_20(((object >> 40) & 0xfffff) as u32);
161 let yi = sign_extend_20(((object >> 20) & 0xfffff) as u32);
162 let zi = sign_extend_20((object & 0xfffff) as u32);
163 let tier_raw = ((object >> 60) & 0x7) as u8;
164 if tier_raw == 0 {
165 (xi as f32 / 1000.0, yi as f32 / 1000.0, zi as f32 / 1000.0)
166 } else {
167 let step = ScaleTier::from_u8(tier_raw).step_meters() as f32;
168 (xi as f32 * step, yi as f32 * step, zi as f32 * step)
169 }
170}
171
172#[inline]
173fn sign_extend_20(v: u32) -> i32 {
174 let v = v & 0xfffff;
175 if v & 0x8_0000 != 0 {
176 (v | !0xfffff) as i32
177 } else {
178 v as i32
179 }
180}
181
182#[inline]
184pub fn is_geo_vertex_quin(nquin: &NQuin) -> bool {
185 let masked_7f = nquin.predicate & 0x7FFF_FFFF_FFFF_FF00;
186 let masked_0f = nquin.predicate & 0x0FFF_FFFF_FFFF_FFFF;
187 let matches = |pred: u64| masked_7f == pred || masked_0f == (pred & 0x0FFF_FFFF_FFFF_FFFF);
188 matches(PRED_GEO_VERTEX)
189 || matches(PRED_GEO_PACKED_CENTROID)
190 || matches(PRED_GEO_PACKED_BBOX_MIN)
191 || matches(PRED_GEO_PACKED_BBOX_MAX)
192}
193
194#[inline]
196pub fn semantic_xyz_from_nquin(nquin: &NQuin) -> (f32, f32, f32) {
197 if is_geo_vertex_quin(nquin) && (nquin.object >> 63) == 0 {
198 return decode_packed_coord(nquin.object);
199 }
200 let hash = nquin.object & 0x0FFF_FFFF_FFFF_FFFF;
201 let x = (hash & 0xFFFF) as f32 / 65535.0;
202 let y = ((hash >> 16) & 0xFFFF) as f32 / 65535.0;
203 let z = ((hash >> 32) & 0xFFFF) as f32 / 65535.0;
204 (x, y, z)
205}
206
207#[inline]
209pub fn bake_quin_to_tensor(nquin: &NQuin) -> Tensor10D {
210 let q = if (nquin.metadata >> 60) & 0xF != 0 {
211 0.25
212 } else {
213 0.0
214 };
215 let v = ((nquin.context >> 32) & 0x7) as f32;
216 let w = ((nquin.context >> 40) & 0xF) as f32;
217 let (x, y, z) = semantic_xyz_from_nquin(nquin);
218 let t = ((nquin.metadata >> 32) & 0x1FFF_FFFF) as f32;
219 let payload = nquin.metadata & 0xFFFF_FFFF;
220 let alpha = (payload & 0xFF) as f32 / 255.0;
221 let mu = ((payload >> 8) & 0xFF) as f32 / 255.0;
222 let sigma = ((payload >> 16) & 0xFF) as f32 / 255.0;
223 if q > 0.0 {
224 Tensor10D::parallel_context(q, v, w, x, y, z, t, alpha.max(0.1), mu, sigma)
225 } else {
226 Tensor10D::ground_truth(v, w, x, y, z, t, alpha.max(0.1), mu, sigma)
227 }
228}
229
230pub fn bake_quins_into(quins: &[NQuin], out: &mut [Tensor10D]) -> usize {
232 let n = quins.len().min(out.len());
233 for i in 0..n {
234 out[i] = bake_quin_to_tensor(&quins[i]);
235 }
236 n
237}
238
239#[cfg(test)]
240mod tests {
241 use super::*;
242 use crate::NQuin;
243
244 fn pack_coord(x: f32, y: f32, z: f32) -> u64 {
245 let xi = (x * 1000.0).round() as i64 & 0xfffff;
246 let yi = (y * 1000.0).round() as i64 & 0xfffff;
247 let zi = (z * 1000.0).round() as i64 & 0xfffff;
248 ((xi as u64) << 40) | ((yi as u64) << 20) | (zi as u64)
249 }
250
251 #[test]
252 fn packed_coord_round_trip() {
253 let (x, y, z) = decode_packed_coord(pack_coord(1.25, -2.5, 3.75));
254 assert!((x - 1.25).abs() < 0.002);
255 assert!((y + 2.5).abs() < 0.002);
256 assert!((z - 3.75).abs() < 0.002);
257 }
258
259 #[test]
260 fn audio_sidecar_path_format() {
261 let mut digest = [0u8; 32];
262 digest[0] = 0xab;
263 digest[31] = 0xcd;
264 let mut buf = [0xa5; 96];
265 let n = audio_sidecar_relpath(&digest, &mut buf);
266 assert_eq!(n, b"spectral/audio/".len() + 64 + b".qac".len());
267 assert_eq!(
268 std::str::from_utf8(&buf[..n]).unwrap(),
269 "spectral/audio/ab000000000000000000000000000000000000000000000000000000000000cd.qac"
270 );
271 assert!(buf[n..].iter().all(|x| *x == 0xa5));
272 let mut small = [0xa5; 82];
273 assert_eq!(audio_sidecar_relpath(&digest, &mut small), 0);
274 assert!(small.iter().all(|x| *x == 0xa5));
275 }
276
277 #[test]
278 fn spectral_sheet_predicate_extracts_index() {
279 let mut q = NQuin::default();
280 q.predicate = PRED_HAS_SPECTRAL_SHEET;
281 q.object = 42;
282 assert_eq!(sigma_sheet_index_from_nquin(&q), Some(42));
283 }
284
285 #[test]
286 fn geo_vertex_bake_uses_packed_xyz() {
287 let mut q = NQuin::default();
288 q.predicate = PRED_GEO_VERTEX;
289 q.object = pack_coord(0.1, 0.2, 0.3);
290 q.metadata = 42 << 32;
291 let t = bake_quin_to_tensor(&q);
292 assert!((t.x - 0.1).abs() < 0.002);
293 assert!((t.y - 0.2).abs() < 0.002);
294 assert!((t.z - 0.3).abs() < 0.002);
295 assert!(t.is_ground_truth());
296 }
297
298 #[test]
299 fn test_multi_scale_packing_across_all_eight_tiers() {
300 let tiers = [
301 ScaleTier::MillimeterDefault,
302 ScaleTier::Nanometer,
303 ScaleTier::Micrometer,
304 ScaleTier::Meter,
305 ScaleTier::Kilometer,
306 ScaleTier::Megameter,
307 ScaleTier::Astronomical,
308 ScaleTier::Parsec,
309 ];
310
311 for tier in tiers {
312 let step = tier.step_meters();
313 let xm = 42.0 * step;
314 let ym = -17.0 * step;
315 let zm = 100.0 * step;
316
317 let packed = encode_scaled_coord(xm, ym, zm, tier);
318 let (dx, dy, dz, decoded_tier) = decode_scaled_coord(packed);
319
320 assert_eq!(decoded_tier, tier);
321 assert!((dx - xm).abs() / step < 0.5, "Tier {tier:?} x error");
322 assert!((dy - ym).abs() / step < 0.5, "Tier {tier:?} y error");
323 assert!((dz - zm).abs() / step < 0.5, "Tier {tier:?} z error");
324
325 let (px, py, pz) = decode_packed_coord(packed);
327 assert!((px as f64 - xm).abs() / step < 0.5);
328 assert!((py as f64 - ym).abs() / step < 0.5);
329 assert!((pz as f64 - zm).abs() / step < 0.5);
330 }
331 }
332
333 #[test]
334 fn test_canonical_exponent_mapping() {
335 assert_eq!(
336 ScaleTier::from_canonical_exponent_tier(0),
337 ScaleTier::Nanometer
338 );
339 assert_eq!(
340 ScaleTier::from_canonical_exponent_tier(1),
341 ScaleTier::Micrometer
342 );
343 assert_eq!(
344 ScaleTier::from_canonical_exponent_tier(2),
345 ScaleTier::MillimeterDefault
346 );
347 assert_eq!(ScaleTier::from_canonical_exponent_tier(3), ScaleTier::Meter);
348 assert_eq!(
349 ScaleTier::from_canonical_exponent_tier(4),
350 ScaleTier::Kilometer
351 );
352 assert_eq!(
353 ScaleTier::from_canonical_exponent_tier(5),
354 ScaleTier::Megameter
355 );
356 assert_eq!(
357 ScaleTier::from_canonical_exponent_tier(6),
358 ScaleTier::Astronomical
359 );
360 assert_eq!(
361 ScaleTier::from_canonical_exponent_tier(7),
362 ScaleTier::Parsec
363 );
364 }
365
366 #[test]
367 fn test_geo_predicates_and_migration() {
368 let preds = [
369 PRED_GEO_VERTEX,
370 PRED_GEO_PACKED_CENTROID,
371 PRED_GEO_PACKED_BBOX_MIN,
372 PRED_GEO_PACKED_BBOX_MAX,
373 ];
374 for pred in preds {
375 let mut q = NQuin::default();
376 q.predicate = pred;
377 assert!(is_geo_vertex_quin(&q));
378 }
379
380 let mut q = NQuin::default();
382 q.predicate = PRED_GEO_PACKED_CENTROID;
383 q.object = pack_coord(5.0, -10.0, 15.0); let migrated = migrate_unscaled_mm_quin(&q, ScaleTier::Meter);
385
386 let (x, y, z, tier) = decode_scaled_coord(migrated.object);
387 assert_eq!(tier, ScaleTier::Meter);
388 assert!((x - 5.0).abs() < 1e-3);
389 assert!((y - (-10.0)).abs() < 1e-3);
390 assert!((z - 15.0).abs() < 1e-3);
391 }
392}