Skip to main content

sightloom_index/
query.rs

1//! Declarative query layer over an in-memory [`VisionIndex`].
2//!
3//! Foundation AST + executor: predicate composition, time range, zone filters,
4//! then-seen-in chains, route prefix matching, confidence, pagination.
5//! Not a full planner / spatial index / NL bridge.
6
7use crate::{Route, TrackSample, VisionIndex, ZoneStay};
8use sightloom_core::{MediaTime, SourceId, SubjectId, ZoneId};
9
10/// Sort order for query results.
11#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
12pub enum QueryOrder {
13    /// Ascending by subject id.
14    #[default]
15    SubjectIdAsc,
16    /// Descending by total sample count.
17    SampleCountDesc,
18    /// Descending by total dwell.
19    DwellDesc,
20}
21
22/// Pagination cursor.
23#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
24pub struct Page {
25    /// Skip this many results.
26    pub offset: usize,
27    /// Return at most this many results (`0` = no limit).
28    pub limit: usize,
29}
30
31/// Require zone A then zone B within a time bound.
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
33pub struct ThenSeenIn {
34    /// First zone.
35    pub first: ZoneId,
36    /// Second zone.
37    pub then: ZoneId,
38    /// Maximum nanoseconds from end of first stay to start of second (`0` = open).
39    pub within_ns: i64,
40}
41
42/// Composable subject-oriented query.
43#[derive(Clone, Debug, Default)]
44pub struct SubjectQuery {
45    /// Restrict to these subjects when non-empty.
46    pub subject_ids: Vec<SubjectId>,
47    /// Must have samples on this source.
48    pub seen_on_source: Option<SourceId>,
49    /// Must have a zone stay in this zone.
50    pub seen_in_zone: Option<ZoneId>,
51    /// Optional A-then-B zone chain with time bound.
52    pub then_seen_in: Option<ThenSeenIn>,
53    /// Route must contain this ordered zone subsequence.
54    pub route_contains: Vec<ZoneId>,
55    /// Time window (inclusive) on track sample pts.
56    pub during: Option<(MediaTime, MediaTime)>,
57    /// Minimum dwell nanoseconds from zone stays.
58    pub min_dwell_ns: Option<i64>,
59    /// Minimum peak track confidence.
60    pub min_confidence: Option<f32>,
61    /// Pagination.
62    pub page: Page,
63    /// Sort order.
64    pub order: QueryOrder,
65}
66
67impl SubjectQuery {
68    /// Empty query (all subjects with any track sample).
69    #[must_use]
70    pub fn new() -> Self {
71        Self::default()
72    }
73
74    /// Builder: filter by zone.
75    #[must_use]
76    pub fn seen_in(mut self, zone: ZoneId) -> Self {
77        self.seen_in_zone = Some(zone);
78        self
79    }
80
81    /// Builder: seen in `first` then `then` within `within_ns` (0 = any later).
82    #[must_use]
83    pub fn then_seen_in(mut self, first: ZoneId, then: ZoneId, within_ns: i64) -> Self {
84        self.then_seen_in = Some(ThenSeenIn {
85            first,
86            then,
87            within_ns,
88        });
89        self
90    }
91
92    /// Builder: route must contain ordered zone subsequence.
93    #[must_use]
94    pub fn route_contains(mut self, zones: impl Into<Vec<ZoneId>>) -> Self {
95        self.route_contains = zones.into();
96        self
97    }
98
99    /// Builder: time window.
100    #[must_use]
101    pub fn during(mut self, start: MediaTime, end: MediaTime) -> Self {
102        self.during = Some((start, end));
103        self
104    }
105
106    /// Builder: min dwell.
107    #[must_use]
108    pub fn with_min_dwell_ns(mut self, dwell_ns: i64) -> Self {
109        self.min_dwell_ns = Some(dwell_ns);
110        self
111    }
112
113    /// Builder: min confidence.
114    #[must_use]
115    pub fn with_min_confidence(mut self, confidence: f32) -> Self {
116        self.min_confidence = Some(confidence);
117        self
118    }
119
120    /// Builder: source filter.
121    #[must_use]
122    pub fn seen_on(mut self, source: SourceId) -> Self {
123        self.seen_on_source = Some(source);
124        self
125    }
126
127    /// Builder: pagination.
128    #[must_use]
129    pub fn page(mut self, offset: usize, limit: usize) -> Self {
130        self.page = Page { offset, limit };
131        self
132    }
133
134    /// Builder: order.
135    #[must_use]
136    pub fn order(mut self, order: QueryOrder) -> Self {
137        self.order = order;
138        self
139    }
140}
141
142/// One subject row returned by [`execute_subject_query`].
143#[derive(Clone, Debug, PartialEq)]
144pub struct SubjectHit {
145    /// Subject id.
146    pub subject_id: SubjectId,
147    /// Matching track samples (effective view recommended by caller).
148    pub samples: Vec<TrackSample>,
149    /// Matching zone stays.
150    pub zone_stays: Vec<ZoneStay>,
151    /// Matching routes.
152    pub routes: Vec<Route>,
153    /// Peak confidence across samples.
154    pub peak_confidence: f32,
155    /// Total dwell ns from zone stays.
156    pub total_dwell_ns: i64,
157}
158
159/// Executes a [`SubjectQuery`] against an in-memory index.
160#[must_use]
161pub fn execute_subject_query(index: &VisionIndex, query: &SubjectQuery) -> Vec<SubjectHit> {
162    let mut by_subject: Vec<(SubjectId, Vec<TrackSample>)> = Vec::new();
163    for sample in index.tracks.effective_samples() {
164        let Some(subject_id) = sample.subject_id else {
165            continue;
166        };
167        if !query.subject_ids.is_empty() && !query.subject_ids.contains(&subject_id) {
168            continue;
169        }
170        if let Some(source) = query.seen_on_source
171            && sample.source_id != source
172        {
173            continue;
174        }
175        if let Some((start, end)) = query.during {
176            let t = sample.pts.as_nanos();
177            if t < start.as_nanos() || t > end.as_nanos() {
178                continue;
179            }
180        }
181        if let Some(min_c) = query.min_confidence
182            && sample.confidence < min_c
183        {
184            continue;
185        }
186        if let Some((_, samples)) = by_subject.iter_mut().find(|(id, _)| *id == subject_id) {
187            samples.push(sample);
188        } else {
189            by_subject.push((subject_id, vec![sample]));
190        }
191    }
192
193    let mut hits = Vec::new();
194    for (subject_id, samples) in by_subject {
195        let zone_stays: Vec<ZoneStay> = index
196            .zone_stays
197            .iter()
198            .copied()
199            .filter(|z| z.subject_id == Some(subject_id))
200            .collect();
201
202        if let Some(zone) = query.seen_in_zone
203            && !zone_stays.iter().any(|z| z.zone_id == zone)
204        {
205            continue;
206        }
207
208        if let Some(chain) = query.then_seen_in
209            && !matches_then_seen_in(&zone_stays, chain)
210        {
211            continue;
212        }
213
214        let routes: Vec<Route> = index
215            .routes
216            .iter()
217            .filter(|r| r.subject_id == subject_id)
218            .cloned()
219            .collect();
220
221        if !query.route_contains.is_empty()
222            && !routes
223                .iter()
224                .any(|r| route_contains_subsequence(&r.zones, &query.route_contains))
225        {
226            continue;
227        }
228
229        let total_dwell_ns = zone_stays.iter().map(|z| z.duration_ns).sum();
230        if let Some(min_dwell) = query.min_dwell_ns
231            && total_dwell_ns < min_dwell
232        {
233            continue;
234        }
235        let peak_confidence = samples.iter().map(|s| s.confidence).fold(0.0_f32, f32::max);
236        hits.push(SubjectHit {
237            subject_id,
238            samples,
239            zone_stays,
240            routes,
241            peak_confidence,
242            total_dwell_ns,
243        });
244    }
245
246    match query.order {
247        QueryOrder::SubjectIdAsc => hits.sort_by_key(|h| h.subject_id.0),
248        QueryOrder::SampleCountDesc => {
249            hits.sort_by_key(|hit| core::cmp::Reverse(hit.samples.len()));
250        }
251        QueryOrder::DwellDesc => {
252            hits.sort_by_key(|hit| core::cmp::Reverse(hit.total_dwell_ns));
253        }
254    }
255
256    let start = query.page.offset.min(hits.len());
257    let end = if query.page.limit == 0 {
258        hits.len()
259    } else {
260        start.saturating_add(query.page.limit).min(hits.len())
261    };
262    hits[start..end].to_vec()
263}
264
265fn matches_then_seen_in(stays: &[ZoneStay], chain: ThenSeenIn) -> bool {
266    let mut first_ends: Vec<i64> = stays
267        .iter()
268        .filter(|z| z.zone_id == chain.first)
269        .map(|z| z.end.as_nanos())
270        .collect();
271    first_ends.sort_unstable();
272    let mut second_starts: Vec<i64> = stays
273        .iter()
274        .filter(|z| z.zone_id == chain.then)
275        .map(|z| z.start.as_nanos())
276        .collect();
277    second_starts.sort_unstable();
278
279    for end in first_ends {
280        for &start in &second_starts {
281            if start < end {
282                continue;
283            }
284            if chain.within_ns == 0 || start.saturating_sub(end) <= chain.within_ns {
285                return true;
286            }
287        }
288    }
289    false
290}
291
292fn route_contains_subsequence(route: &[ZoneId], needle: &[ZoneId]) -> bool {
293    if needle.is_empty() {
294        return true;
295    }
296    if needle.len() > route.len() {
297        return false;
298    }
299    route.windows(needle.len()).any(|window| window == needle)
300}
301
302/// Axis-aligned region query over effective track samples.
303#[derive(Clone, Copy, Debug, PartialEq)]
304pub struct SpatialQuery {
305    /// Region left.
306    pub left: f32,
307    /// Region top.
308    pub top: f32,
309    /// Region right.
310    pub right: f32,
311    /// Region bottom.
312    pub bottom: f32,
313    /// Optional source filter.
314    pub source_id: Option<SourceId>,
315    /// Optional time window.
316    pub during: Option<(MediaTime, MediaTime)>,
317    /// Minimum sample confidence.
318    pub min_confidence: Option<f32>,
319    /// When true, only labeled subjects are returned.
320    pub require_subject: bool,
321    /// Pagination.
322    pub page: Page,
323}
324
325impl SpatialQuery {
326    /// Creates a spatial region query.
327    #[must_use]
328    pub fn new(left: f32, top: f32, right: f32, bottom: f32) -> Self {
329        Self {
330            left,
331            top,
332            right,
333            bottom,
334            source_id: None,
335            during: None,
336            min_confidence: None,
337            require_subject: false,
338            page: Page::default(),
339        }
340    }
341
342    /// Builder: source filter.
343    #[must_use]
344    pub fn on_source(mut self, source: SourceId) -> Self {
345        self.source_id = Some(source);
346        self
347    }
348
349    /// Builder: time window.
350    #[must_use]
351    pub fn during(mut self, start: MediaTime, end: MediaTime) -> Self {
352        self.during = Some((start, end));
353        self
354    }
355
356    /// Builder: require subject labels.
357    #[must_use]
358    pub fn with_subject(mut self) -> Self {
359        self.require_subject = true;
360        self
361    }
362
363    /// Builder: min confidence.
364    #[must_use]
365    pub fn with_min_confidence(mut self, confidence: f32) -> Self {
366        self.min_confidence = Some(confidence);
367        self
368    }
369
370    /// Builder: pagination.
371    #[must_use]
372    pub fn page(mut self, offset: usize, limit: usize) -> Self {
373        self.page = Page { offset, limit };
374        self
375    }
376}
377
378/// One spatial hit (track sample intersecting the region).
379#[derive(Clone, Copy, Debug, PartialEq)]
380pub struct SpatialHit {
381    /// Matching sample (effective view).
382    pub sample: TrackSample,
383    /// Subject when labeled.
384    pub subject_id: Option<SubjectId>,
385    /// Intersection-over-union of sample box vs query region (0 when degenerate).
386    pub iou: f32,
387}
388
389/// Returns effective track samples whose boxes intersect the spatial region.
390#[must_use]
391pub fn execute_spatial_query(index: &VisionIndex, query: &SpatialQuery) -> Vec<SpatialHit> {
392    let mut hits = Vec::new();
393    for sample in index.tracks.effective_samples() {
394        if let Some(source) = query.source_id
395            && sample.source_id != source
396        {
397            continue;
398        }
399        if query.require_subject && sample.subject_id.is_none() {
400            continue;
401        }
402        if let Some((start, end)) = query.during {
403            let t = sample.pts.as_nanos();
404            if t < start.as_nanos() || t > end.as_nanos() {
405                continue;
406            }
407        }
408        if let Some(min_c) = query.min_confidence
409            && sample.confidence < min_c
410        {
411            continue;
412        }
413        if !boxes_intersect(
414            sample.left,
415            sample.top,
416            sample.right,
417            sample.bottom,
418            query.left,
419            query.top,
420            query.right,
421            query.bottom,
422        ) {
423            continue;
424        }
425        let iou = box_iou(
426            sample.left,
427            sample.top,
428            sample.right,
429            sample.bottom,
430            query.left,
431            query.top,
432            query.right,
433            query.bottom,
434        );
435        hits.push(SpatialHit {
436            sample,
437            subject_id: sample.subject_id,
438            iou,
439        });
440    }
441    hits.sort_by(|a, b| {
442        b.iou
443            .partial_cmp(&a.iou)
444            .unwrap_or(core::cmp::Ordering::Equal)
445            .then_with(|| a.sample.sample_id.cmp(&b.sample.sample_id))
446    });
447    let start = query.page.offset.min(hits.len());
448    let end = if query.page.limit == 0 {
449        hits.len()
450    } else {
451        start.saturating_add(query.page.limit).min(hits.len())
452    };
453    hits[start..end].to_vec()
454}
455
456#[allow(clippy::too_many_arguments)]
457fn boxes_intersect(
458    a_l: f32,
459    a_t: f32,
460    a_r: f32,
461    a_b: f32,
462    b_l: f32,
463    b_t: f32,
464    b_r: f32,
465    b_b: f32,
466) -> bool {
467    a_l < b_r && a_r > b_l && a_t < b_b && a_b > b_t
468}
469
470#[allow(clippy::too_many_arguments)]
471fn box_iou(a_l: f32, a_t: f32, a_r: f32, a_b: f32, b_l: f32, b_t: f32, b_r: f32, b_b: f32) -> f32 {
472    let inter_l = a_l.max(b_l);
473    let inter_t = a_t.max(b_t);
474    let inter_r = a_r.min(b_r);
475    let inter_b = a_b.min(b_b);
476    let inter_w = (inter_r - inter_l).max(0.0);
477    let inter_h = (inter_b - inter_t).max(0.0);
478    let inter = inter_w * inter_h;
479    if inter <= 0.0 {
480        return 0.0;
481    }
482    let area_a = ((a_r - a_l) * (a_b - a_t)).max(0.0);
483    let area_b = ((b_r - b_l) * (b_b - b_t)).max(0.0);
484    let union = area_a + area_b - inter;
485    if union <= 0.0 { 0.0 } else { inter / union }
486}
487
488#[cfg(test)]
489mod tests {
490    use super::*;
491    use crate::{TrackSample, VisionIndex, ZoneStay};
492    use sightloom_core::{MediaTime, SourceId, SubjectId, TrackId, ZoneId};
493
494    fn sample(subject: u64, frame: u64) -> TrackSample {
495        TrackSample {
496            sample_id: 0,
497            supersedes: None,
498            revision: 0,
499            idempotency_key: 0,
500            source_id: SourceId(1),
501            frame_index: frame,
502            pts: MediaTime::new(frame as i64, 1).unwrap(),
503            track_id: TrackId(1),
504            track_uid: None,
505            subject_id: Some(SubjectId(subject)),
506            class_id: None,
507            left: 0.0,
508            top: 0.0,
509            right: 1.0,
510            bottom: 1.0,
511            confidence: 0.9,
512            mask_ref: 0,
513        }
514    }
515
516    #[test]
517    fn then_seen_in_filters_subjects() {
518        let mut index = VisionIndex::new("q");
519        index.push_track(sample(1, 0));
520        index.push_track(sample(2, 0));
521        index.zone_stays.push(ZoneStay {
522            zone_id: ZoneId(1),
523            subject_id: Some(SubjectId(1)),
524            track_id: None,
525            start: MediaTime::new(0, 1).unwrap(),
526            end: MediaTime::new(1, 1).unwrap(),
527            duration_ns: 1,
528        });
529        index.zone_stays.push(ZoneStay {
530            zone_id: ZoneId(2),
531            subject_id: Some(SubjectId(1)),
532            track_id: None,
533            start: MediaTime::new(2, 1).unwrap(),
534            end: MediaTime::new(3, 1).unwrap(),
535            duration_ns: 1,
536        });
537        // Subject 2 only entrance
538        index.zone_stays.push(ZoneStay {
539            zone_id: ZoneId(1),
540            subject_id: Some(SubjectId(2)),
541            track_id: None,
542            start: MediaTime::new(0, 1).unwrap(),
543            end: MediaTime::new(1, 1).unwrap(),
544            duration_ns: 1,
545        });
546
547        let hits = execute_subject_query(
548            &index,
549            &SubjectQuery::new().then_seen_in(ZoneId(1), ZoneId(2), 10_000_000_000),
550        );
551        assert_eq!(hits.len(), 1);
552        assert_eq!(hits[0].subject_id, SubjectId(1));
553    }
554
555    #[test]
556    fn route_contains_subsequence_works() {
557        assert!(route_contains_subsequence(
558            &[ZoneId(1), ZoneId(2), ZoneId(3)],
559            &[ZoneId(2), ZoneId(3)]
560        ));
561        assert!(!route_contains_subsequence(
562            &[ZoneId(1), ZoneId(3)],
563            &[ZoneId(1), ZoneId(2)]
564        ));
565    }
566}