nv_perception/
temporal_access.rs

1//! Typed temporal-access contract for stages.
2//!
3//! [`TemporalAccess`] defines the read-only interface that stages use to
4//! query track history and temporal state. It lives in `nv-perception` (not
5//! `nv-temporal`) so that stages can depend on it without a circular
6//! dependency: `nv-temporal` implements `TemporalAccess` for its snapshot
7//! type, and `nv-perception` never imports from `nv-temporal`.
8
9use nv_core::{MonotonicTs, TrackId};
10use nv_view::ViewEpoch;
11
12use crate::track::{Track, TrackObservation};
13
14/// Read-only access to temporal state for stages.
15///
16/// Implemented by `nv_temporal::TemporalStoreSnapshot`. The runtime passes
17/// a `&dyn TemporalAccess` through [`StageContext::temporal`](super::StageContext).
18///
19/// Stages that need track history, observation windows, or view-epoch context
20/// program against this trait, keeping them decoupled from the concrete
21/// temporal store implementation.
22pub trait TemporalAccess: Send + Sync {
23    /// View epoch at the time this snapshot was taken.
24    fn view_epoch(&self) -> ViewEpoch;
25
26    /// Number of tracks in the snapshot.
27    fn track_count(&self) -> usize;
28
29    /// All track IDs in the snapshot.
30    ///
31    /// The order is unspecified. Callers that need a stable iteration
32    /// order should collect and sort.
33    fn track_ids(&self) -> Vec<TrackId>;
34
35    /// Look up a track's current state by ID.
36    ///
37    /// Returns `None` if the track is not present in the snapshot.
38    fn get_track(&self, id: &TrackId) -> Option<&Track>;
39
40    /// Return the most recent observations for a track, ordered oldest-first.
41    ///
42    /// Returns an empty slice if the track is not present or has no
43    /// recorded observations.
44    fn recent_observations(&self, id: &TrackId) -> &[TrackObservation];
45
46    /// Timestamp when a track was first seen.
47    ///
48    /// Returns `None` if the track is not present.
49    fn first_seen(&self, id: &TrackId) -> Option<MonotonicTs>;
50
51    /// Timestamp of the most recent observation for a track.
52    ///
53    /// Returns `None` if the track is not present.
54    fn last_seen(&self, id: &TrackId) -> Option<MonotonicTs>;
55
56    /// Total trajectory points for a track across all segments.
57    ///
58    /// Returns 0 if the track is not present.
59    fn trajectory_point_count(&self, id: &TrackId) -> usize;
60
61    /// Number of trajectory segments for a track.
62    ///
63    /// Returns 0 if the track is not present.
64    fn trajectory_segment_count(&self, id: &TrackId) -> usize;
65}
nv_perception/temporal_access.rs

nv_perception/
temporal_access.rs
