Skip to main content

qualia_vision/
semantic.rs

1//! Observation → fixed NQuin-compatible records (epistemic, not ground truth).
2//!
3//! Layout matches Qualia `NQuin` (6 × u64). We keep a local definition so
4//! Phase-1 does not force a full `qualia-core-db` link for every UI binary;
5//! field meanings are identical and can be cast/transmuted at the core boundary.
6//!
7//! V6: human reject/correct, bbox/track predicates, full compile (up to 4 quins/det).
8
9use crate::types::Detection;
10
11/// Predicate / context IRIs (hashed with FNV-1a 64, same family as Qualia `q_hash`).
12pub 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
22/// Max observation quins emitted per batch (up to 4 per detection in full compile).
23pub const MAX_OBS_QUINS: usize = 256;
24
25/// 48-byte semantic quin (parity = XOR fold of other fields).
26#[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    /// Builder — sets parity.
40    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/// Content digest of media bytes (FNV-1a over up to 64 KiB prefix + length).
60#[derive(Debug, Clone, Copy, PartialEq, Eq)]
61pub struct MediaDigest {
62    pub hash: u64,
63    pub byte_len: u64,
64}
65
66/// FNV-1a 64 — matches Qualia URI hashing family.
67#[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]
80/// q_hash of bytes.
81pub 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
92/// Media digest.
93pub fn media_digest(bytes: &[u8]) -> MediaDigest {
94    let take = bytes.len().min(65_536);
95    let mut h = q_hash_bytes(&bytes[..take]);
96    // Mix length so different sizes of same prefix differ.
97    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
104/// One observation quin: media --VisualObservation--> instance, score in metadata low 16.
105pub 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    // metadata: score | frame in high bits (simple packing).
111    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
116/// Class proposal quin: instance --proposesClass--> class_hash.
117pub 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/// Pack normalized u16 bbox into a single u64 (x0|y0|x1|y1 as 16-bit lanes).
127#[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]
136/// Unpacks a u64 bbox.
137pub 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
146/// instance --hasBoundingBox--> packed box (metadata: score).
147pub 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
156/// instance --hasTrackId--> track_id (0 if untracked).
157pub 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
166/// Detailed human-readable semantic description of an object detection.
167pub 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
186/// RDF Turtle representation of a detected object instance.
187pub 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
228/// Human rejects a machine observation instance (does not erase the machine claim).
229/// subject = human_did_hash, object = instance_hash that is rejected.
230pub 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
240/// Human corrects class: subject = human, object = new_class_hash;
241/// metadata low 64 bits of original instance for linkage (instance in context xor).
242pub 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
256/// media --modelDigest--> model_hash (provenance of which model produced claims).
257pub 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
267/// Compile detections into observation + class quins (epistemic layer).
268///
269/// Returns number of quins written. Each detection contributes up to 2 quins.
270pub 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
292/// Full epistemic compile: model digest + per-det (observation, class, bbox, track).
293/// Machine claims are never erased by later human reject/correct (separate context).
294pub 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
325/// Region query over compiled observation quins: keep instances whose bbox
326/// intersects the query box (normalized u16). Writes matching instance hashes.
327pub 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            // Dedupe instance
347            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
358/// Filter observation quins by media time / frame range (frame in observation metadata bits 16..48).
359pub 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
383/// Filter by model hash mixed into context (context = CTX_VISION ^ model_hash).
384pub 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); // digest + 4 per det
485        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        // Machine claim still present after human acts.
497        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}