Skip to main content

qualia_vision/recipes/
sparql_mm_observation_query.rs

1//! SPARQL-MM spatial+temporal query over vision OBSERVATION quins (D4.03).
2//!
3//! Composes the vision-native semantic engine — it does NOT reimplement region /
4//! frame filtering. Two existing primitives are joined on the instance hash:
5//!
6//!   * [`crate::semantic::query_by_frame_range`]     — temporal filter over
7//!     `VisualObservation` quins (frame index packed in metadata bits 16..48);
8//!     each surviving quin carries `object = instance_hash`.
9//!   * [`crate::semantic::query_instances_in_region`] — spatial filter over
10//!     `hasBoundingBox` quins (box packed in the object payload); each surviving
11//!     hit yields `subject = instance_hash`.
12//!
13//! An observation is "in the window" iff its instance appears in BOTH result sets.
14//!
15//! ## Why the vision-native route (not `SparqlMmHandler`)
16//! `qualia_core_db::sparql_library::sparql_mm::SparqlMmHandler` already recognises
17//! the `hasBoundingBox` / `hasTrackId` predicate hashes this layer emits, and a
18//! `&[VisionQuin]` could be reinterpreted as `&[NQuin]` (both are 6×u64 `#[repr(C)]`).
19//! Its TEMPORAL dimension, however, keys off `ma-ont#mediaTimeMs` / `hasStartTime`
20//! payloads in the *object* field — whereas vision observations carry the frame
21//! index in *metadata*. Routing the temporal half through `SparqlMmHandler` would
22//! therefore silently match nothing (or require inventing media-time edges we do
23//! not have). The vision-native primitives model the frame semantics exactly, so
24//! they are the route that composes correctly AND compiles cleanly. Documented per
25//! the task's "prefer the one that compiles cleanly" instruction.
26//!
27//! ## Template-leak safety
28//! `VisionQuin` holds OBSERVATIONS, never biometric templates. This query returns
29//! only instance/subject IDENTITY hashes (`u64` node identifiers) and a count — it
30//! never emits an `object` payload (which is where a packed box, or in other quin
31//! families a template digest, would live). Callers cannot recover template bytes
32//! through this surface.
33
34use crate::semantic::{query_by_frame_range, query_instances_in_region, VisionQuin};
35
36/// Result of a spatial+temporal observation query: a count plus the instance
37/// (subject) hashes that fall inside the window. Never contains object payloads.
38#[derive(Debug, Clone, Default, PartialEq, Eq)]
39pub struct ObsQueryResult {
40    /// Number of distinct in-window observation instances.
41    pub count: usize,
42    /// Distinct instance/subject identity hashes inside the zone+frame window.
43    pub instance_hashes: Vec<u64>,
44}
45
46/// Count + identify observation instances whose bounding box intersects the zone
47/// `[x0,y0,x1,y1]` AND whose `VisualObservation` frame is in `[frame_start,
48/// frame_end]`.
49///
50/// Returns only instance hashes and a count — never template/object-payload bytes.
51pub fn faces_in_zone_time(
52    obs: &[VisionQuin],
53    x0: u16,
54    y0: u16,
55    x1: u16,
56    y1: u16,
57    frame_start: u32,
58    frame_end: u32,
59) -> ObsQueryResult {
60    if obs.is_empty() {
61        return ObsQueryResult::default();
62    }
63
64    // Temporal half: observation quins whose frame is in range. Each carries
65    // object = instance_hash (media --VisualObservation--> instance).
66    let mut frame_hits = vec![VisionQuin::with_parity(0, 0, 0, 0, 0); obs.len()];
67    let n_frame = query_by_frame_range(obs, frame_start, frame_end, &mut frame_hits);
68
69    // Spatial half: instance hashes whose bounding box intersects the zone
70    // (bbox quin subject = instance_hash).
71    let mut region_inst = vec![0u64; obs.len()];
72    let n_region = query_instances_in_region(obs, x0, y0, x1, y1, &mut region_inst);
73
74    // Join on instance hash: keep instances present in BOTH halves. We only ever
75    // move `subject`/`object` identity hashes here — no object payload escapes.
76    let mut instance_hashes: Vec<u64> = Vec::new();
77    for &inst in &region_inst[..n_region] {
78        let in_window = frame_hits[..n_frame].iter().any(|q| q.object == inst);
79        if in_window && !instance_hashes.contains(&inst) {
80            instance_hashes.push(inst);
81        }
82    }
83
84    ObsQueryResult {
85        count: instance_hashes.len(),
86        instance_hashes,
87    }
88}
89
90#[cfg(test)]
91mod tests {
92    use super::*;
93    use crate::semantic::{bbox_quin, observation_quin, pack_bbox_u64, MediaDigest};
94    use crate::types::Detection;
95
96    fn det(instance: u64, x0: u16, y0: u16, x1: u16, y1: u16, frame: u32) -> Detection {
97        Detection {
98            class_hash: 0xC1A55,
99            instance_hash: instance,
100            score_u16: 40_000,
101            x_min_u16: x0,
102            y_min_u16: y0,
103            x_max_u16: x1,
104            y_max_u16: y1,
105            frame_index: frame,
106            track_id: 0,
107            flags: 0,
108        }
109    }
110
111    /// Build the two quins the query joins on (observation + bbox) for one det.
112    fn quins_for(media: MediaDigest, d: &Detection, model: u64) -> [VisionQuin; 2] {
113        [observation_quin(media, d, model), bbox_quin(d, model)]
114    }
115
116    #[test]
117    fn counts_only_in_zone_and_in_frame() {
118        let media = MediaDigest {
119            hash: 0xF00D,
120            byte_len: 10,
121        };
122        let model = 0x42;
123
124        // In zone (top-left quadrant), in frame window.
125        let a = det(0xAAAA, 100, 100, 4000, 4000, 5);
126        // In zone, but OUT of frame window.
127        let b = det(0xBBBB, 200, 200, 4000, 4000, 999);
128        // Out of zone (far bottom-right), in frame window.
129        let c = det(0xCCCC, 60000, 60000, 65000, 65000, 6);
130        // In zone, in frame window — second valid hit.
131        let e = det(0xEEEE, 500, 500, 3000, 3000, 7);
132
133        let mut all: Vec<VisionQuin> = Vec::new();
134        for d in [&a, &b, &c, &e] {
135            all.extend_from_slice(&quins_for(media, d, model));
136        }
137
138        // Zone = top-left region; frame window [0,100].
139        let r = faces_in_zone_time(&all, 0, 0, 10000, 10000, 0, 100);
140
141        assert_eq!(r.count, 2, "only A and E are in zone AND in frame window");
142        assert!(r.instance_hashes.contains(&0xAAAA));
143        assert!(r.instance_hashes.contains(&0xEEEE));
144        assert!(!r.instance_hashes.contains(&0xBBBB), "B excluded by frame");
145        assert!(!r.instance_hashes.contains(&0xCCCC), "C excluded by zone");
146    }
147
148    #[test]
149    fn returns_no_template_or_object_payload_bytes() {
150        let media = MediaDigest {
151            hash: 0x1234,
152            byte_len: 5,
153        };
154        let model = 7;
155        let a = det(0xAAAA, 100, 100, 4000, 4000, 3);
156
157        let mut all: Vec<VisionQuin> = Vec::new();
158        all.extend_from_slice(&quins_for(media, &a, model));
159
160        let r = faces_in_zone_time(&all, 0, 0, 10000, 10000, 0, 100);
161        assert_eq!(r.count, 1);
162
163        // The ONLY value returned is the instance identity hash — never the packed
164        // bbox object payload (the field where template-like bytes would live).
165        let packed_box = pack_bbox_u64(&a);
166        assert!(
167            !r.instance_hashes.contains(&packed_box),
168            "packed object payload must never appear in results"
169        );
170        for &h in &r.instance_hashes {
171            assert_eq!(h, 0xAAAA, "results are subject/instance hashes only");
172        }
173    }
174
175    #[test]
176    fn empty_input_is_empty_result() {
177        let r = faces_in_zone_time(&[], 0, 0, 100, 100, 0, 10);
178        assert_eq!(r.count, 0);
179        assert!(r.instance_hashes.is_empty());
180    }
181}