nv-perception 0.1.0

Stage model, detection/track types, perception artifacts, and derived signals for the NextVision runtime.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

//! Typed temporal-access contract for stages.
//!
//! [`TemporalAccess`] defines the read-only interface that stages use to
//! query track history and temporal state. It lives in `nv-perception` (not
//! `nv-temporal`) so that stages can depend on it without a circular
//! dependency: `nv-temporal` implements `TemporalAccess` for its snapshot
//! type, and `nv-perception` never imports from `nv-temporal`.

use nv_core::{MonotonicTs, TrackId};
use nv_view::ViewEpoch;

use crate::track::{Track, TrackObservation};

/// Read-only access to temporal state for stages.
///
/// Implemented by `nv_temporal::TemporalStoreSnapshot`. The runtime passes
/// a `&dyn TemporalAccess` through [`StageContext::temporal`](super::StageContext).
///
/// Stages that need track history, observation windows, or view-epoch context
/// program against this trait, keeping them decoupled from the concrete
/// temporal store implementation.
pub trait TemporalAccess: Send + Sync {
    /// View epoch at the time this snapshot was taken.
    fn view_epoch(&self) -> ViewEpoch;

    /// Number of tracks in the snapshot.
    fn track_count(&self) -> usize;

    /// All track IDs in the snapshot.
    ///
    /// The order is unspecified. Callers that need a stable iteration
    /// order should collect and sort.
    fn track_ids(&self) -> Vec<TrackId>;

    /// Look up a track's current state by ID.
    ///
    /// Returns `None` if the track is not present in the snapshot.
    fn get_track(&self, id: &TrackId) -> Option<&Track>;

    /// Return the most recent observations for a track, ordered oldest-first.
    ///
    /// Returns an empty slice if the track is not present or has no
    /// recorded observations.
    fn recent_observations(&self, id: &TrackId) -> &[TrackObservation];

    /// Timestamp when a track was first seen.
    ///
    /// Returns `None` if the track is not present.
    fn first_seen(&self, id: &TrackId) -> Option<MonotonicTs>;

    /// Timestamp of the most recent observation for a track.
    ///
    /// Returns `None` if the track is not present.
    fn last_seen(&self, id: &TrackId) -> Option<MonotonicTs>;

    /// Total trajectory points for a track across all segments.
    ///
    /// Returns 0 if the track is not present.
    fn trajectory_point_count(&self, id: &TrackId) -> usize;

    /// Number of trajectory segments for a track.
    ///
    /// Returns 0 if the track is not present.
    fn trajectory_segment_count(&self, id: &TrackId) -> usize;
}