nv-view 0.1.0

PTZ/view-state, camera motion modeling, epoch policy, and context validity 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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

//! Transition phase state machine for camera motion events.

/// Where in a camera motion transition the current frame sits.
///
/// This is a strict state machine updated every frame by the view system.
///
/// ## State transitions
///
/// | Previous | Current motion | Next |
/// |---|---|---|
/// | `Settled` | `Stable` | `Settled` |
/// | `Settled` | `Moving`/`Unknown` | `MoveStart` |
/// | `MoveStart` | `Moving`/`Unknown` | `Moving` |
/// | `MoveStart` | `Stable` | `MoveEnd` |
/// | `Moving` | `Moving`/`Unknown` | `Moving` |
/// | `Moving` | `Stable` | `MoveEnd` |
/// | `MoveEnd` | `Stable` | `Settled` |
/// | `MoveEnd` | `Moving`/`Unknown` | `MoveStart` |
///
/// `MoveStart` and `MoveEnd` each last exactly one frame (edge-triggered).
/// `Settled` and `Moving` persist across multiple frames (level-triggered).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum TransitionPhase {
    /// No transition in progress. Camera is (or has been) stable.
    Settled,
    /// First frame of detected motion.
    MoveStart,
    /// Camera is mid-move.
    Moving,
    /// First frame of detected stability after motion.
    MoveEnd,
}

impl TransitionPhase {
    /// Compute the next phase given the current motion state.
    ///
    /// `is_moving` should be `true` if the camera motion state is
    /// `Moving` or `Unknown` (conservative: unknown = potentially moving).
    #[must_use]
    pub fn next(self, is_moving: bool) -> Self {
        match (self, is_moving) {
            (Self::Settled, false) => Self::Settled,
            (Self::Settled, true) => Self::MoveStart,
            (Self::MoveStart, true) => Self::Moving,
            (Self::MoveStart, false) => Self::MoveEnd,
            (Self::Moving, true) => Self::Moving,
            (Self::Moving, false) => Self::MoveEnd,
            (Self::MoveEnd, false) => Self::Settled,
            (Self::MoveEnd, true) => Self::MoveStart,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn settled_stays_settled() {
        assert_eq!(
            TransitionPhase::Settled.next(false),
            TransitionPhase::Settled
        );
    }

    #[test]
    fn settled_to_move_start() {
        assert_eq!(
            TransitionPhase::Settled.next(true),
            TransitionPhase::MoveStart
        );
    }

    #[test]
    fn move_start_to_moving() {
        assert_eq!(
            TransitionPhase::MoveStart.next(true),
            TransitionPhase::Moving
        );
    }

    #[test]
    fn move_start_one_frame_jitter() {
        assert_eq!(
            TransitionPhase::MoveStart.next(false),
            TransitionPhase::MoveEnd
        );
    }

    #[test]
    fn moving_to_move_end() {
        assert_eq!(
            TransitionPhase::Moving.next(false),
            TransitionPhase::MoveEnd
        );
    }

    #[test]
    fn move_end_to_settled() {
        assert_eq!(
            TransitionPhase::MoveEnd.next(false),
            TransitionPhase::Settled
        );
    }

    #[test]
    fn move_end_resume_motion() {
        assert_eq!(
            TransitionPhase::MoveEnd.next(true),
            TransitionPhase::MoveStart
        );
    }

    #[test]
    fn full_cycle() {
        let mut phase = TransitionPhase::Settled;
        phase = phase.next(true); // MoveStart
        assert_eq!(phase, TransitionPhase::MoveStart);
        phase = phase.next(true); // Moving
        assert_eq!(phase, TransitionPhase::Moving);
        phase = phase.next(true); // Moving
        assert_eq!(phase, TransitionPhase::Moving);
        phase = phase.next(false); // MoveEnd
        assert_eq!(phase, TransitionPhase::MoveEnd);
        phase = phase.next(false); // Settled
        assert_eq!(phase, TransitionPhase::Settled);
    }
}