1use crate::types::Detection;
10
11pub const P_VISUAL_OBSERVATION: &str = "https://ns.webizen.org/q42/VisualObservation";
13pub const P_PROPOSES_CLASS: &str = "https://ns.webizen.org/q42/proposesClass";
14pub const P_HAS_BBOX: &str = "https://ns.webizen.org/q42/hasBoundingBox";
15pub const P_HAS_TRACK: &str = "https://ns.webizen.org/q42/hasTrackId";
16pub const P_HUMAN_REJECTS: &str = "https://ns.webizen.org/q42/humanRejects";
17pub const P_HUMAN_CORRECTS: &str = "https://ns.webizen.org/q42/humanCorrectsClass";
18pub const P_MODEL_DIGEST: &str = "https://ns.webizen.org/q42/modelDigest";
19pub const CTX_VISION: &str = "https://ns.webizen.org/q42/vision-observation";
20pub const CTX_HUMAN_ATTESTATION: &str = "https://ns.webizen.org/q42/human-attestation";
21
22pub const MAX_OBS_QUINS: usize = 256;
24
25#[repr(C)]
27#[derive(Debug, Clone, Copy, PartialEq, Eq)]
28pub struct VisionQuin {
29 pub subject: u64,
30 pub predicate: u64,
31 pub object: u64,
32 pub context: u64,
33 pub metadata: u64,
34 pub parity: u64,
35}
36
37impl VisionQuin {
38 #[inline]
39 pub fn with_parity(
41 subject: u64,
42 predicate: u64,
43 object: u64,
44 context: u64,
45 metadata: u64,
46 ) -> Self {
47 let parity = subject ^ predicate ^ object ^ context ^ metadata;
48 Self {
49 subject,
50 predicate,
51 object,
52 context,
53 metadata,
54 parity,
55 }
56 }
57}
58
59#[derive(Debug, Clone, Copy, PartialEq, Eq)]
61pub struct MediaDigest {
62 pub hash: u64,
63 pub byte_len: u64,
64}
65
66#[inline]
68pub fn q_hash(s: &str) -> u64 {
69 const FNV_OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
70 const FNV_PRIME: u64 = 0x100_0000_01b3;
71 let mut h = FNV_OFFSET;
72 for b in s.as_bytes() {
73 h ^= *b as u64;
74 h = h.wrapping_mul(FNV_PRIME);
75 }
76 h
77}
78
79#[inline]
80pub fn q_hash_bytes(bytes: &[u8]) -> u64 {
82 const FNV_OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
83 const FNV_PRIME: u64 = 0x100_0000_01b3;
84 let mut h = FNV_OFFSET;
85 for b in bytes {
86 h ^= *b as u64;
87 h = h.wrapping_mul(FNV_PRIME);
88 }
89 h
90}
91
92pub fn media_digest(bytes: &[u8]) -> MediaDigest {
94 let take = bytes.len().min(65_536);
95 let mut h = q_hash_bytes(&bytes[..take]);
96 h ^= (bytes.len() as u64).wrapping_mul(0x9e37_79b9_7f4a_7c15);
98 MediaDigest {
99 hash: h,
100 byte_len: bytes.len() as u64,
101 }
102}
103
104pub fn observation_quin(media: MediaDigest, det: &Detection, model_hash: u64) -> VisionQuin {
106 let subject = media.hash;
107 let predicate = q_hash(P_VISUAL_OBSERVATION);
108 let object = det.instance_hash;
109 let context = q_hash(CTX_VISION) ^ model_hash;
110 let metadata =
112 (det.score_u16 as u64) | ((det.frame_index as u64) << 16) | ((det.flags as u64) << 48);
113 VisionQuin::with_parity(subject, predicate, object, context, metadata)
114}
115
116pub fn class_proposal_quin(det: &Detection, model_hash: u64) -> VisionQuin {
118 let subject = det.instance_hash;
119 let predicate = q_hash(P_PROPOSES_CLASS);
120 let object = det.class_hash;
121 let context = q_hash(CTX_VISION) ^ model_hash;
122 let metadata = det.score_u16 as u64;
123 VisionQuin::with_parity(subject, predicate, object, context, metadata)
124}
125
126#[inline]
128pub fn pack_bbox_u64(det: &Detection) -> u64 {
129 (det.x_min_u16 as u64)
130 | ((det.y_min_u16 as u64) << 16)
131 | ((det.x_max_u16 as u64) << 32)
132 | ((det.y_max_u16 as u64) << 48)
133}
134
135#[inline]
136pub fn unpack_bbox_u64(v: u64) -> (u16, u16, u16, u16) {
138 (
139 (v & 0xFFFF) as u16,
140 ((v >> 16) & 0xFFFF) as u16,
141 ((v >> 32) & 0xFFFF) as u16,
142 ((v >> 48) & 0xFFFF) as u16,
143 )
144}
145
146pub fn bbox_quin(det: &Detection, model_hash: u64) -> VisionQuin {
148 let subject = det.instance_hash;
149 let predicate = q_hash(P_HAS_BBOX);
150 let object = pack_bbox_u64(det);
151 let context = q_hash(CTX_VISION) ^ model_hash;
152 let metadata = det.score_u16 as u64 | ((det.frame_index as u64) << 16);
153 VisionQuin::with_parity(subject, predicate, object, context, metadata)
154}
155
156pub fn track_quin(det: &Detection, model_hash: u64) -> VisionQuin {
158 let subject = det.instance_hash;
159 let predicate = q_hash(P_HAS_TRACK);
160 let object = det.track_id as u64;
161 let context = q_hash(CTX_VISION) ^ model_hash;
162 let metadata = det.frame_index as u64;
163 VisionQuin::with_parity(subject, predicate, object, context, metadata)
164}
165
166pub fn format_detection_text_description(det: &Detection, class_name: &str) -> String {
168 let score_pct = (det.score_u16 as f32 / 65535.0) * 100.0;
169 let x_min = (det.x_min_u16 as f32 / 65535.0) * 100.0;
170 let y_min = (det.y_min_u16 as f32 / 65535.0) * 100.0;
171 let w = ((det.x_max_u16.saturating_sub(det.x_min_u16)) as f32 / 65535.0) * 100.0;
172 let h = ((det.y_max_u16.saturating_sub(det.y_min_u16)) as f32 / 65535.0) * 100.0;
173
174 let track_info = if det.track_id > 0 {
175 format!(" (Track #{})", det.track_id)
176 } else {
177 String::new()
178 };
179
180 format!(
181 "Detected '{class_name}' (confidence {score_pct:.1}%){track_info} at bbox [x: {x_min:.1}%, y: {y_min:.1}%, w: {w:.1}%, h: {h:.1}%] in frame {}",
182 det.frame_index
183 )
184}
185
186pub fn format_detection_turtle_rdf(det: &Detection, class_name: &str, media_hash: u64) -> String {
188 let score = det.score_u16 as f32 / 65535.0;
189 let x_min = det.x_min_u16 as f32 / 65535.0;
190 let y_min = det.y_min_u16 as f32 / 65535.0;
191 let x_max = det.x_max_u16 as f32 / 65535.0;
192 let y_max = det.y_max_u16 as f32 / 65535.0;
193
194 format!(
195 r#"@prefix q42: <https://ns.webizen.org/q42/> .
196@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
197@prefix schema: <http://schema.org/> .
198@prefix prov: <http://www.w3.org/ns/prov#> .
199
200<urn:q42:instance:{inst_hash:016x}> a q42:DetectedObject ;
201 rdfs:label "{class_name}" ;
202 schema:confidence {score:.4} ;
203 q42:classHash "{class_hash:016x}" ;
204 q42:frameIndex {frame_index} ;
205 q42:trackId {track_id} ;
206 q42:boundingBox [
207 q42:xMin {x_min:.4} ;
208 q42:yMin {y_min:.4} ;
209 q42:xMax {x_max:.4} ;
210 q42:yMax {y_max:.4}
211 ] ;
212 prov:wasDerivedFrom <urn:q42:media:{media_hash:016x}> .
213"#,
214 inst_hash = det.instance_hash,
215 class_name = class_name,
216 score = score,
217 class_hash = det.class_hash,
218 frame_index = det.frame_index,
219 track_id = det.track_id,
220 x_min = x_min,
221 y_min = y_min,
222 x_max = x_max,
223 y_max = y_max,
224 media_hash = media_hash
225 )
226}
227
228pub fn human_reject_quin(human_did_hash: u64, instance_hash: u64, reason_hash: u64) -> VisionQuin {
231 VisionQuin::with_parity(
232 human_did_hash,
233 q_hash(P_HUMAN_REJECTS),
234 instance_hash,
235 q_hash(CTX_HUMAN_ATTESTATION),
236 reason_hash,
237 )
238}
239
240pub fn human_correct_quin(
243 human_did_hash: u64,
244 instance_hash: u64,
245 new_class_hash: u64,
246) -> VisionQuin {
247 VisionQuin::with_parity(
248 human_did_hash,
249 q_hash(P_HUMAN_CORRECTS),
250 new_class_hash,
251 q_hash(CTX_HUMAN_ATTESTATION) ^ instance_hash,
252 instance_hash,
253 )
254}
255
256pub fn model_digest_quin(media: MediaDigest, model_hash: u64) -> VisionQuin {
258 VisionQuin::with_parity(
259 media.hash,
260 q_hash(P_MODEL_DIGEST),
261 model_hash,
262 q_hash(CTX_VISION),
263 media.byte_len,
264 )
265}
266
267pub fn compile_observation_quins(
271 media: MediaDigest,
272 detections: &[Detection],
273 model_hash: u64,
274 out: &mut [VisionQuin],
275) -> usize {
276 let mut w = 0usize;
277 for det in detections {
278 if det.class_hash == 0 && det.score_u16 == 0 {
279 continue;
280 }
281 if w + 2 > out.len() {
282 break;
283 }
284 out[w] = observation_quin(media, det, model_hash);
285 w += 1;
286 out[w] = class_proposal_quin(det, model_hash);
287 w += 1;
288 }
289 w
290}
291
292pub fn compile_observation_quins_full(
295 media: MediaDigest,
296 detections: &[Detection],
297 model_hash: u64,
298 out: &mut [VisionQuin],
299) -> usize {
300 let mut w = 0usize;
301 if out.is_empty() {
302 return 0;
303 }
304 out[w] = model_digest_quin(media, model_hash);
305 w += 1;
306 for det in detections {
307 if det.class_hash == 0 && det.score_u16 == 0 {
308 continue;
309 }
310 if w + 4 > out.len() {
311 break;
312 }
313 out[w] = observation_quin(media, det, model_hash);
314 w += 1;
315 out[w] = class_proposal_quin(det, model_hash);
316 w += 1;
317 out[w] = bbox_quin(det, model_hash);
318 w += 1;
319 out[w] = track_quin(det, model_hash);
320 w += 1;
321 }
322 w
323}
324
325pub fn query_instances_in_region(
328 quins: &[VisionQuin],
329 x0: u16,
330 y0: u16,
331 x1: u16,
332 y1: u16,
333 out_instances: &mut [u64],
334) -> usize {
335 let mut w = 0usize;
336 let pred = q_hash(P_HAS_BBOX);
337 for q in quins {
338 if q.predicate != pred {
339 continue;
340 }
341 let (bx0, by0, bx1, by1) = unpack_bbox_u64(q.object);
342 if boxes_intersect(x0, y0, x1, y1, bx0, by0, bx1, by1) {
343 if w >= out_instances.len() {
344 break;
345 }
346 let inst = q.subject;
348 if out_instances[..w].contains(&inst) {
349 continue;
350 }
351 out_instances[w] = inst;
352 w += 1;
353 }
354 }
355 w
356}
357
358pub fn query_by_frame_range(
360 quins: &[VisionQuin],
361 frame_min: u32,
362 frame_max: u32,
363 out: &mut [VisionQuin],
364) -> usize {
365 let pred_obs = q_hash(P_VISUAL_OBSERVATION);
366 let mut w = 0usize;
367 for q in quins {
368 if q.predicate != pred_obs {
369 continue;
370 }
371 let frame = ((q.metadata >> 16) & 0xFFFF_FFFF) as u32;
372 if frame >= frame_min && frame <= frame_max {
373 if w >= out.len() {
374 break;
375 }
376 out[w] = *q;
377 w += 1;
378 }
379 }
380 w
381}
382
383pub fn query_by_model(quins: &[VisionQuin], model_hash: u64, out: &mut [VisionQuin]) -> usize {
385 let ctx = q_hash(CTX_VISION) ^ model_hash;
386 let mut w = 0usize;
387 for q in quins {
388 if q.context == ctx || (q.predicate == q_hash(P_MODEL_DIGEST) && q.object == model_hash) {
389 if w >= out.len() {
390 break;
391 }
392 out[w] = *q;
393 w += 1;
394 }
395 }
396 w
397}
398
399#[inline]
400fn boxes_intersect(
401 ax0: u16,
402 ay0: u16,
403 ax1: u16,
404 ay1: u16,
405 bx0: u16,
406 by0: u16,
407 bx1: u16,
408 by1: u16,
409) -> bool {
410 ax0 < bx1 && ax1 > bx0 && ay0 < by1 && ay1 > by0
411}
412
413#[cfg(test)]
414mod tests {
415 use super::*;
416 use crate::types::Detection;
417
418 #[test]
419 fn parity_valid() {
420 let d = Detection {
421 class_hash: 0xABC,
422 instance_hash: 0xDEF,
423 score_u16: 40_000,
424 x_min_u16: 0,
425 y_min_u16: 0,
426 x_max_u16: 65535,
427 y_max_u16: 65535,
428 frame_index: 0,
429 track_id: 0,
430 flags: Detection::FLAG_REFERENCE_BACKEND,
431 };
432 let m = MediaDigest {
433 hash: 0x1111,
434 byte_len: 100,
435 };
436 let q = observation_quin(m, &d, 0x42);
437 assert_eq!(
438 q.parity,
439 q.subject ^ q.predicate ^ q.object ^ q.context ^ q.metadata
440 );
441 }
442
443 #[test]
444 fn compile_two_per_detection() {
445 let mut out = [VisionQuin::with_parity(0, 0, 0, 0, 0); 8];
446 let d = Detection {
447 class_hash: 1,
448 instance_hash: 2,
449 score_u16: 1000,
450 ..Detection::empty()
451 };
452 let n = compile_observation_quins(
453 MediaDigest {
454 hash: 9,
455 byte_len: 1,
456 },
457 &[d],
458 7,
459 &mut out,
460 );
461 assert_eq!(n, 2);
462 }
463
464 #[test]
465 fn full_compile_includes_bbox_and_track() {
466 let d = Detection {
467 class_hash: 1,
468 instance_hash: 2,
469 score_u16: 1000,
470 x_min_u16: 100,
471 y_min_u16: 200,
472 x_max_u16: 3000,
473 y_max_u16: 4000,
474 frame_index: 3,
475 track_id: 7,
476 flags: 0,
477 };
478 let media = MediaDigest {
479 hash: 9,
480 byte_len: 1,
481 };
482 let mut out = [VisionQuin::with_parity(0, 0, 0, 0, 0); 16];
483 let n = compile_observation_quins_full(media, &[d], 7, &mut out);
484 assert_eq!(n, 5); assert_eq!(out[0].predicate, q_hash(P_MODEL_DIGEST));
486
487 let mut inst = [0u64; 4];
488 let qn = query_instances_in_region(&out[..n], 0, 0, 5000, 5000, &mut inst);
489 assert_eq!(qn, 1);
490 assert_eq!(inst[0], 2);
491
492 let rej = human_reject_quin(0xD1D_u64, d.instance_hash, 0);
493 assert_eq!(rej.predicate, q_hash(P_HUMAN_REJECTS));
494 let corr = human_correct_quin(0xD1D_u64, d.instance_hash, 99);
495 assert_eq!(corr.object, 99);
496 assert!(out[..n]
498 .iter()
499 .any(|q| q.predicate == q_hash(P_PROPOSES_CLASS)));
500 let _ = corr;
501 }
502
503 #[test]
504 fn pack_unpack_bbox_roundtrip() {
505 let d = Detection {
506 x_min_u16: 1,
507 y_min_u16: 2,
508 x_max_u16: 3,
509 y_max_u16: 4,
510 ..Detection::empty()
511 };
512 let p = pack_bbox_u64(&d);
513 assert_eq!(unpack_bbox_u64(p), (1, 2, 3, 4));
514 }
515
516 #[test]
517 fn test_detection_semantic_formatting() {
518 let d = Detection {
519 class_hash: 0x1234,
520 instance_hash: 0x5678,
521 score_u16: 60000,
522 x_min_u16: 6553,
523 y_min_u16: 13107,
524 x_max_u16: 39321,
525 y_max_u16: 52428,
526 frame_index: 12,
527 track_id: 3,
528 flags: 0,
529 };
530
531 let desc = format_detection_text_description(&d, "person");
532 assert!(desc.contains("Detected 'person'"));
533 assert!(desc.contains("Track #3"));
534 assert!(desc.contains("frame 12"));
535
536 let ttl = format_detection_turtle_rdf(&d, "person", 0x9999);
537 assert!(ttl.contains("a q42:DetectedObject"));
538 assert!(ttl.contains("rdfs:label \"person\""));
539 assert!(ttl.contains("prov:wasDerivedFrom <urn:q42:media:0000000000009999>"));
540 }
541}