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 ®ion_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}