Skip to main content

sightloom_index/
memory_build.rs

1//! Build first-class memory entities (appearances / visits / subject profiles)
2//! and redaction provenance intervals from track samples.
3//!
4//! Track samples are the raw observation stream. Appearances, visits, and
5//! subject profiles are derived video-memory records hosts can query without
6//! replaying every box. Redaction intervals are exportable provenance rows
7//! (no pixels).
8
9use crate::{
10    Appearance, RedactionIntent, RedactionInterval, SubjectProfile, TrackSample, VisionIndex, Visit,
11};
12use sightloom_core::{
13    AppearanceId, MediaTime, RedactionIntervalId, SourceId, SubjectId, TrackId, VisitId,
14};
15
16/// Options for materializing appearances and visits.
17#[derive(Clone, Copy, Debug, PartialEq, Eq)]
18pub struct MemoryBuildConfig {
19    /// Max gap between samples on the same `(source, track)` before a new appearance.
20    pub appearance_gap_ns: i64,
21    /// Max gap between consecutive appearances of a subject before a new visit.
22    pub visit_gap_ns: i64,
23    /// When true, only samples with `subject_id` contribute (recommended).
24    pub require_subject: bool,
25}
26
27impl Default for MemoryBuildConfig {
28    fn default() -> Self {
29        Self {
30            // ~1 second at 30 fps is too tight; 2s default for dropped frames.
31            appearance_gap_ns: 2_000_000_000,
32            // 5 minutes default between visit windows.
33            visit_gap_ns: 300_000_000_000,
34            require_subject: true,
35        }
36    }
37}
38
39/// One open appearance run while scanning samples.
40#[derive(Clone, Debug)]
41struct AppearanceRun {
42    subject_id: Option<SubjectId>,
43    track_id: TrackId,
44    source_id: sightloom_core::SourceId,
45    start: MediaTime,
46    end: MediaTime,
47    peak_confidence: f32,
48    class_id: Option<sightloom_core::ClassId>,
49}
50
51/// Builds appearances from effective track samples.
52///
53/// Groups by `(source_id, local track_id)` and splits when consecutive samples
54/// exceed `config.appearance_gap_ns`.
55#[must_use]
56pub fn build_appearances(
57    samples: &[TrackSample],
58    config: MemoryBuildConfig,
59    next_id: &mut u64,
60) -> Vec<Appearance> {
61    let mut filtered: Vec<TrackSample> = samples
62        .iter()
63        .copied()
64        .filter(|s| !config.require_subject || s.subject_id.is_some())
65        .collect();
66    filtered.sort_by(|a, b| {
67        a.source_id
68            .0
69            .cmp(&b.source_id.0)
70            .then_with(|| a.track_id.0.cmp(&b.track_id.0))
71            .then_with(|| a.pts.as_nanos().cmp(&b.pts.as_nanos()))
72            .then_with(|| a.frame_index.cmp(&b.frame_index))
73    });
74
75    let mut runs: Vec<AppearanceRun> = Vec::new();
76    for sample in filtered {
77        if let Some(run) = runs.last_mut() {
78            let same = run.source_id == sample.source_id && run.track_id == sample.track_id;
79            let gap = sample.pts.as_nanos().saturating_sub(run.end.as_nanos());
80            if same && gap <= config.appearance_gap_ns {
81                run.end = sample.pts;
82                run.peak_confidence = run.peak_confidence.max(sample.confidence);
83                if sample.class_id.is_some() {
84                    run.class_id = sample.class_id;
85                }
86                if run.subject_id.is_none() {
87                    run.subject_id = sample.subject_id;
88                }
89                continue;
90            }
91        }
92        runs.push(AppearanceRun {
93            subject_id: sample.subject_id,
94            track_id: sample.track_id,
95            source_id: sample.source_id,
96            start: sample.pts,
97            end: sample.pts,
98            peak_confidence: sample.confidence,
99            class_id: sample.class_id,
100        });
101    }
102
103    runs.into_iter()
104        .map(|run| {
105            let id = AppearanceId(*next_id);
106            *next_id = next_id.saturating_add(1);
107            Appearance {
108                appearance_id: id,
109                subject_id: run.subject_id,
110                track_id: Some(run.track_id),
111                source_id: run.source_id,
112                start: run.start,
113                end: run.end,
114                class_id: run.class_id,
115                peak_confidence: run.peak_confidence,
116                evidence: None,
117            }
118        })
119        .collect()
120}
121
122/// Builds visits by merging a subject's appearances across sources.
123///
124/// Appearances sorted by start; merge when gap from previous visit end ≤
125/// `config.visit_gap_ns` (or overlapping).
126#[must_use]
127pub fn build_visits(
128    appearances: &[Appearance],
129    config: MemoryBuildConfig,
130    next_id: &mut u64,
131) -> Vec<Visit> {
132    let mut by_subject: Vec<(Option<SubjectId>, Vec<Appearance>)> = Vec::new();
133    for appearance in appearances {
134        if let Some((_, list)) = by_subject
135            .iter_mut()
136            .find(|(sid, _)| *sid == appearance.subject_id)
137        {
138            list.push(*appearance);
139        } else {
140            by_subject.push((appearance.subject_id, vec![*appearance]));
141        }
142    }
143
144    let mut visits = Vec::new();
145    for (subject_id, mut list) in by_subject {
146        if config.require_subject && subject_id.is_none() {
147            continue;
148        }
149        list.sort_by(|a, b| {
150            a.start
151                .as_nanos()
152                .cmp(&b.start.as_nanos())
153                .then_with(|| a.end.as_nanos().cmp(&b.end.as_nanos()))
154        });
155
156        let mut open_start: Option<MediaTime> = None;
157        let mut open_end: Option<MediaTime> = None;
158        let mut sources: Vec<u32> = Vec::new();
159
160        for appearance in list {
161            if let (Some(start), Some(end)) = (open_start, open_end) {
162                let gap = appearance.start.as_nanos().saturating_sub(end.as_nanos());
163                let overlaps = appearance.start.as_nanos() <= end.as_nanos();
164                if overlaps || gap <= config.visit_gap_ns {
165                    if appearance.end.as_nanos() > end.as_nanos() {
166                        open_end = Some(appearance.end);
167                    }
168                    if !sources.contains(&appearance.source_id.0) {
169                        sources.push(appearance.source_id.0);
170                    }
171                } else {
172                    let id = VisitId(*next_id);
173                    *next_id = next_id.saturating_add(1);
174                    visits.push(Visit {
175                        visit_id: id,
176                        subject_id,
177                        start,
178                        end,
179                        source_count: u32::try_from(sources.len()).unwrap_or(u32::MAX),
180                        duration_ns: end.as_nanos().saturating_sub(start.as_nanos()),
181                    });
182                    open_start = Some(appearance.start);
183                    open_end = Some(appearance.end);
184                    sources = vec![appearance.source_id.0];
185                }
186            } else {
187                open_start = Some(appearance.start);
188                open_end = Some(appearance.end);
189                sources = vec![appearance.source_id.0];
190            }
191        }
192        if let (Some(start), Some(end)) = (open_start, open_end) {
193            let id = VisitId(*next_id);
194            *next_id = next_id.saturating_add(1);
195            visits.push(Visit {
196                visit_id: id,
197                subject_id,
198                start,
199                end,
200                source_count: u32::try_from(sources.len()).unwrap_or(u32::MAX),
201                duration_ns: end.as_nanos().saturating_sub(start.as_nanos()),
202            });
203        }
204    }
205    visits
206}
207
208/// Rebuilds `appearances` and `visits` on the index from effective track samples.
209///
210/// Existing appearance/visit vectors are replaced (idempotent rebuild).
211/// Returns `(appearance_count, visit_count)`.
212pub fn rebuild_memory_entities(
213    index: &mut VisionIndex,
214    config: MemoryBuildConfig,
215    next_appearance_id: &mut u64,
216    next_visit_id: &mut u64,
217) -> (usize, usize) {
218    let samples = index.tracks.effective_samples();
219    let appearances = build_appearances(&samples, config, next_appearance_id);
220    let visits = build_visits(&appearances, config, next_visit_id);
221    let a = appearances.len();
222    let v = visits.len();
223    index.appearances = appearances;
224    index.visits = visits;
225    (a, v)
226}
227
228/// Accumulator while aggregating a subject profile.
229#[derive(Clone, Debug)]
230struct ProfileAcc {
231    appearance_count: u32,
232    sources: Vec<u32>,
233    total_duration_ns: i64,
234    first_ns: i64,
235    last_ns: i64,
236    first: MediaTime,
237    last: MediaTime,
238}
239
240fn touch_acc(acc: &mut ProfileAcc, start: MediaTime, end: MediaTime, source_id: SourceId) {
241    let s = start.as_nanos();
242    let e = end.as_nanos();
243    acc.appearance_count = acc.appearance_count.saturating_add(1);
244    if !acc.sources.contains(&source_id.0) {
245        acc.sources.push(source_id.0);
246    }
247    acc.total_duration_ns = acc.total_duration_ns.saturating_add(e.saturating_sub(s));
248    if s < acc.first_ns {
249        acc.first_ns = s;
250        acc.first = start;
251    }
252    if e > acc.last_ns {
253        acc.last_ns = e;
254        acc.last = end;
255    }
256}
257
258/// Builds [`SubjectProfile`] rows from appearances (preferred) or track samples.
259///
260/// Host-supplied `label` and `embedding` on matching previous profiles are
261/// preserved. Profiles are sorted by `subject_id`.
262#[must_use]
263pub fn build_subject_profiles(
264    index: &VisionIndex,
265    previous: &[SubjectProfile],
266) -> Vec<SubjectProfile> {
267    let mut acc: Vec<(SubjectId, ProfileAcc)> = Vec::new();
268
269    if index.appearances.is_empty() {
270        // Fallback: one "appearance unit" per effective labeled sample.
271        for sample in index.tracks.effective_samples() {
272            let Some(subject_id) = sample.subject_id else {
273                continue;
274            };
275            if let Some((_, row)) = acc.iter_mut().find(|(id, _)| *id == subject_id) {
276                touch_acc(row, sample.pts, sample.pts, sample.source_id);
277            } else {
278                let mut row = ProfileAcc {
279                    appearance_count: 0,
280                    sources: Vec::new(),
281                    total_duration_ns: 0,
282                    first_ns: sample.pts.as_nanos(),
283                    last_ns: sample.pts.as_nanos(),
284                    first: sample.pts,
285                    last: sample.pts,
286                };
287                touch_acc(&mut row, sample.pts, sample.pts, sample.source_id);
288                acc.push((subject_id, row));
289            }
290        }
291    } else {
292        for appearance in &index.appearances {
293            let Some(subject_id) = appearance.subject_id else {
294                continue;
295            };
296            if let Some((_, row)) = acc.iter_mut().find(|(id, _)| *id == subject_id) {
297                touch_acc(row, appearance.start, appearance.end, appearance.source_id);
298            } else {
299                let mut row = ProfileAcc {
300                    appearance_count: 0,
301                    sources: Vec::new(),
302                    total_duration_ns: 0,
303                    first_ns: appearance.start.as_nanos(),
304                    last_ns: appearance.end.as_nanos(),
305                    first: appearance.start,
306                    last: appearance.end,
307                };
308                touch_acc(
309                    &mut row,
310                    appearance.start,
311                    appearance.end,
312                    appearance.source_id,
313                );
314                acc.push((subject_id, row));
315            }
316        }
317    }
318
319    let mut profiles: Vec<SubjectProfile> = acc
320        .into_iter()
321        .map(|(subject_id, row)| {
322            let prev = previous.iter().find(|p| p.subject_id == subject_id);
323            SubjectProfile {
324                subject_id,
325                label: prev.and_then(|p| p.label.clone()),
326                appearance_count: row.appearance_count,
327                source_count: u32::try_from(row.sources.len()).unwrap_or(u32::MAX),
328                total_duration_ns: row.total_duration_ns,
329                first_seen: Some(row.first),
330                last_seen: Some(row.last),
331                embedding: prev.and_then(|p| p.embedding),
332            }
333        })
334        .collect();
335
336    // Keep host-only subjects that have no track/appearance evidence yet.
337    for prev in previous {
338        if !profiles.iter().any(|p| p.subject_id == prev.subject_id) {
339            profiles.push(SubjectProfile {
340                subject_id: prev.subject_id,
341                label: prev.label.clone(),
342                appearance_count: 0,
343                source_count: 0,
344                total_duration_ns: 0,
345                first_seen: None,
346                last_seen: None,
347                embedding: prev.embedding,
348            });
349        }
350    }
351
352    profiles.sort_by_key(|p| p.subject_id.0);
353    profiles
354}
355
356/// Rebuilds `index.subjects` from appearances (or tracks). Preserves labels /
357/// embeddings. Returns profile count.
358pub fn rebuild_subject_profiles(index: &mut VisionIndex) -> usize {
359    let previous = index.subjects.clone();
360    let profiles = build_subject_profiles(index, &previous);
361    let n = profiles.len();
362    index.subjects = profiles;
363    n
364}
365
366/// Builds redaction provenance rows from appearances matching a filter.
367///
368/// - `include_subject = Some(id)`: only that subject (blur-subject path).
369/// - `exclude_subject = Some(id)`: everyone except that subject (blur-others).
370/// - both `None`: all labeled appearances with the given intent.
371#[must_use]
372pub fn build_redaction_from_appearances(
373    appearances: &[Appearance],
374    include_subject: Option<SubjectId>,
375    exclude_subject: Option<SubjectId>,
376    intent: RedactionIntent,
377    tag: u32,
378    next_id: &mut u64,
379) -> Vec<RedactionInterval> {
380    let mut out = Vec::new();
381    for appearance in appearances {
382        let Some(subject_id) = appearance.subject_id else {
383            continue;
384        };
385        if let Some(want) = include_subject
386            && subject_id != want
387        {
388            continue;
389        }
390        if let Some(skip) = exclude_subject
391            && subject_id == skip
392        {
393            continue;
394        }
395        let id = RedactionIntervalId(*next_id);
396        *next_id = next_id.saturating_add(1);
397        out.push(RedactionInterval {
398            interval_id: id,
399            subject_id: Some(subject_id),
400            source_id: appearance.source_id,
401            track_id: appearance.track_id,
402            start: appearance.start,
403            end: appearance.end,
404            intent,
405            evidence: appearance.evidence,
406            mask_ref: 0,
407            peak_confidence: appearance.peak_confidence,
408            appearance_id: Some(appearance.appearance_id),
409            tag,
410        });
411    }
412    out
413}
414
415/// Builds redaction rows from explicit host-provided interval specs.
416#[must_use]
417pub fn build_redaction_from_specs(
418    specs: &[RedactionSpec],
419    next_id: &mut u64,
420) -> Vec<RedactionInterval> {
421    specs
422        .iter()
423        .map(|spec| {
424            let id = RedactionIntervalId(*next_id);
425            *next_id = next_id.saturating_add(1);
426            RedactionInterval {
427                interval_id: id,
428                subject_id: spec.subject_id,
429                source_id: spec.source_id,
430                track_id: spec.track_id,
431                start: spec.start,
432                end: spec.end,
433                intent: spec.intent,
434                evidence: spec.evidence,
435                mask_ref: spec.mask_ref,
436                peak_confidence: spec.peak_confidence,
437                appearance_id: None,
438                tag: spec.tag,
439            }
440        })
441        .collect()
442}
443
444/// Host / re-id input for one provenance interval (no auto appearance link).
445#[derive(Clone, Copy, Debug, PartialEq)]
446pub struct RedactionSpec {
447    /// Subject in focus.
448    pub subject_id: Option<SubjectId>,
449    /// Source.
450    pub source_id: SourceId,
451    /// Track when known.
452    pub track_id: Option<TrackId>,
453    /// Start.
454    pub start: MediaTime,
455    /// End.
456    pub end: MediaTime,
457    /// Intent.
458    pub intent: RedactionIntent,
459    /// Evidence handle.
460    pub evidence: Option<sightloom_core::EvidenceRef>,
461    /// Mask handle.
462    pub mask_ref: u64,
463    /// Peak score / confidence.
464    pub peak_confidence: f32,
465    /// Host tag.
466    pub tag: u32,
467}
468
469/// Replaces `index.redaction_intervals` with `rows` (idempotent assign).
470pub fn set_redaction_intervals(index: &mut VisionIndex, rows: Vec<RedactionInterval>) {
471    index.redaction_intervals = rows;
472}
473
474/// Appends rows to the redaction table.
475pub fn append_redaction_intervals(index: &mut VisionIndex, rows: Vec<RedactionInterval>) {
476    index.redaction_intervals.extend(rows);
477}
478
479#[cfg(test)]
480mod tests {
481    use super::*;
482    use crate::TrackSample;
483    use sightloom_core::{SourceId, SubjectId, TrackId};
484
485    fn sample(subject: u64, source: u32, track: u32, ticks: i64, conf: f32) -> TrackSample {
486        TrackSample {
487            sample_id: 0,
488            supersedes: None,
489            revision: 0,
490            idempotency_key: 0,
491            source_id: SourceId(source),
492            frame_index: u64::try_from(ticks).unwrap_or(0),
493            pts: MediaTime::new(ticks, 30).unwrap(),
494            track_id: TrackId(track),
495            track_uid: None,
496            subject_id: Some(SubjectId(subject)),
497            class_id: None,
498            left: 0.0,
499            top: 0.0,
500            right: 1.0,
501            bottom: 1.0,
502            confidence: conf,
503            mask_ref: 0,
504        }
505    }
506
507    #[test]
508    fn gap_splits_appearances_and_merges_visits() {
509        let samples = vec![
510            sample(1, 1, 1, 0, 0.9),
511            sample(1, 1, 1, 1, 0.95),   // same appearance (~33ms)
512            sample(1, 1, 1, 100, 0.8),  // big gap → new appearance
513            sample(1, 2, 2, 101, 0.85), // other source, near in time → same visit if gap large
514        ];
515        let mut next_a = 1;
516        let config = MemoryBuildConfig {
517            appearance_gap_ns: 50_000_000, // ~1.5 frames at 30fps
518            visit_gap_ns: 10_000_000_000,
519            require_subject: true,
520        };
521        let appearances = build_appearances(&samples, config, &mut next_a);
522        assert_eq!(appearances.len(), 3);
523        assert!((appearances[0].peak_confidence - 0.95).abs() < 1e-5);
524
525        let mut next_v = 1;
526        let visits = build_visits(&appearances, config, &mut next_v);
527        // All three appearances merge into one visit (within 10s).
528        assert_eq!(visits.len(), 1);
529        assert_eq!(visits[0].source_count, 2);
530        assert_eq!(visits[0].subject_id, Some(SubjectId(1)));
531    }
532
533    #[test]
534    fn subject_profiles_and_redaction_from_appearances() {
535        let mut index = VisionIndex::new("profiles");
536        index.push_track(sample(7, 1, 1, 0, 0.9));
537        index.push_track(sample(7, 1, 1, 1, 0.95));
538        index.push_track(sample(9, 1, 2, 2, 0.8));
539        let mut next_a = 1;
540        let config = MemoryBuildConfig {
541            appearance_gap_ns: 2_000_000_000,
542            visit_gap_ns: 10_000_000_000,
543            require_subject: true,
544        };
545        let mut next_v = 1;
546        let _ = rebuild_memory_entities(&mut index, config, &mut next_a, &mut next_v);
547        index.subjects.push(SubjectProfile {
548            subject_id: SubjectId(7),
549            label: Some("alice".into()),
550            appearance_count: 0,
551            source_count: 0,
552            total_duration_ns: 0,
553            first_seen: None,
554            last_seen: None,
555            embedding: None,
556        });
557        let n = rebuild_subject_profiles(&mut index);
558        assert_eq!(n, 2);
559        let alice = index
560            .subjects
561            .iter()
562            .find(|p| p.subject_id == SubjectId(7))
563            .unwrap();
564        assert_eq!(alice.label.as_deref(), Some("alice"));
565        assert!(alice.appearance_count >= 1);
566        assert_eq!(alice.source_count, 1);
567
568        let mut next_r = 1;
569        let blur = build_redaction_from_appearances(
570            &index.appearances,
571            Some(SubjectId(7)),
572            None,
573            RedactionIntent::BlurSubject,
574            0,
575            &mut next_r,
576        );
577        assert!(!blur.is_empty());
578        assert_eq!(blur[0].intent, RedactionIntent::BlurSubject);
579        assert_eq!(blur[0].subject_id, Some(SubjectId(7)));
580
581        let others = build_redaction_from_appearances(
582            &index.appearances,
583            None,
584            Some(SubjectId(7)),
585            RedactionIntent::BlurOthers,
586            1,
587            &mut next_r,
588        );
589        assert!(others.iter().all(|r| r.subject_id != Some(SubjectId(7))));
590        assert!(!others.is_empty());
591    }
592}